From baf39af15b1fe8570e6430788ec7cd4959fbc5d9 Mon Sep 17 00:00:00 2001 From: Karel Zak Date: Thu, 7 Dec 2006 00:26:58 +0100 Subject: Imported from util-linux-2.13-pre2 tarball. --- sys-utils/flock.1 | 133 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 96 insertions(+), 37 deletions(-) (limited to 'sys-utils/flock.1') diff --git a/sys-utils/flock.1 b/sys-utils/flock.1 index e9cdb979a..4d12be2c1 100644 --- a/sys-utils/flock.1 +++ b/sys-utils/flock.1 @@ -1,47 +1,106 @@ -.TH FLOCK "1" "November 2004" "flock (util-linux)" "User Commands" +.\" $Id: flock.1,v 1.2 2005/07/09 21:34:44 hpa Exp $ +.\" ----------------------------------------------------------------------- +.\" +.\" Copyright 2003 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" "17 Mar 2003" "flock utility" "H. Peter Anvin" .SH NAME -flock \- acquire a file lock and then execute a command with the lock held +flock \- Manage locks from shell scripts .SH SYNOPSIS -.BR flock -.RB [ \-\-shared ] -.RB [ \-\-timeout=\fP\fIseconds\fP ] -.I lockfile command ... +\fBflock\fP [\fB\-sxon\fP] [\fB\-w\fP \fItimeout\fP] \fIlockfile\fP [\fB\-c\fP] \fIcommand...\fP +.PP +\fBflock\fP [\fB\-sxun\fP] [\fB\-w\fP \fItimeout\fP] \fIfd\fP .SH DESCRIPTION -.\" Add any additional description here .PP -Acquire a file lock using the flock(2) system call and then execute -the given command with the lock held. Depending on the options given, -the lock can be either exclusive or shared, and the behavior in the -event of lock contention can be specified as either waiting -indefinitely for the lock to become available (the default), or -failing if the lock does not become available after a specific time, -which can be specified as zero to make the command not wait at all. +This utility manages +.BR flock (2) +locks from within shell scripts or the command line. .PP -.TP -\fB\-\-shared\fR -Acquire a shared lock. Acquiring a shared lock does -not stop others from acquiring a shared lock, but it will stop others -from acquiring an exclusive lock. Conversely, acquiring an exclusive -lock (the default) stops both exclusive and shared attempts to acquire -the lock. Typically, a shared lock is used if a command is just going -to read the locked data, and an exclusive lock is used if the command -might write to it. -.TP -\fB\-\-timeout=n\fR -Abort if the lock cannot be acquired before \fIn\fR seconds. -For a completely non-blocking attempt to acquire a lock, specify -\fB\-\-timeout=0\fR. -The timer applies only to the attempt to acquire the lock. As soon -as the lock is acquired, the timeout is cancelled. The command to -be run is not subject to the timeout. +The first form 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, which is created (assuming appropriate +permissions), if it does not already exist. .PP -.SH "EXAMPLES (invoking some imaginary programs)" -.hl +The second form is conveninent inside shell scripts, and is usually +used the following manner: .PP -flock /etc/passwd read-and-write-to-passwd +\fC( +.br + flock -s 200 +.br + # ... commands executed under lock ... +.br +) 200>/var/lock/mylockfile\fP .PP -flock \-\-shared /etc/passwd just-read-something-from-passwd +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 -flock \-\-timeout=0 /sys /usr/local/bin/update-hotplug /sys +By default, if the lock cannot be immediately acquired, \fBflock\fP +waits until the lock is available. +.SH OPTIONS +.TP +\fB\-s\fP, \fB\-\-shared\fP +Obtain a shared lock, sometimes called a read lock. +.TP +\fB\-x\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\-\-nonblock\fP +Fail (with an exit code of 1) rather than wait if the lock cannot be +immediately acquired. +.TP +\fB\-w\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. +.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 hold ing the lock. +.TP +\fB\-h\fP, \fB\-\-help\fP +Print a help message. .SH AUTHOR -Written by Adam J. Richter +Written by H. Peter Anvin . +.SH COPYRIGHT +Copyright \(co 2003\-2005 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) -- cgit v1.2.3-55-g7522