~mdw / mLib / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
@@@ much mess, mostly manpages
[mLib] / sys / lock.3.in
CommitLineData
c4ccbbf9
MW		 1.\" -*-nroff-*-
2.\"
3.\" Manual for file locking
4.\"
5.\" (c) 1999, 2001, 2005, 2009, 2023, 2024 Straylight/Edgeware
6.\"
7.
8.\"----- Licensing notice ---------------------------------------------------
9.\"
10.\" This file is part of the mLib utilities library.
11.\"
12.\" mLib is free software: you can redistribute it and/or modify it under
13.\" the terms of the GNU Library General Public License as published by
14.\" the Free Software Foundation; either version 2 of the License, or (at
15.\" your option) any later version.
16.\"
17.\" mLib is distributed in the hope that it will be useful, but WITHOUT
18.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
19.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
20.\" License for more details.
21.\"
22.\" You should have received a copy of the GNU Library General Public
23.\" License along with mLib. If not, write to the Free Software
24.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
25.\" USA.
26.
27.\"--------------------------------------------------------------------------
28.so ../defs.man \" @@@PRE@@@
29.
30.\"--------------------------------------------------------------------------
31.TH lock 3mLib "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
32.\" @lock_file
33.
34.\"--------------------------------------------------------------------------
35.SH NAME
36lock \- oversimplified file locking interface
37.
38.\"--------------------------------------------------------------------------
39.SH SYNOPSIS
40.
41.nf
42.B "#include <mLib/lock.h>"
43.PP
44.ta 2n
45.B "enum {"
46.B " LOCK_UNLOCK = ...,"
47.B " LOCK_EXCL = ...,"
48.B " LOCK_NONEXCL = ..."
49.B "};"
50.PP
51.BI "int lock_file(int " fd ", unsigned " how );
52.fi
53.
54.\"--------------------------------------------------------------------------
55.SH DESCRIPTION
56.
57The
58.B lock_file
59function provides an extremely simplistic interface to POSIX
60.BR fcntl (2)
61locking. It locks only entire files, not sections of files. It doesn't
62have a nonblocking `is this file locked?' function.
63.PP
64On entry,
65.I fd
66should be a file descriptor on an open file, and
67.I how
68is a constant which describes how the file is to be locked. The
69possible values of
70.I how
71are:
72.TP
73.B LOCK_EXCL
74Lock the file exclusively. Attempts to lock the file exclusively or
75nonexclusively will fail until the file is unlocked.
76.TP
77.B LOCK_NONEXCL
78Lock the file nonexclusively. Until the file is unlocked, attempts to
79lock it exclusively will fail, but other nonexclusive locks will
80succeed.
81.TP
82.B LOCK_UNLOCK
83Unlocks a locked file. Any locks afterwards can succeed.
84.PP
85The
86.B lock_file
87function will block if it can't obtain a lock immediately. It will time
88itself out after a short while (10 seconds in the current
89implementation) if the lock doesn't become available.
90.PP
91If the call succeeds,
92.B lock_file
93returns zero. On failure, \-1 is returned, and
94.B errno
95is set to an appropriate value. Most of the error returns are from
96.BR fcntl (2)
97(q.v.). If the lock operation times out,
98.B errno
99is set to
100.BR EINTR .
101.
102.\"--------------------------------------------------------------------------
103.SH "SEE ALSO"
104.
105.BR fcntl (2),
106.BR mLib (3).
107.
108.\"--------------------------------------------------------------------------
109.SH AUTHOR
110.
111Mark Wooding, <mdw@distorted.org.uk>
112.
113.\"----- That's all, folks --------------------------------------------------
mLib utilities library