[PATCH] flock: improve usage strings

Mike Frysinger
2012-12-26T20:09:51Z

The current examples miss the best usage of all: specifying the command
and its arguments directly on the command line. Add that to both the
program usage and the man page.

Signed-off-by: Mike Frysinger <vapier@gentoo.org>
---
sys-utils/flock.1 | 15 +++++++++++++--
sys-utils/flock.c | 6 +++---
2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/sys-utils/flock.1 b/sys-utils/flock.1
index b50c619..b28526f 100644
--- 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>
@@ -120,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
@@ -138,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
diff --git a/sys-utils/flock.c b/sys-utils/flock.c
index b514155..50435e0 100644
--- a/sys-utils/flock.c
+++ b/sys-utils/flock.c
@@ -48,9 +48,9 @@ static void __attribute__((__noreturn__)) usage(int ex)
{
fprintf(stderr, USAGE_HEADER);
fprintf(stderr,
- _(" %1$s [options] <file descriptor number>\n"
- " %1$s [options] <file> -c <command>\n"
- " %1$s [options] <directory> -c <command>\n"),
+ _(" %1$s [options] <file|directory> <command> [command args]\n"
+ " %1$s [options] <file|directory> -c <command>\n"
+ " %1$s [options] <file descriptor number>\n"),
program_invocation_short_name);
fputs(USAGE_OPTIONS, stderr);
fputs(_( " -s --shared get a shared lock\n"), stderr);
--
1.8.0