From 399644e47874bff147afb19c89228901ac39340e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:40:15 +0200 Subject: Adding upstream version 6.05.01. Signed-off-by: Daniel Baumann --- man3/flockfile.3 | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 man3/flockfile.3 (limited to 'man3/flockfile.3') diff --git a/man3/flockfile.3 b/man3/flockfile.3 new file mode 100644 index 0000000..c2a18a4 --- /dev/null +++ b/man3/flockfile.3 @@ -0,0 +1,134 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer . +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH flockfile 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +flockfile, ftrylockfile, funlockfile \- lock FILE for stdio +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "void flockfile(FILE *" filehandle ); +.BI "int ftrylockfile(FILE *" filehandle ); +.BI "void funlockfile(FILE *" filehandle ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +All functions shown above: +.nf + /* Since glibc 2.24: */ _POSIX_C_SOURCE >= 199309L + || /* glibc <= 2.23: */ _POSIX_C_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The stdio functions are thread-safe. +This is achieved by assigning +to each +.I FILE +object a lockcount and (if the lockcount is nonzero) +an owning thread. +For each library call, these functions wait until the +.I FILE +object +is no longer locked by a different thread, then lock it, do the +requested I/O, and unlock the object again. +.PP +(Note: this locking has nothing to do with the file locking done +by functions like +.BR flock (2) +and +.BR lockf (3).) +.PP +All this is invisible to the C-programmer, but there may be two +reasons to wish for more detailed control. +On the one hand, maybe +a series of I/O actions by one thread belongs together, and should +not be interrupted by the I/O of some other thread. +On the other hand, maybe the locking overhead should be avoided +for greater efficiency. +.PP +To this end, a thread can explicitly lock the +.I FILE +object, +then do its series of I/O actions, then unlock. +This prevents +other threads from coming in between. +If the reason for doing +this was to achieve greater efficiency, one does the I/O with +the nonlocking versions of the stdio functions: with +.BR getc_unlocked (3) +and +.BR putc_unlocked (3) +instead of +.BR getc (3) +and +.BR putc (3). +.PP +The +.BR flockfile () +function waits for +.I *filehandle +to be +no longer locked by a different thread, then makes the +current thread owner of +.IR *filehandle , +and increments +the lockcount. +.PP +The +.BR funlockfile () +function decrements the lock count. +.PP +The +.BR ftrylockfile () +function is a nonblocking version +of +.BR flockfile (). +It does nothing in case some other thread +owns +.IR *filehandle , +and it obtains ownership and increments +the lockcount otherwise. +.SH RETURN VALUE +The +.BR ftrylockfile () +function returns zero for success +(the lock was obtained), and nonzero for failure. +.SH ERRORS +None. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR flockfile (), +.BR ftrylockfile (), +.BR funlockfile () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.PP +These functions are available when +.B _POSIX_THREAD_SAFE_FUNCTIONS +is defined. +.SH SEE ALSO +.BR unlocked_stdio (3) -- cgit v1.2.3