119 lines
2.5 KiB
Groff
119 lines
2.5 KiB
Groff
.\" $OpenBSD: flockfile.3,v 1.11 2013/06/05 03:44:50 tedu Exp $
|
|
.\" David Leonard <d@openbsd.org>, 1998. Public domain.
|
|
.Dd $Mdocdate: June 5 2013 $
|
|
.Dt FLOCKFILE 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm flockfile ,
|
|
.Nm ftrylockfile ,
|
|
.Nm funlockfile
|
|
.Nd application level locking of stdio files
|
|
.Sh SYNOPSIS
|
|
.In 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.
|