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