flockfile.3p (5960B)
- '\" et
- .TH FLOCKFILE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- flockfile,
- ftrylockfile,
- funlockfile
- \(em stdio locking functions
- .SH SYNOPSIS
- .LP
- .nf
- #include <stdio.h>
- .P
- void flockfile(FILE *\fIfile\fP);
- int ftrylockfile(FILE *\fIfile\fP);
- void funlockfile(FILE *\fIfile\fP);
- .fi
- .SH DESCRIPTION
- These functions shall provide for explicit application-level locking of
- stdio (\c
- .BR "FILE *" )
- objects. These functions can be used by a thread to delineate a
- sequence of I/O statements that are executed as a unit.
- .P
- The
- \fIflockfile\fR()
- function shall acquire for a thread ownership of a (\c
- .BR "FILE *" )
- object.
- .P
- The
- \fIftrylockfile\fR()
- function shall acquire for a thread ownership of a (\c
- .BR "FILE *" )
- object if the object is available;
- \fIftrylockfile\fR()
- is a non-blocking version of
- \fIflockfile\fR().
- .P
- The
- \fIfunlockfile\fR()
- function shall relinquish the ownership granted to the thread.
- The behavior is undefined if a thread other than the current owner
- calls the
- \fIfunlockfile\fR()
- function.
- .P
- The functions shall behave as if there is a lock count associated with
- each (\c
- .BR "FILE *" )
- object. This count is implicitly initialized to zero when the (\c
- .BR "FILE *" )
- object is created. The (\c
- .BR "FILE *" )
- object is unlocked when the count is zero. When the count is positive,
- a single thread owns the (\c
- .BR "FILE *" )
- object. When the
- \fIflockfile\fR()
- function is called, if the count is zero or if the count is positive
- and the caller owns the (\c
- .BR "FILE *" )
- object, the count shall be incremented. Otherwise, the calling thread
- shall be suspended, waiting for the count to return to zero. Each call
- to
- \fIfunlockfile\fR()
- shall decrement the count. This allows matching calls to
- \fIflockfile\fR()
- (or successful calls to
- \fIftrylockfile\fR())
- and
- \fIfunlockfile\fR()
- to be nested.
- .P
- All functions that reference (\c
- .BR "FILE *" )
- objects, except those with names ending in
- .IR _unlocked ,
- shall behave as if they use
- \fIflockfile\fR()
- and
- \fIfunlockfile\fR()
- internally to obtain ownership of these (\c
- .BR "FILE *" )
- objects.
- .SH "RETURN VALUE"
- None for
- \fIflockfile\fR()
- and
- \fIfunlockfile\fR().
- .P
- The
- \fIftrylockfile\fR()
- function shall return zero for success and non-zero to indicate
- that the lock cannot be acquired.
- .SH ERRORS
- No errors are defined.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- Applications using these functions may be subject to priority inversion,
- as discussed in the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 3.291" ", " "Priority Inversion".
- .P
- A call to
- \fIexit\fR()
- can block until locked streams are unlocked because a thread having
- ownership of a (\c
- .BR FILE *)
- object blocks all function calls that reference that (\c
- .BR FILE *)
- object (except those with names ending in _unlocked) from other threads,
- including calls to
- \fIexit\fR().
- .SH RATIONALE
- The
- \fIflockfile\fR()
- and
- \fIfunlockfile\fR()
- functions provide an orthogonal mutual-exclusion lock for each
- .BR FILE .
- The
- \fIftrylockfile\fR()
- function provides a non-blocking attempt to acquire a file lock,
- analogous to
- \fIpthread_mutex_trylock\fR().
- .P
- These locks behave as if they are the same as those used internally by
- .IR stdio
- for thread-safety.
- This both provides thread-safety of these functions without requiring a
- second level of internal locking and allows functions in
- .IR stdio
- to be implemented in terms of other
- .IR stdio
- functions.
- .P
- Application developers and implementors should be aware that there are
- potential deadlock problems on
- .BR FILE
- objects. For example, the line-buffered flushing semantics of
- .IR stdio
- (requested via {_IOLBF})
- require that certain input operations sometimes cause the buffered
- contents of implementation-defined line-buffered output streams to be
- flushed. If two threads each hold the lock on the other's
- .BR FILE ,
- deadlock ensues. This type of deadlock can be avoided by acquiring
- .BR FILE
- locks in a consistent order. In particular, the line-buffered output
- stream deadlock can typically be avoided by acquiring locks on input
- streams before locks on output streams if a thread would be acquiring
- both.
- .P
- In summary, threads sharing
- .IR stdio
- streams with other threads can use
- \fIflockfile\fR()
- and
- \fIfunlockfile\fR()
- to cause sequences of I/O performed by a single thread to be kept
- bundled. The only case where the use of
- \fIflockfile\fR()
- and
- \fIfunlockfile\fR()
- is required is to provide a scope protecting uses of the
- .IR *_unlocked
- functions/macros. This moves the cost/performance tradeoff to the
- optimal point.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIexit\fR\^(\|)",
- .IR "\fIgetc_unlocked\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 3.291" ", " "Priority Inversion",
- .IR "\fB<stdio.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .