PDCLIB-15 PDCLIB-16:

[pdclib.old] / man3 / flockfile.3

diff --git a/man3/flockfile.3 b/man3/flockfile.3
new file mode 100644 (file)
index 0000000..a8a4a3b
--- /dev/null
+++ b/man3/flockfile.3
@@ -0,0 +1,56 @@
+.\" This file is part of the Public Domain C Library (PDCLib).\r
+.\" Permission is granted to use, modify, and / or redistribute at will.\r
+.\"\r
+.Dd\r
+.Dt flockfile 3\r
+.Os\r
+\r
+.Sh NAME\r
+.Nm flockfile, ftrylockfile, funlockfile\r
+.Nd stdio file locking\r
+\r
+.Sh SYNOPSIS\r
+.Sy #define _POSIX_C_SOURCE >= 200112L || _XOPEN_SOURCE >= 600 || _SVID_SOURCE || _BSD_SOURCE\r
+\r
+.In stdio.h\r
+.Fn "void flockfile" "FILE *file"\r
+.Fn "int ftrylockfile" "FILE *file"\r
+.Fn "void funlockfile" "FILE *file"\r
+\r
+.Sh DESCRIPTION\r
+.Fn flockfile\r
+locks the passed FILE stream for access by the calling thread, potentially \r
+blocking. \r
+.Fn ftrylockfile\r
+attempts to lock the file for the calling thread, but will return failure if\r
+another thread has already locked the file.\r
+.Fn funlockfile\r
+releases the lock on the stream, allowing another thread in the process to \r
+access it.\r
+.\"\r
+.Pp\r
+The same stream may be locked multiple times by the calling thread; the number \r
+of calls to \r
+.Fn flockfile \r
+and \r
+.Fn ftrylockfile\r
+on a file must be equal to the number of calls to\r
+.Fn funlockfile .\r
+.\"\r
+.Pp\r
+No other thread may do I/O through the locked file while it is locked.\r
+\r
+.Sh IMPLEMENTATION NOTES\r
+PDCLib implements the file locking on top of the Mutex primitives added by C11\r
+\r
+.Sh SEE ALSO\r
+.Xr fopen 3\r
+.Xr fclose 3\r
+.Xr unlocked_stdio 3\r
+.Xr mtx_t 3\r
+\r
+.Sh STANDARDS\r
+The locked I/O routines were initially introduced in \r
+.St -svid4 ,\r
+and incorporated into POSIX in \r
+.St -p1003.1-2001 .\r