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 45The 46.Fn flock 47system call applies or removes an 48.Em advisory 49lock on the file associated with the file descriptor 50.Fa fd . 51A lock is applied by specifying an 52.Fa operation 53argument that is one of 54.Dv LOCK_SH 55or 56.Dv LOCK_EX 57with the optional addition of 58.Dv LOCK_NB . 59To unlock 60an existing lock 61.Dv operation 62should be 63.Dv LOCK_UN . 64.Pp 65Advisory locks allow cooperating processes to perform 66consistent operations on files, but do not guarantee 67consistency (i.e., processes may still access files 68without using advisory locks possibly resulting in 69inconsistencies). 70.Pp 71The locking mechanism allows two types of locks: 72.Em shared 73locks and 74.Em exclusive 75locks. 76At any time multiple shared locks may be applied to a file, 77but at no time are multiple exclusive, or both shared and exclusive, 78locks allowed simultaneously on a file. 79.Pp 80A shared lock may be 81.Em upgraded 82to an exclusive lock, and vice versa, simply by specifying 83the appropriate lock type; this results in the previous 84lock being released and the new lock applied (possibly 85after other processes have gained and released the lock). 86.Pp 87Requesting a lock on an object that is already locked 88normally causes the caller to be blocked until the lock may be 89acquired. 90If 91.Dv LOCK_NB 92is included in 93.Fa operation , 94then this will not happen; instead the call will fail and 95the error 96.Er EWOULDBLOCK 97will be returned. 98.Sh NOTES 99Locks are on files, not file descriptors. 100That is, file descriptors 101duplicated through 102.Xr dup 2 103or 104.Xr fork 2 105do not result in multiple instances of a lock, but rather multiple 106references to a single lock. 107If a process holding a lock on a file 108forks and the child explicitly unlocks the file, the parent will 109lose its lock. 110.Pp 111The 112.Fn flock , 113.Xr fcntl 2 , 114and 115.Xr lockf 3 116locks are compatible. 117Processes using different locking interfaces can cooperate 118over the same file safely. 119However, only one of such interfaces should be used within 120the same process. 121If a file is locked by a process through 122.Fn flock , 123any record within the file will be seen as locked 124from the viewpoint of another process using 125.Xr fcntl 2 126or 127.Xr lockf 3 , 128and vice versa. 129.Pp 130Processes blocked awaiting a lock may be awakened by signals. 131.Sh RETURN VALUES 132.Rv -std flock 133.Sh ERRORS 134The 135.Fn flock 136system call fails if: 137.Bl -tag -width Er 138.It Bq Er EWOULDBLOCK 139The file is locked and the 140.Dv LOCK_NB 141option was specified. 142.It Bq Er EBADF 143The argument 144.Fa fd 145is an invalid descriptor. 146.It Bq Er EINVAL 147The argument 148.Fa fd 149refers to an object other than a file. 150.It Bq Er EOPNOTSUPP 151The argument 152.Fa fd 153refers to an object that does not support file locking. 154.It Bq Er ENOLCK 155A 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 167The 168.Fn flock 169system call appeared in 170.Bx 4.2 . 171