[mLib] / sys / lock.3

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