OpenBSD-4.6/lib/libpthread/man/flockfile.3

.\" $OpenBSD: flockfile.3,v 1.10 2007/05/31 19:19:36 jmc Exp $
.\" David Leonard <d@openbsd.org>, 1998. Public domain.
.Dd $Mdocdate: May 31 2007 $
.Dt FLOCKFILE 3
.Os
.Sh NAME
.Nm flockfile ,
.Nm ftrylockfile ,
.Nm funlockfile
.Nd application level locking of stdio files
.Sh SYNOPSIS
.Fd #include <stdio.h>
.Ft void
.Fn flockfile "FILE *file"
.Ft int
.Fn ftrylockfile "FILE *file"
.Ft void
.Fn funlockfile "FILE *file"
.Sh DESCRIPTION
The
.Fn flockfile ,
.Fn ftrylockfile ,
and
.Fn funlockfile
functions provide for explicit application-level locking of stdio
.Ft "FILE *"
objects.
These functions can be used by a thread to delineate a sequence
of I/O statements that are to be executed as a unit.
.Pp
The
.Fn flockfile
function is used by a thread to acquire ownership of a
.Ft "FILE *"
object.
.Pp
The
.Fn ftrylockfile
function is used by a thread to acquire ownership of a
.Ft "FILE *"
object if the object is available;
.Fn ftrylockfile
is a non-blocking version of
.Fn flockfile .
.Pp
The
.Fn funlockfile
function is used to relinquish the ownership granted to the thread.
The behaviour is undefined if a thread other than the current owner calls the
.Fn funlockfile
function.
.Pp
Logically, there is a lock count associated with each
.Ft "FILE *"
object.
This count is implicitly initialized to zero when the
.Ft "FILE *"
object is created.
The
.Ft "FILE *"
object is unlocked when the count is zero.
When the count is positive, a single thread owns the
.Ft "FILE *"
object.
When the
.Fn flockfile
function is called, if the count is zero or if the count is positive and
the caller owns the
.Ft "FILE *"
object, the count is incremented.
Otherwise, the calling thread is suspended, waiting for the count to
return to zero.
Each call to
.Fn funlockfile
decrements the count.
This allows matching calls to
.Fn flockfile
(or successful calls to
.Fn ftrylockfile )
and
.Fn funlockfile
to be nested.
.Pp
Library functions that reference
.Ft "FILE *"
behave as if they use
.Fn flockfile
and
.Fn funlockfile
internally to obtain ownership of these
.Ft "FILE *"
objects.
.Sh RETURN VALUES
None for
.Fn flockfile
and
.Fn funlockfile .
The function
.Fn ftrylockfile
returns zero for success and non-zero to indicate that the lock cannot
be acquired.
.Sh ERRORS
None.
.Sh SEE ALSO
.Xr getc_unlocked 3 ,
.Xr getchar_unlocked 3 ,
.Xr pthreads 3 ,
.Xr putc_unlocked 3 ,
.Xr putchar_unlocked 3
.Sh STANDARDS
.Fn flockfile ,
.Fn ftrylockfile
and
.Fn funlockfile
conform to ISO/IEC 9945-1 ANSI/IEEE
.Pq Dq Tn POSIX
Std 1003.1c/D10.
.\" Std 1003.1 Second Edition 1996-07-12.