Debian Codegraph @

upstream/debian-unstable/man3/flockfile.3

raw
1 '\" t
2 .\" Copyright 2001, Andries E. Brouwer <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH flockfile 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 flockfile, ftrylockfile, funlockfile \- lock FILE for stdio
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <stdio.h>
16 .P
17 .BI "void flockfile(FILE *" filehandle );
18 .BI "int ftrylockfile(FILE *" filehandle );
19 .BI "void funlockfile(FILE *" filehandle );
20 .fi
21 .P
22 .RS -4
23 Feature Test Macro Requirements for glibc (see
24 .BR feature_test_macros (7)):
25 .RE
26 .P
27 All functions shown above:
28 .nf
29 /* Since glibc 2.24: */ _POSIX_C_SOURCE >= 199309L
30 || /* glibc <= 2.23: */ _POSIX_C_SOURCE
31 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
32 .fi
33 .SH DESCRIPTION
34 The stdio functions are thread-safe.
35 This is achieved by assigning
36 to each
37 .I FILE
38 object a lockcount and (if the lockcount is nonzero)
39 an owning thread.
40 For each library call, these functions wait until the
41 .I FILE
42 object
43 is no longer locked by a different thread, then lock it, do the
44 requested I/O, and unlock the object again.
45 .P
46 (Note: this locking has nothing to do with the file locking done
47 by functions like
48 .BR flock (2)
49 and
50 .BR lockf (3).)
51 .P
52 All this is invisible to the C-programmer, but there may be two
53 reasons to wish for more detailed control.
54 On the one hand, maybe
55 a series of I/O actions by one thread belongs together, and should
56 not be interrupted by the I/O of some other thread.
57 On the other hand, maybe the locking overhead should be avoided
58 for greater efficiency.
59 .P
60 To this end, a thread can explicitly lock the
61 .I FILE
62 object,
63 then do its series of I/O actions, then unlock.
64 This prevents
65 other threads from coming in between.
66 If the reason for doing
67 this was to achieve greater efficiency, one does the I/O with
68 the nonlocking versions of the stdio functions: with
69 .BR getc_unlocked (3)
70 and
71 .BR putc_unlocked (3)
72 instead of
73 .BR getc (3)
74 and
75 .BR putc (3).
76 .P
77 The
78 .BR flockfile ()
79 function waits for
80 .I *filehandle
81 to be
82 no longer locked by a different thread, then makes the
83 current thread owner of
84 .IR *filehandle ,
85 and increments
86 the lockcount.
87 .P
88 The
89 .BR funlockfile ()
90 function decrements the lock count.
91 .P
92 The
93 .BR ftrylockfile ()
94 function is a nonblocking version
95 of
96 .BR flockfile ().
97 It does nothing in case some other thread
98 owns
99 .IR *filehandle ,
100 and it obtains ownership and increments
101 the lockcount otherwise.
102 .SH RETURN VALUE
103 The
104 .BR ftrylockfile ()
105 function returns zero for success
106 (the lock was obtained), and nonzero for failure.
107 .SH ERRORS
108 None.
109 .SH ATTRIBUTES
110 For an explanation of the terms used in this section, see
111 .BR attributes (7).
112 .TS
113 allbox;
114 lbx lb lb
115 l l l.
116 Interface Attribute Value
117 T{
118 .na
119 .nh
120 .BR flockfile (),
121 .BR ftrylockfile (),
122 .BR funlockfile ()
123 T} Thread safety MT-Safe
124 .TE
125 .SH STANDARDS
126 POSIX.1-2008.
127 .SH HISTORY
128 POSIX.1-2001.
129 .P
130 These functions are available when
131 .B _POSIX_THREAD_SAFE_FUNCTIONS
132 is defined.
133 .SH SEE ALSO
134 .BR unlocked_stdio (3)