161181Sbostic.\" Copyright (c) 1983, 1991, 1993 261181Sbostic.\" The Regents of the University of California. All rights reserved. 320215Smckusick.\" 443568Strent.\" %sccs.include.redist.man% 520215Smckusick.\" 6*65100Smckusick.\" @(#)flock.2 8.2 (Berkeley) 12/11/93 738053Sbostic.\" 847208Scael.Dd 947208Scael.Dt FLOCK 2 1047208Scael.Os BSD 4.2 1147208Scael.Sh NAME 1247208Scael.Nm flock 1347208Scael.Nd "apply or remove an advisory lock on an open file" 1447208Scael.Sh SYNOPSIS 1547208Scael.Fd #include <sys/file.h> 1647208Scael.Fd #define LOCK_SH 1 /* shared lock */ 1747208Scael.Fd #define LOCK_EX 2 /* exclusive lock */ 1847208Scael.Fd #define LOCK_NB 4 /* don't block when locking */ 1947208Scael.Fd #define LOCK_UN 8 /* unlock */ 2047208Scael.Ft int 2147208Scael.Fn flock "int fd" "int operation" 2247208Scael.Sh DESCRIPTION 2347208Scael.Fn Flock 2420215Smckusickapplies or removes an 2547208Scael.Em advisory 2620215Smckusicklock on the file associated with the file descriptor 2747208Scael.Fa fd . 2820215SmckusickA lock is applied by specifying an 2947208Scael.Fa operation 30*65100Smckusickparameter that is one of 3147208Scael.Dv LOCK_SH 3247208Scaelor 3347208Scael.Dv LOCK_EX 34*65100Smckusickwith the optional addition of 3547208Scael.Dv LOCK_NB . 3647208ScaelTo unlock 3720215Smckusickan existing lock 3847208Scael.Dv operation 3947208Scaelshould be 4047208Scael.Dv LOCK_UN . 4147208Scael.Pp 4220215SmckusickAdvisory locks allow cooperating processes to perform 4320215Smckusickconsistent operations on files, but do not guarantee 4428367Sanneconsistency (i.e., processes may still access files 4520215Smckusickwithout using advisory locks possibly resulting in 4620215Smckusickinconsistencies). 4747208Scael.Pp 4820215SmckusickThe locking mechanism allows two types of locks: 4947208Scael.Em shared 5020215Smckusicklocks and 5147208Scael.Em exclusive 5220215Smckusicklocks. 5320215SmckusickAt any time multiple shared locks may be applied to a file, 5420215Smckusickbut at no time are multiple exclusive, or both shared and exclusive, 5520215Smckusicklocks allowed simultaneously on a file. 5647208Scael.Pp 5720215SmckusickA shared lock may be 5847208Scael.Em upgraded 5920215Smckusickto an exclusive lock, and vice versa, simply by specifying 6020215Smckusickthe appropriate lock type; this results in the previous 6120215Smckusicklock being released and the new lock applied (possibly 6220215Smckusickafter other processes have gained and released the lock). 6347208Scael.Pp 6423800SsechrestRequesting a lock on an object that is already locked 6527205Slepreaunormally causes the caller to be blocked until the lock may be 6647208Scaelacquired. If 6747208Scael.Dv LOCK_NB 6847208Scaelis included in 6947208Scael.Fa operation , 7020215Smckusickthen this will not happen; instead the call will fail and 7147208Scaelthe error 7247208Scael.Er EWOULDBLOCK 7347208Scaelwill be returned. 7447208Scael.Sh NOTES 7520215SmckusickLocks are on files, not file descriptors. That is, file descriptors 7620215Smckusickduplicated through 7747208Scael.Xr dup 2 7820215Smckusickor 7947208Scael.Xr fork 2 8020215Smckusickdo not result in multiple instances of a lock, but rather multiple 8120215Smckusickreferences to a single lock. If a process holding a lock on a file 8220215Smckusickforks and the child explicitly unlocks the file, the parent will 8320215Smckusicklose its lock. 8447208Scael.Pp 8520215SmckusickProcesses blocked awaiting a lock may be awakened by signals. 8647208Scael.Sh RETURN VALUES 8720215SmckusickZero is returned if the operation was successful; 8847208Scaelon an error a -1 is returned and an error code is left in 8947208Scaelthe global location 9047208Scael.Va errno . 9147208Scael.Sh ERRORS 9247208ScaelThe 9347208Scael.Fn flock 9447208Scaelcall fails if: 9547208Scael.Bl -tag -width EWOULDBLOCKAA 9647208Scael.It Bq Er EWOULDBLOCK 9747208ScaelThe file is locked and the 9847208Scael.Dv LOCK_NB 9947208Scaeloption was specified. 10047208Scael.It Bq Er EBADF 10147208ScaelThe argument 10247208Scael.Fa fd 10347208Scaelis an invalid descriptor. 10447208Scael.It Bq Er EINVAL 10547208ScaelThe argument 10647208Scael.Fa fd 10747208Scaelrefers to an object other than a file. 10847208Scael.El 10947208Scael.Sh SEE ALSO 11047208Scael.Xr open 2 , 11147208Scael.Xr close 2 , 11247208Scael.Xr dup 2 , 11347208Scael.Xr execve 2 , 11447208Scael.Xr fork 2 11547208Scael.Sh HISTORY 11647208ScaelThe 11747208Scael.Nm 11847208Scaelfunction call appeared in 11947208Scael.Bx 4.2 . 120