1 files changed, 112 insertions, 0 deletions
diff --git a/lib/libc_r/man/flockfile.3 b/lib/libc_r/man/flockfile.3
new file mode 100644
index 00000000000..80602c5584b
--- /dev/null
+++ b/lib/libc_r/man/flockfile.3
@@ -0,0 +1,112 @@
+.\" $OpenBSD: flockfile.3,v 1.1 1998/08/27 09:00:34 d Exp $
+.Dd August 20, 1998
+.Os Ox
+.Dt FLOCKFILE 3
+.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 intialized 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 sucessful 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 ftrylock
+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 putc_unlocked 3 ,
+.Xr putchar_unlocked 3 ,
+.Xr pthreads 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.