| 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 | .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 . |
| 57 | .SH "SEE ALSO" |
| 58 | .BR fcntl (2), |
| 59 | .BR mLib (3). |
| 60 | .SH AUTHOR |
| 61 | Mark Wooding, <mdw@nsict.org> |