usr.bin/flock/flock.1

   1 .\"     $NetBSD: flock.1,v 1.10 2014/08/18 09:45:52 christos Exp $
   2 .\"
   3 .\" Copyright (c) 2012 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Christos Zoulas.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\"
  31 .Dd August 18, 2014
  32 .Dt FLOCK 1
  33 .Os
  34 .Sh NAME
  35 .Nm flock
  36 .Nd Provide locking API for shell scripts
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl dnosvx
  40 .Op Fl w Ar timeout
  41 .Ar lockfile|lockdir
  42 .Op Fl c Ar command
  43 |
  44 .Op Ar command ...
  45 .Nm
  46 .Op Fl dnsuvx
  47 .Op Fl w Ar timeout
  48 .Ar lockfd
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 utility provides
  53 .Xr flock 2
  54 access to the command line or scripts.
  55 The first form locks a file or directory while the command provided is executed.
  56 If the file or directory does not exist, then a file is created.
  57 .Pp
  58 The second form can use an arbitrary file descriptor that is provided from a
  59 shell script for example:
  60 .Bd -literal
  61 (
  62         flock -s 100
  63         # commands to be executed under the lock
  64 ) 100> /path/to/lockfile
  65 .Ed
  66 .Pp
  67 The following options are available:
  68 .Bl -tag -width "XXXXXXXXXXXXXXXXX"
  69 .It Fl c Ar command
  70 Pass a command to a the shell.
  71 .It Fl d , Fl Fl debug
  72 Provide debugging output.
  73 .It Fl n , Fl Fl nb , Fl Fl nonblock
  74 Don't block and fail immediately if the lock could not be obtained.
  75 .It Fl o , Fl Fl close
  76 Close the file before executing the command.
  77 This is useful if the child forks and should not be holding the lock.
  78 .It Fl s , Fl Fl shared
  79 Obtain a shared lock.
  80 .It Fl u , Fl Fl unlock
  81 Unlock an existing lock.
  82 This is available only for a file descriptor.
  83 .It Fl v , Fl Fl verbose
  84 On error print an explanation of the failure.
  85 .It Fl w , Fl Fl wait , Fl Fl timeout Ar seconds
  86 Fail if the lock could not be obtained after
  87 .Ar seconds .
  88 .It Fl x , Fl Fl exclusive
  89 Obtain an exclusive lock.
  90 This is the default.
  91 .El
  92 .Sh EXIT STATUS
  93 .Ex -std
  94 .Sh SEE ALSO
  95 .Xr shlock 1 ,
  96 .Xr flock 2
  97 .Sh HISTORY
  98 An
  99 .Nm
 100 utility appeared in
 101 .Nx 6.1 .