From: Mike Frysinger <vapier@gentoo.org>
Date: Wed, 26 Dec 2012 20:10:29 +0000 (-0500)
Subject: flock: improve usage strings
X-Git-Tag: v2.23-rc1~378
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=295dd90226852a1f3b3dd108ed01dd1d7da92240;p=thirdparty%2Futil-linux.git

flock: improve usage strings

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>
---

diff --git a/sys-utils/flock.1 b/sys-utils/flock.1
index b50c619cf3..b28526f692 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 b514155299..50435e0ecb 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);