1FLOCKFILE(3P)              POSIX Programmer's Manual             FLOCKFILE(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       flockfile, ftrylockfile, funlockfile — stdio locking functions
13

SYNOPSIS

15       #include <stdio.h>
16
17       void flockfile(FILE *file);
18       int ftrylockfile(FILE *file);
19       void funlockfile(FILE *file);
20

DESCRIPTION

22       These functions shall provide for explicit application-level locking of
23       stdio  (FILE  *)  objects.  These  functions can be used by a thread to
24       delineate a sequence of I/O statements that are executed as a unit.
25
26       The flockfile() function shall acquire for  a  thread  ownership  of  a
27       (FILE *) object.
28
29       The  ftrylockfile()  function shall acquire for a thread ownership of a
30       (FILE *) object if the object is available; ftrylockfile()  is  a  non-
31       blocking version of flockfile().
32
33       The  funlockfile()  function  shall relinquish the ownership granted to
34       the thread.  The behavior is undefined if a thread other than the  cur‐
35       rent owner calls the funlockfile() function.
36
37       The  functions shall behave as if there is a lock count associated with
38       each (FILE *) object. This count is implicitly initialized to zero when
39       the  (FILE  *)  object is created. The (FILE *) object is unlocked when
40       the count is zero. When the count is positive, a single thread owns the
41       (FILE  *) object. When the flockfile() function is called, if the count
42       is zero or if the count is positive and the caller owns  the  (FILE  *)
43       object,  the  count shall be incremented. Otherwise, the calling thread
44       shall be suspended, waiting for the count to return to zero. Each  call
45       to  funlockfile() shall decrement the count. This allows matching calls
46       to flockfile() (or successful calls  to  ftrylockfile())  and  funlock‐
47       file() to be nested.
48
49       All  functions that reference (FILE *) objects, except those with names
50       ending in _unlocked, shall behave as if they use flockfile()  and  fun‐
51       lockfile() internally to obtain ownership of these (FILE *) objects.
52

RETURN VALUE

54       None for flockfile() and funlockfile().
55
56       The  ftrylockfile() function shall return zero for success and non-zero
57       to indicate that the lock cannot be acquired.
58

ERRORS

60       No errors are defined.
61
62       The following sections are informative.
63

EXAMPLES

65       None.
66

APPLICATION USAGE

68       Applications using these functions may be subject  to  priority  inver‐
69       sion, as discussed in the Base Definitions volume of POSIX.1‐2017, Sec‐
70       tion 3.291, Priority Inversion.
71
72       A call to exit() can block until locked streams are unlocked because  a
73       thread  having  ownership of a (FILE*) object blocks all function calls
74       that reference that (FILE*) object (except those with names  ending  in
75       _unlocked) from other threads, including calls to exit().
76

RATIONALE

78       The  flockfile()  and  funlockfile()  functions  provide  an orthogonal
79       mutual-exclusion lock for each FILE.  The ftrylockfile() function  pro‐
80       vides  a  non-blocking  attempt  to  acquire  a file lock, analogous to
81       pthread_mutex_trylock().
82
83       These locks behave as if they are the same as those used internally  by
84       stdio  for  thread-safety.   This  both provides thread-safety of these
85       functions without requiring a second  level  of  internal  locking  and
86       allows  functions  in  stdio  to be implemented in terms of other stdio
87       functions.
88
89       Application developers and implementors should be aware that there  are
90       potential  deadlock  problems  on  FILE objects. For example, the line-
91       buffered flushing semantics of stdio (requested via  {_IOLBF})  require
92       that  certain input operations sometimes cause the buffered contents of
93       implementation-defined line-buffered output streams to be  flushed.  If
94       two  threads  each  hold the lock on the other's FILE, deadlock ensues.
95       This type of deadlock can be avoided by acquiring FILE locks in a  con‐
96       sistent  order. In particular, the line-buffered output stream deadlock
97       can typically be avoided by acquiring locks  on  input  streams  before
98       locks on output streams if a thread would be acquiring both.
99
100       In  summary,  threads  sharing stdio streams with other threads can use
101       flockfile() and funlockfile() to cause sequences of I/O performed by  a
102       single thread to be kept bundled. The only case where the use of flock‐
103       file() and funlockfile() is required is to provide a  scope  protecting
104       uses  of  the  *_unlocked functions/macros. This moves the cost/perfor‐
105       mance tradeoff to the optimal point.
106

FUTURE DIRECTIONS

108       None.
109

SEE ALSO

111       exit(), getc_unlocked()
112
113       The Base Definitions volume of POSIX.1‐2017,  Section  3.291,  Priority
114       Inversion, <stdio.h>
115
117       Portions  of  this text are reprinted and reproduced in electronic form
118       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
119       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
120       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
121       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
122       event of any discrepancy between this version and the original IEEE and
123       The  Open Group Standard, the original IEEE and The Open Group Standard
124       is the referee document. The original Standard can be  obtained  online
125       at http://www.opengroup.org/unix/online.html .
126
127       Any  typographical  or  formatting  errors that appear in this page are
128       most likely to have been introduced during the conversion of the source
129       files  to  man page format. To report such errors, see https://www.ker
130       nel.org/doc/man-pages/reporting_bugs.html .
131
132
133
134IEEE/The Open Group                  2017                        FLOCKFILE(3P)
Impressum