chiark / gitweb /
75460b4800d61a3d9154a0fca4fa3d9f993d985a
[mLib] / lock.3
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@distorted.org.uk>