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
11

NAME

13       flockfile, ftrylockfile, funlockfile — stdio locking functions
14

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

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

EXAMPLES

66       None.
67

APPLICATION USAGE

69       Applications using these functions may be subject  to  priority  inver‐
70       sion, as discussed in the Base Definitions volume of POSIX.1‐2008, Sec‐
71       tion 3.287, Priority Inversion.
72

RATIONALE

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

FUTURE DIRECTIONS

104       None.
105

SEE ALSO

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