docs: standardize the phrases for --help and --version in all man pages

[thirdparty/util-linux.git] / sys-utils / flock.1

diff --git a/sys-utils/flock.1 b/sys-utils/flock.1
index 5a6f27fbbdb052d409c84ce55e19ad3d579ace46..d9f7d86e70af9e25cea7abc84b7982a78ba47182 100644 (file)
--- a/sys-utils/flock.1
+++ b/sys-utils/flock.1
@@ -29,10 +29,10 @@
 flock \- manage locks from shell scripts
 .SH SYNOPSIS
 .B flock
-[options] <file> -c <command>
+[options] <file|directory> <command> [command args]
 .br
 .B flock
-[options] <directory> -c <command>
+[options] <file|directory> -c <command>
 .br
 .B flock
 [options] <file descriptor number>
@@ -71,13 +71,19 @@ cases, for example if the enclosed command group may have forked a background
 process which should not be holding the lock.
 .TP
 \fB\-n\fP, \fB\-\-nb\fP, \fB\-\-nonblock\fP
-Fail (with an exit code of 1) rather than wait if the lock cannot be
+Fail rather than wait if the lock cannot be
 immediately acquired.
+See the
+.I \-E
+option for the exit code used.
 .TP
 \fB\-w\fP, \fB\-\-wait\fP, \fB\-\-timeout\fP \fIseconds\fP
-Fail (with an exit code of 1) if the lock cannot be acquired within
+Fail if the lock cannot be acquired within
 .IR seconds .
 Decimal fractional values are allowed.
+See the
+.I \-E
+option for the exit code used.
 .TP
 \fB\-o\fP, \fB\-\-close\fP
 Close the file descriptor on which the lock is held before executing
@@ -86,6 +92,11 @@ This is useful if
 .B command
 spawns a child process which should not be holding the lock.
 .TP
+\fB\-E\fP, \fB\-\-conflict\-exit\-code\fP \fInumber\fP
+The exit code used when the \fB\-n\fP option is in use, and the
+conflicting lock exists, or the \fB\-w\fP option is in use,
+and the timeout is reached. The default value is 1.
+.TP
 \fB\-c\fP, \fB\-\-command\fP \fIcommand\fP
 Pass a single
 .IR command ,
@@ -93,9 +104,9 @@ without arguments, to the shell with
 .BR -c .
 .TP
 \fB\-h\fP, \fB\-\-help\fP
-Print a help message.
+Display help text and exit.
 .IP "\fB\-V, \-\-version\fP"
-Show version number and exit.
+Display version information and exit.
 .SH EXAMPLES
 .TP
 shell1> flock /tmp -c cat
@@ -109,6 +120,9 @@ 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.
 .TP
+shell> flock -x local-lock-file echo 'a b c'
+Grab the exclusive lock "local-lock-file" before running echo with 'a b c'.
+.TP
 (
 .TQ
   flock -n 9 || exit 1
@@ -127,6 +141,14 @@ allows the lockfile to be created if it does not already exist, however,
 write permission is required.  Using
 .I <
 requires that the file already exists but only read permission is required.
+.TP
+[ "${FLOCKER}" != "$0" ] && exec env FLOCKER="$0" flock -en "$0" "$0" "$@" || :
+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.
 .SH "EXIT STATUS"
 The command uses
 .B sysexits.h
@@ -134,7 +156,9 @@ return values for everything else but an options
 .I \-n
 or
 .I \-w
-failures which return 1.
+failures which return either the value given by the
+.I \-E
+option, or 1 by default.
 .SH AUTHOR
 .UR hpa@zytor.com
 H. Peter Anvin