docs: restructure flock.1 manual page

The commit aligns manual page with howto-man-page.txt, and adds example
section which I hope makes usage of this command easier.

Signed-off-by: Sami Kerola <kerolasa@iki.fi>

1 files changed, 82 insertions, 42 deletions

diff --git a/sys-utils/flock.1 b/sys-utils/flock.1
index 4f0332a70..84bc96fc4 100644
--- a/sys-utils/flock.1
+++ b/sys-utils/flock.1
@@ -1,5 +1,5 @@
 .\" -----------------------------------------------------------------------
-.\"   
+.\"
 .\"   Copyright 2003-2006 H. Peter Anvin - All Rights Reserved
 .\"
 .\"   Permission is hereby granted, free of charge, to any person
@@ -10,10 +10,10 @@
 .\"   sell copies of the Software, and to permit persons to whom
 .\"   the Software is furnished to do so, subject to the following
 .\"   conditions:
-.\"   
+.\"
 .\"   The above copyright notice and this permission notice shall
 .\"   be included in all copies or substantial portions of the Software.
-.\"   
+.\"
 .\"   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 .\"   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 .\"   OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
@@ -24,47 +24,37 @@
 .\"   OTHER DEALINGS IN THE SOFTWARE.
 .\"
 .\" -----------------------------------------------------------------------
-.TH FLOCK 1 "February 2006" "util-linux" "User Commands"
+.TH FLOCK 1 "September 2011" "util-linux" "User Commands"
 .SH NAME
 flock \- manage locks from shell scripts
 .SH SYNOPSIS
-\fBflock\fP [\fB\-sxon\fP] [\fB\-w\fP \fItimeout\fP] \fIlockfile\fP [\fB\-c\fP] \fIcommand...\fP
-.PP
-\fBflock\fP [\fB\-sxon\fP] [\fB\-w\fP \fItimeout\fP] \fIlockdir\fP [\fB\-c\fP] \fIcommand...\fP
-.PP
-\fBflock\fP [\fB\-sxun\fP] [\fB\-w\fP \fItimeout\fP] \fIfd\fP
+.B flock
+[options] <file> -c <command>
+.br
+.B flock
+[options] <directory> -c <command>
+.br
+.B flock
+[options] <file descriptor number>
 .SH DESCRIPTION
 .PP
 This utility manages
 .BR flock (2)
 locks from within shell scripts or the command line.
 .PP
-The first and second forms wraps the lock around the executing a command, in a manner similar to
+The first and second forms wraps the lock around the executing a command, in
+a manner similar to
 .BR su (1)
 or
 .BR newgrp (1).
-It locks a specified file or directory, which is created (assuming appropriate
-permissions), if it does not already exist.
-.PP
-The third form is convenient inside shell scripts, and is usually
-used the following manner:
-.PP
-\fC(
-.br
-  flock -n 9 || exit 1
-.br
-  # ... commands executed under lock ...
-.br
-) 9>/var/lock/mylockfile\fP
-.PP
-The mode used to open the file doesn't matter to \fBflock\fP; using
-\fC>\fP or \fP>>\fP allows the lockfile to be created if it does not
-already exist, however, write permission is required; using \fC<\fP
-requires that the file already exists but only read permission is
-required.
-.PP
-By default, if the lock cannot be immediately acquired, \fBflock\fP
+It locks a specified file or directory, which is created (assuming
+appropriate permissions), if it does not already exist.  By default, if the
+lock cannot be immediately acquired,
+.B flock
 waits until the lock is available.
+.PP
+The third form uses open file by file descriptor number.  See examples how
+that can used.
 .SH OPTIONS
 .TP
 \fB\-s\fP, \fB\-\-shared\fP
@@ -75,11 +65,10 @@ Obtain an exclusive lock, sometimes called a write lock.  This is the
 default.
 .TP
 \fB\-u\fP, \fB\-\-unlock\fP
-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.
+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.
 .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
@@ -87,20 +76,69 @@ immediately acquired.
 .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
-\fIseconds\fP seconds.  Decimal fractional values are allowed.
+.IR seconds .
+Decimal fractional values are allowed.
 .TP
 \fB\-o\fP, \fB\-\-close\fP
 Close the file descriptor on which the lock is held before executing
-\fIcommand\fP.  This is useful if \fIcommand\fP spawns a child process
-which should not be holding the lock.
+.BR command\ .
+This is useful if
+.B command
+spawns a child process which should not be holding the lock.
 .TP
 \fB\-c\fP, \fB\-\-command\fP \fIcommand\fP
-Pass a single \fIcommand\fP to the shell with \fB\-c\fP.
+Pass a single
+.IR command ,
+without arguments, to the shell with
+.BR -c .
 .TP
 \fB\-h\fP, \fB\-\-help\fP
 Print a help message.
+.IP "\fB\-V, \-\-version\fP"
+Show version number and exit.
+.SH EXAMPLES
+.TP
+shell1> flock /tmp -c cat
+.TQ
+shell2> flock -w .007 /tmp -c echo; /bin/echo $?
+Set exclusive lock to directory /tmp and the second command will fail.
+.TP
+shell1> flock -s /tmp -c cat
+.TQ
+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
+(
+.TQ
+  flock -n 9 || exit 1
+.TQ
+  # ... commands executed under lock ...
+.TQ
+) 9>/var/lock/mylockfile
+The form is convenient inside shell scripts.  The mode used to open the file
+doesn't matter to
+.BR flock ;
+using
+.I >
+or
+.I >>
+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.
+.SH "EXIT STATUS"
+The command uses
+.B sysexits.h
+return values for everything else but an options
+.I \-n
+or
+.I \-w
+failures which return 1.
 .SH AUTHOR
-Written by H. Peter Anvin <hpa@zytor.com>.
+.UR hpa@zytor.com
+H. Peter Anvin
+.UE
 .SH COPYRIGHT
 Copyright \(co 2003\-2006 H. Peter Anvin.
 .br
@@ -110,4 +148,6 @@ warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 .BR flock (2)
 .SH AVAILABILITY
 The flock command is part of the util-linux package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
+.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .