lib/libc/sys/flock.2

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd November 9, 2011
  29 .Dt FLOCK 2
  30 .Os
  31 .Sh NAME
  32 .Nm flock
  33 .Nd "apply or remove an advisory lock on an open file"
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In sys/file.h
  38 .Fd "#define   LOCK_SH        0x01      /* shared file lock */"
  39 .Fd "#define   LOCK_EX        0x02      /* exclusive file lock */"
  40 .Fd "#define   LOCK_NB        0x04      /* do not block when locking */"
  41 .Fd "#define   LOCK_UN        0x08      /* unlock file */"
  42 .Ft int
  43 .Fn flock "int fd" "int operation"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn flock
  47 system call applies or removes an
  48 .Em advisory
  49 lock on the file associated with the file descriptor
  50 .Fa fd .
  51 A lock is applied by specifying an
  52 .Fa operation
  53 argument that is one of
  54 .Dv LOCK_SH
  55 or
  56 .Dv LOCK_EX
  57 with the optional addition of
  58 .Dv LOCK_NB .
  59 To unlock
  60 an existing lock
  61 .Dv operation
  62 should be
  63 .Dv LOCK_UN .
  64 .Pp
  65 Advisory locks allow cooperating processes to perform
  66 consistent operations on files, but do not guarantee
  67 consistency (i.e., processes may still access files
  68 without using advisory locks possibly resulting in
  69 inconsistencies).
  70 .Pp
  71 The locking mechanism allows two types of locks:
  72 .Em shared
  73 locks and
  74 .Em exclusive
  75 locks.
  76 At any time multiple shared locks may be applied to a file,
  77 but at no time are multiple exclusive, or both shared and exclusive,
  78 locks allowed simultaneously on a file.
  79 .Pp
  80 A shared lock may be
  81 .Em upgraded
  82 to an exclusive lock, and vice versa, simply by specifying
  83 the appropriate lock type; this results in the previous
  84 lock being released and the new lock applied (possibly
  85 after other processes have gained and released the lock).
  86 .Pp
  87 Requesting a lock on an object that is already locked
  88 normally causes the caller to be blocked until the lock may be
  89 acquired.
  90 If
  91 .Dv LOCK_NB
  92 is included in
  93 .Fa operation ,
  94 then this will not happen; instead the call will fail and
  95 the error
  96 .Er EWOULDBLOCK
  97 will be returned.
  98 .Sh NOTES
  99 Locks are on files, not file descriptors.
 100 That is, file descriptors
 101 duplicated through
 102 .Xr dup 2
 103 or
 104 .Xr fork 2
 105 do not result in multiple instances of a lock, but rather multiple
 106 references to a single lock.
 107 If a process holding a lock on a file
 108 forks and the child explicitly unlocks the file, the parent will
 109 lose its lock.
 110 .Pp
 111 The
 112 .Fn flock ,
 113 .Xr fcntl 2 ,
 114 and
 115 .Xr lockf 3
 116 locks are compatible.
 117 Processes using different locking interfaces can cooperate
 118 over the same file safely.
 119 However, only one of such interfaces should be used within
 120 the same process.
 121 If a file is locked by a process through
 122 .Fn flock ,
 123 any record within the file will be seen as locked
 124 from the viewpoint of another process using
 125 .Xr fcntl 2
 126 or
 127 .Xr lockf 3 ,
 128 and vice versa.
 129 .Pp
 130 Processes blocked awaiting a lock may be awakened by signals.
 131 .Sh RETURN VALUES
 132 .Rv -std flock
 133 .Sh ERRORS
 134 The
 135 .Fn flock
 136 system call fails if:
 137 .Bl -tag -width Er
 138 .It Bq Er EWOULDBLOCK
 139 The file is locked and the
 140 .Dv LOCK_NB
 141 option was specified.
 142 .It Bq Er EBADF
 143 The argument
 144 .Fa fd
 145 is an invalid descriptor.
 146 .It Bq Er EINVAL
 147 The argument
 148 .Fa fd
 149 refers to an object other than a file.
 150 .It Bq Er EOPNOTSUPP
 151 The argument
 152 .Fa fd
 153 refers to an object that does not support file locking.
 154 .It Bq Er ENOLCK
 155 A lock was requested, but no locks are available.
 156 .El
 157 .Sh SEE ALSO
 158 .Xr close 2 ,
 159 .Xr dup 2 ,
 160 .Xr execve 2 ,
 161 .Xr fcntl 2 ,
 162 .Xr fork 2 ,
 163 .Xr open 2 ,
 164 .Xr flopen 3 ,
 165 .Xr lockf 3
 166 .Sh HISTORY
 167 The
 168 .Fn flock
 169 system call appeared in
 170 .Bx 4.2 .