| | 1 | .\" -*-nroff-*- |
| | 2 | .TH lock 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library" |
| | 3 | .SH NAME |
| | 4 | lock \- oversimplified file locking interface |
| | 5 | .\" @lock_file |
| | 6 | .SH SYNOPSIS |
| | 7 | .nf |
| | 8 | .B "#include <mLib/lock.h>" |
| | 9 | |
| | 10 | .B "enum {" |
| | 11 | .B "\h'4n'LOCK_UNLOCK = ...," |
| | 12 | .B "\h'4n'LOCK_EXCL = ...," |
| | 13 | .B "\h'4n'LOCK_NONEXCL = ..." |
| | 14 | .B "};" |
| | 15 | |
| | 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 . |
| | 63 | .SH "SEE ALSO" |
| | 64 | .BR fcntl (2), |
| | 65 | .BR mLib (3). |
| | 66 | .SH AUTHOR |
| | 67 | Mark Wooding, <mdw@distorted.org.uk> |
~mdw / mLib / blame_incremental