From e9da7722a01758d7e6fc06ff0fd6592929f9a81d Mon Sep 17 00:00:00 2001 From: Sami Kerola Date: Sun, 25 Sep 2011 13:00:15 +0200 Subject: 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 --- sys-utils/flock.1 | 124 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 82 insertions(+), 42 deletions(-) (limited to 'sys-utils/flock.1') 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] -c +.br +.B flock +[options] -c +.br +.B flock +[options] .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 . +.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 . -- cgit v1.2.3-55-g7522