Commit | Line | Data |
---|---|---|
aaea5b2e KB |
1 | .\" Copyright (c) 1983, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
619ee695 | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
88b3ccf2 | 5 | .\" |
653ba8b6 | 6 | .\" @(#)flock.2 8.2 (Berkeley) %G% |
619ee695 | 7 | .\" |
931b8415 CL |
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 | |
619ee695 | 24 | applies or removes an |
931b8415 | 25 | .Em advisory |
619ee695 | 26 | lock on the file associated with the file descriptor |
931b8415 | 27 | .Fa fd . |
619ee695 | 28 | A lock is applied by specifying an |
931b8415 | 29 | .Fa operation |
653ba8b6 | 30 | parameter that is one of |
931b8415 CL |
31 | .Dv LOCK_SH |
32 | or | |
33 | .Dv LOCK_EX | |
653ba8b6 | 34 | with the optional addition of |
931b8415 CL |
35 | .Dv LOCK_NB . |
36 | To unlock | |
619ee695 | 37 | an existing lock |
931b8415 CL |
38 | .Dv operation |
39 | should be | |
40 | .Dv LOCK_UN . | |
41 | .Pp | |
619ee695 KM |
42 | Advisory locks allow cooperating processes to perform |
43 | consistent operations on files, but do not guarantee | |
4decc76b | 44 | consistency (i.e., processes may still access files |
619ee695 KM |
45 | without using advisory locks possibly resulting in |
46 | inconsistencies). | |
931b8415 | 47 | .Pp |
619ee695 | 48 | The locking mechanism allows two types of locks: |
931b8415 | 49 | .Em shared |
619ee695 | 50 | locks and |
931b8415 | 51 | .Em exclusive |
619ee695 KM |
52 | locks. |
53 | At any time multiple shared locks may be applied to a file, | |
54 | but at no time are multiple exclusive, or both shared and exclusive, | |
55 | locks allowed simultaneously on a file. | |
931b8415 | 56 | .Pp |
619ee695 | 57 | A shared lock may be |
931b8415 | 58 | .Em upgraded |
619ee695 KM |
59 | to an exclusive lock, and vice versa, simply by specifying |
60 | the appropriate lock type; this results in the previous | |
61 | lock being released and the new lock applied (possibly | |
62 | after other processes have gained and released the lock). | |
931b8415 | 63 | .Pp |
38edb05c | 64 | Requesting a lock on an object that is already locked |
19ecbc2b | 65 | normally causes the caller to be blocked until the lock may be |
931b8415 CL |
66 | acquired. If |
67 | .Dv LOCK_NB | |
68 | is included in | |
69 | .Fa operation , | |
619ee695 | 70 | then this will not happen; instead the call will fail and |
931b8415 CL |
71 | the error |
72 | .Er EWOULDBLOCK | |
73 | will be returned. | |
74 | .Sh NOTES | |
619ee695 KM |
75 | Locks are on files, not file descriptors. That is, file descriptors |
76 | duplicated through | |
931b8415 | 77 | .Xr dup 2 |
619ee695 | 78 | or |
931b8415 | 79 | .Xr fork 2 |
619ee695 KM |
80 | do not result in multiple instances of a lock, but rather multiple |
81 | references to a single lock. If a process holding a lock on a file | |
82 | forks and the child explicitly unlocks the file, the parent will | |
83 | lose its lock. | |
931b8415 | 84 | .Pp |
619ee695 | 85 | Processes blocked awaiting a lock may be awakened by signals. |
931b8415 | 86 | .Sh RETURN VALUES |
619ee695 | 87 | Zero is returned if the operation was successful; |
931b8415 CL |
88 | on an error a -1 is returned and an error code is left in |
89 | the global location | |
90 | .Va errno . | |
91 | .Sh ERRORS | |
92 | The | |
93 | .Fn flock | |
94 | call fails if: | |
95 | .Bl -tag -width EWOULDBLOCKAA | |
96 | .It Bq Er EWOULDBLOCK | |
97 | The file is locked and the | |
98 | .Dv LOCK_NB | |
99 | option was specified. | |
100 | .It Bq Er EBADF | |
101 | The argument | |
102 | .Fa fd | |
103 | is an invalid descriptor. | |
104 | .It Bq Er EINVAL | |
105 | The argument | |
106 | .Fa fd | |
107 | refers 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 | |
116 | The | |
117 | .Nm | |
118 | function call appeared in | |
119 | .Bx 4.2 . |