270 lines
7.0 KiB
HTML
270 lines
7.0 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of FLOCK</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>FLOCK</H1>
|
|
Section: User Commands (1)<BR>Updated: July 2014<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
flock - manage locks from shell scripts
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>flock</B>
|
|
|
|
[options]
|
|
<I>file</I>|<I>directory command </I>[<I>arguments</I>]
|
|
|
|
<BR>
|
|
|
|
<B>flock</B>
|
|
|
|
[options]
|
|
<I>file</I>|<I>directory</I>
|
|
|
|
<B>-c</B><I> command</I>
|
|
|
|
<BR>
|
|
|
|
<B>flock</B>
|
|
|
|
[options]<I> number</I>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<P>
|
|
|
|
This utility manages
|
|
<B><A HREF="/cgi-bin/man/man2html?2+flock">flock</A></B>(2)
|
|
|
|
locks from within shell scripts or from the command line.
|
|
<P>
|
|
|
|
The first and second of the above forms wrap the lock around the execution of a
|
|
<I>command</I>,
|
|
|
|
in a manner similar to
|
|
<B><A HREF="/cgi-bin/man/man2html?1+su">su</A></B>(1)
|
|
|
|
or
|
|
<B><A HREF="/cgi-bin/man/man2html?1+newgrp">newgrp</A></B>(1).
|
|
|
|
They lock a specified <I>file</I> or <I>directory</I>, which is created (assuming
|
|
appropriate permissions) if it does not already exist. By default, if the
|
|
lock cannot be immediately acquired,
|
|
<B>flock</B>
|
|
|
|
waits until the lock is available.
|
|
<P>
|
|
|
|
The third form uses an open file by its file descriptor <I>number</I>.
|
|
See the examples below for how that can be used.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1"><B>-c</B>,<B> --command </B><I>command</I>
|
|
|
|
<DD>
|
|
Pass a single <I>command</I>, without arguments, to the shell with
|
|
<B>-c</B>.
|
|
|
|
<DT id="2"><B>-E</B>,<B> --conflict-exit-code </B><I>number</I>
|
|
|
|
<DD>
|
|
The exit code used when the <B>-n</B> option is in use, and the
|
|
conflicting lock exists, or the <B>-w</B> option is in use,
|
|
and the timeout is reached. The default value is <B>1</B>.
|
|
<DT id="3"><B>-F</B>,<B> --no-fork</B>
|
|
|
|
<DD>
|
|
Do not fork before executing
|
|
<I>command</I>.
|
|
|
|
Upon execution the flock process is replaced by
|
|
<I>command</I>
|
|
|
|
which continues to hold the lock. This option is incompatible with
|
|
<B>--close</B> as there would otherwise be nothing left to hold the lock.
|
|
<DT id="4"><B>-e</B>,<B> -x</B>,<B> --exclusive</B>
|
|
|
|
<DD>
|
|
Obtain an exclusive lock, sometimes called a write lock. This is the
|
|
default.
|
|
<DT id="5"><B>-n</B>,<B> --nb</B>,<B> --nonblock</B>
|
|
|
|
<DD>
|
|
Fail rather than wait if the lock cannot be
|
|
immediately acquired.
|
|
See the
|
|
<B>-E</B>
|
|
|
|
option for the exit code used.
|
|
<DT id="6"><B>-o</B>,<B> --close</B>
|
|
|
|
<DD>
|
|
Close the file descriptor on which the lock is held before executing
|
|
<I>command</I>.
|
|
|
|
This is useful if
|
|
<I>command</I>
|
|
|
|
spawns a child process which should not be holding the lock.
|
|
<DT id="7"><B>-s</B>,<B> --shared</B>
|
|
|
|
<DD>
|
|
Obtain a shared lock, sometimes called a read lock.
|
|
<DT id="8"><B>-u</B>,<B> --unlock</B>
|
|
|
|
<DD>
|
|
Drop a lock. This is usually not required, since a lock is automatically
|
|
dropped when the file is closed. However, it may be required in special
|
|
cases, for example if the enclosed command group may have forked a background
|
|
process which should not be holding the lock.
|
|
<DT id="9"><B>-w</B>,<B> --wait</B>,<B> --timeout </B><I>seconds</I>
|
|
|
|
<DD>
|
|
Fail if the lock cannot be acquired within
|
|
<I>seconds</I>.
|
|
|
|
Decimal fractional values are allowed.
|
|
See the
|
|
<B>-E</B>
|
|
|
|
option for the exit code used. The zero number of
|
|
<I>seconds</I>
|
|
|
|
is interpreted as <B>--nonblock</B>.
|
|
<DT id="10"><B>--verbose</B>
|
|
|
|
<DD>
|
|
Report how long it took to acquire the lock, or why the lock could not be
|
|
obtained.
|
|
<DT id="11"><B>-V</B>,<B> --version</B>
|
|
|
|
<DD>
|
|
Display version information and exit.
|
|
<DT id="12"><B>-h</B>,<B> --help</B>
|
|
|
|
<DD>
|
|
Display help text and exit.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="13">shell1> flock /tmp -c cat<DD>
|
|
|
|
shell2> flock -w .007 /tmp -c echo; /bin/echo $?
|
|
Set exclusive lock to directory /tmp and the second command will fail.
|
|
<DT id="14">shell1> flock -s /tmp -c cat<DD>
|
|
|
|
shell2> flock -s -w .007 /tmp -c echo; /bin/echo $?
|
|
Set shared lock to directory /tmp and the second command will not fail.
|
|
Notice that attempting to get exclusive lock with second command would fail.
|
|
<DT id="15">shell> flock -x local-lock-file echo 'a b c'<DD>
|
|
Grab the exclusive lock "local-lock-file" before running echo with 'a b c'.
|
|
<DT id="16">(<DD>
|
|
|
|
<BR> flock -n 9 || exit 1
|
|
|
|
<BR> # ... commands executed under lock ...
|
|
|
|
) 9>/var/lock/mylockfile
|
|
The form is convenient inside shell scripts. The mode used to open the file
|
|
doesn't matter to
|
|
<B>flock</B>;
|
|
|
|
using
|
|
<I>></I>
|
|
|
|
or
|
|
<I>>></I>
|
|
|
|
allows the lockfile to be created if it does not already exist, however,
|
|
write permission is required. Using
|
|
<I><</I>
|
|
|
|
requires that the file already exists but only read permission is required.
|
|
<DT id="17">[ "${FLOCKER}" != "$0" ] && exec env FLOCKER="$0" flock -en "$0" "$0" "$@" || :<DD>
|
|
This is useful boilerplate code for shell scripts. Put it at the top of the
|
|
shell script you want to lock and it'll automatically lock itself on the first
|
|
run. If the env var $FLOCKER is not set to the shell script that is being run,
|
|
then execute flock and grab an exclusive non-blocking lock (using the script
|
|
itself as the lock file) before re-execing itself with the right arguments. It
|
|
also sets the FLOCKER env var to the right value so it doesn't run again.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>EXIT STATUS</H2>
|
|
|
|
The command uses
|
|
<B>sysexits.h</B>
|
|
|
|
return values for everything, except when using either of the options
|
|
<B>-n</B>
|
|
|
|
or
|
|
<B>-w</B>
|
|
|
|
which report a failure to acquire the lock with a return value given by the
|
|
<B>-E</B>
|
|
|
|
option, or 1 by default.
|
|
<P>
|
|
|
|
When using the <I>command</I> variant, and executing the child worked, then
|
|
the exit status is that of the child command.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
H. Peter Anvin
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
Copyright © 2003-2006 H. Peter Anvin.
|
|
<BR>
|
|
|
|
This is free software; see the source for copying conditions. There is NO
|
|
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+flock">flock</A></B>(2)
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H2>AVAILABILITY</H2>
|
|
|
|
The flock command is part of the util-linux package and is available from
|
|
|
|
Linux Kernel Archive
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="18"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="19"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="20"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="21"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="22"><A HREF="#lbAF">EXAMPLES</A><DD>
|
|
<DT id="23"><A HREF="#lbAG">EXIT STATUS</A><DD>
|
|
<DT id="24"><A HREF="#lbAH">AUTHOR</A><DD>
|
|
<DT id="25"><A HREF="#lbAI">COPYRIGHT</A><DD>
|
|
<DT id="26"><A HREF="#lbAJ">SEE ALSO</A><DD>
|
|
<DT id="27"><A HREF="#lbAK">AVAILABILITY</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:12 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|