.\" $Id: flock.man,v 2.9 2012/10/15 13:27:14 ksb Exp $
.\" by Kevin Braunsdorf and Matthew Bradburn
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -man -Tascii %f | ${PAGER:-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man1/flock.1
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]1/flock.1*
.TH FLOCK 1 LOCAL
.SH NAME
flock - lock a file to synchronize command streams
.SH SYNOPSIS
.ds PN "flock
\fB\*(PN\fP [\fB\-cfn\fP] [\fB\-EX\fP|\fBSH\fP|\fBUN\fP|\fBNB\fP] \fIfile\fP|\fIfd\fP [\fIcmd\fP]
.br
\fB\*(PN\fP \fB\-h\fP
.br
\fB\*(PN\fP \fB\-V\fP
.SH DESCRIPTION
Flock applies or removes an advisory lock on the named file or file descriptor.
Advisory locks allow cooperating processes to perform consistent operations
on files or synchronize other atomic operations, see \fI\*(PN\fP(2).
.PP
When \fB\*(PN\fP succeeds, the exit status from the \fI\*(PN\fP command is
the exit status of its child.  The default \fIcmd\fP is ``/bin/true'' so
that by default \fI\*(PN\fP succeeds.  \fIFlock\fP exits nonzero
when it cannot lock \fIfile\fP, or when the specified \fIfile\fP
(\fIfd\fP) cannot be (isn't) opened.
.PP
It \fB\*(PN\fP has to open the file to get the lock it will not pass
the created file descriptor to the child process.  (Said process might
unlock the descriptor.)  If the named file is all numeric the \fB\-f\fP
option may be used to force it to be interpreted as a file name.
.SH OPTIONS
.TP
.BI \-c
Create the lock file if it doesn't exist.
.TP
.BI \-f
The given \fIfile\fP is a file name, even if consists of all digits.
.TP
.BI \-h
Give a brief help message.
.TP
.BI \-n
Do not create the lock file if it doesn't exist.  This is the default.
.TP
.BI \-EX
Set or reset the LOCK_EX bit in the arguments to \fBflock\fP(2).
This is the default if no locking bits are given.
.TP
.BI \-NB
Set or reset the LOCK_NB bit in the arguments to \fBflock\fP(2).
.TP
.BI \-SH
Set or reset the LOCK_SH bit in the arguments to \fBflock\fP(2).
.TP
.BI \-UN
Set or reset the LOCK_UN bit in the arguments to \fBflock\fP(2).
This option is only useful when a file descriptor is given as the
\fIfile\fP on which to operate.
.TP
.BI \-V
Output the version of \fB\*(PN\fP installed.
.PP
The option \fB\-EX\fP may be spelled \fB\-LOCK_EX\fP, likewise the other
locking bits may be spelled more verbosely.
.PP
The locking bits may be inclusive or'ed together with a pipe (`|'), which
must be quoted from the shell.
.SH EXAMPLES
.TP
.nf
\*(PN \-EX 1 echo \*(lqsomething important\*(rq >>daemon.log
.fi
Avoid interlaminate writes to the log by
locking the log file before each write.
.TP
.nf
\*(PN \-EX 1 sh \-c "doit1 ; doit2; doit3"
.fi
Run three sequential tasks under the same lock on \fIstdout\fP
.TP
.nf
\*(PN share.c ${VISUAL:-vi} share.c
.fi
To edit a shared source file.  Now days most editors lock the
file for you, so you don't need this anymore.
.TP
.nf
flock ~monitor su monitor
.fi
Substitute user to "monitor" while holding a lock on her
home directory.  This is a primative way to keep administators
from accessing the same pseudo-user account in parallel.
.TP
.nf
alias lockdir='exec 7<. && flock \-NB \-EX 0 0<&7 2>/dev/null || \e
	echo "${0#\-}: $PWD: already locked" && false'
.fi
A \fBksh\fP alias to lock the current working directory, if possible.
.TP
.nf
alias unlockdir='exec 7<&\-'
.fi
Unlock a directory locked by the alias above.

.SH BUGS
On some not-quite UNIX systems the \fBflock\fP(2) call is emulated
with \fBlockf\fP(3) which doesn't allow locking of read-only
nodes (like directories).  This is a real loss to the community,
as locks on directories make life much safer for some updates.

.SH AUTHOR
KS Braunsdorf
.br
NonPlayer Character Guild
.br
install at ksb \-snip~me- npcguild.org

.SH "SEE ALSO"
.hlm 0
sh(1), true(1), flock(2), open(2), xapply(1l), lockf(3)