Commit | Line | Data |
---|---|---|
b6b9d458 | 1 | .\" -*-nroff-*- |
fbf20b5b | 2 | .TH lock 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library" |
b6b9d458 | 3 | .SH NAME |
4 | lock \- oversimplified file locking interface | |
08da152e | 5 | .\" @lock_file |
b6b9d458 | 6 | .SH SYNOPSIS |
7 | .nf | |
d2a91066 | 8 | .B "#include <mLib/lock.h>" |
b6b9d458 | 9 | |
4729aa69 MW |
10 | .B "enum {" |
11 | .B "\h'4n'LOCK_UNLOCK = ...," | |
12 | .B "\h'4n'LOCK_EXCL = ...," | |
13 | .B "\h'4n'LOCK_NONEXCL = ..." | |
14 | .B "};" | |
15 | ||
b6b9d458 | 16 | .BI "int lock_file(int " fd ", unsigned " how ); |
17 | .fi | |
18 | .SH DESCRIPTION | |
19 | The | |
20 | .B lock_file | |
21 | function provides an extremely simplistic interface to POSIX | |
22 | .BR fcntl (2) | |
23 | locking. It locks only entire files, not sections of files. It doesn't | |
24 | have a nonblocking `is this file locked?' function. | |
25 | .PP | |
26 | On entry, | |
27 | .I fd | |
28 | should be a file descriptor on an open file, and | |
29 | .I how | |
30 | is a constant which describes how the file is to be locked. The | |
31 | possible values of | |
32 | .I how | |
33 | are: | |
34 | .TP | |
35 | .B LOCK_EXCL | |
36 | Lock the file exclusively. Attempts to lock the file exclusively or | |
37 | nonexclusively will fail until the file is unlocked. | |
38 | .TP | |
39 | .B LOCK_NONEXCL | |
40 | Lock the file nonexclusively. Until the file is unlocked, attempts to | |
41 | lock it exclusively will fail, but other nonexclusive locks will | |
42 | succeed. | |
43 | .TP | |
44 | .B LOCK_UNLOCK | |
45 | Unlocks a locked file. Any locks afterwards can succeed. | |
46 | .PP | |
47 | The | |
48 | .B lock_file | |
49 | function will block if it can't obtain a lock immediately. It will time | |
50 | itself out after a short while (10 seconds in the current | |
51 | implementation) if the lock doesn't become available. | |
52 | .PP | |
53 | If the call succeeds, | |
54 | .B lock_file | |
55 | returns zero. On failure, \-1 is returned, and | |
56 | .B errno | |
57 | is set to an appropriate value. Most of the error returns are from | |
58 | .BR fcntl (2) | |
59 | (q.v.). If the lock operation times out, | |
60 | .B errno | |
61 | is set to | |
62 | .BR EINTR . | |
08da152e | 63 | .SH "SEE ALSO" |
64 | .BR fcntl (2), | |
65 | .BR mLib (3). | |
b6b9d458 | 66 | .SH AUTHOR |
9b5ac6ff | 67 | Mark Wooding, <mdw@distorted.org.uk> |