Imported Upstream version 2.22upstream/2.22upstream

1 files changed, 166 insertions, 0 deletions

diff --git a/sys-utils/flock.1 b/sys-utils/flock.1
new file mode 100644
index 0000000..b50c619
--- /dev/null
+++ b/sys-utils/flock.1
@@ -0,0 +1,166 @@
+.\" -----------------------------------------------------------------------
+.\"
+.\"   Copyright 2003-2006 H. Peter Anvin - All Rights Reserved
+.\"
+.\"   Permission is hereby granted, free of charge, to any person
+.\"   obtaining a copy of this software and associated documentation
+.\"   files (the "Software"), to deal in the Software without
+.\"   restriction, including without limitation the rights to use,
+.\"   copy, modify, merge, publish, distribute, sublicense, and/or
+.\"   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
+.\"   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+.\"   HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+.\"   WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+.\"   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+.\"   OTHER DEALINGS IN THE SOFTWARE.
+.\"
+.\" -----------------------------------------------------------------------
+.TH FLOCK 1 "September 2011" "util-linux" "User Commands"
+.SH NAME
+flock \- manage locks from shell scripts
+.SH SYNOPSIS
+.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 wrap 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.  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 be used.
+.SH OPTIONS
+.TP
+\fB\-s\fP, \fB\-\-shared\fP
+Obtain a shared lock, sometimes called a read lock.
+.TP
+\fB\-x\fP, \fB\-e\fP, \fB\-\-exclusive\fP
+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.
+.TP
+\fB\-n\fP, \fB\-\-nb\fP, \fB\-\-nonblock\fP
+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 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
+.BR command\ .
+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 ,
+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 either the value given by the
+.I \-E
+option, or 1 by default.
+.SH AUTHOR
+.UR hpa@zytor.com
+H. Peter Anvin
+.UE
+.SH COPYRIGHT
+Copyright \(co 2003\-2006 H. Peter Anvin.
+.br
+This is free software; see the source for copying conditions.  There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.SH "SEE ALSO"
+.BR flock (2)
+.SH AVAILABILITY
+The flock command is part of the util-linux package and is available from
+.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .