1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)flock.2 8.2 (Berkeley) 12/11/93 7.\" 8.Dd 9.Dt FLOCK 2 10.Os BSD 4.2 11.Sh NAME 12.Nm flock 13.Nd "apply or remove an advisory lock on an open file" 14.Sh SYNOPSIS 15.Fd #include <sys/file.h> 16.Fd #define LOCK_SH 1 /* shared lock */ 17.Fd #define LOCK_EX 2 /* exclusive lock */ 18.Fd #define LOCK_NB 4 /* don't block when locking */ 19.Fd #define LOCK_UN 8 /* unlock */ 20.Ft int 21.Fn flock "int fd" "int operation" 22.Sh DESCRIPTION 23.Fn Flock 24applies or removes an 25.Em advisory 26lock on the file associated with the file descriptor 27.Fa fd . 28A lock is applied by specifying an 29.Fa operation 30parameter that is one of 31.Dv LOCK_SH 32or 33.Dv LOCK_EX 34with the optional addition of 35.Dv LOCK_NB . 36To unlock 37an existing lock 38.Dv operation 39should be 40.Dv LOCK_UN . 41.Pp 42Advisory locks allow cooperating processes to perform 43consistent operations on files, but do not guarantee 44consistency (i.e., processes may still access files 45without using advisory locks possibly resulting in 46inconsistencies). 47.Pp 48The locking mechanism allows two types of locks: 49.Em shared 50locks and 51.Em exclusive 52locks. 53At any time multiple shared locks may be applied to a file, 54but at no time are multiple exclusive, or both shared and exclusive, 55locks allowed simultaneously on a file. 56.Pp 57A shared lock may be 58.Em upgraded 59to an exclusive lock, and vice versa, simply by specifying 60the appropriate lock type; this results in the previous 61lock being released and the new lock applied (possibly 62after other processes have gained and released the lock). 63.Pp 64Requesting a lock on an object that is already locked 65normally causes the caller to be blocked until the lock may be 66acquired. If 67.Dv LOCK_NB 68is included in 69.Fa operation , 70then this will not happen; instead the call will fail and 71the error 72.Er EWOULDBLOCK 73will be returned. 74.Sh NOTES 75Locks are on files, not file descriptors. That is, file descriptors 76duplicated through 77.Xr dup 2 78or 79.Xr fork 2 80do not result in multiple instances of a lock, but rather multiple 81references to a single lock. If a process holding a lock on a file 82forks and the child explicitly unlocks the file, the parent will 83lose its lock. 84.Pp 85Processes blocked awaiting a lock may be awakened by signals. 86.Sh RETURN VALUES 87Zero is returned if the operation was successful; 88on an error a -1 is returned and an error code is left in 89the global location 90.Va errno . 91.Sh ERRORS 92The 93.Fn flock 94call fails if: 95.Bl -tag -width EWOULDBLOCKAA 96.It Bq Er EWOULDBLOCK 97The file is locked and the 98.Dv LOCK_NB 99option was specified. 100.It Bq Er EBADF 101The argument 102.Fa fd 103is an invalid descriptor. 104.It Bq Er EINVAL 105The argument 106.Fa fd 107refers to an object other than a file. 108.El 109.Sh SEE ALSO 110.Xr open 2 , 111.Xr close 2 , 112.Xr dup 2 , 113.Xr execve 2 , 114.Xr fork 2 115.Sh HISTORY 116The 117.Nm 118function call appeared in 119.Bx 4.2 . 120