logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

flockfile.3p (5960B)


  1. '\" et
  2. .TH FLOCKFILE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. flockfile,
  12. ftrylockfile,
  13. funlockfile
  14. \(em stdio locking functions
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <stdio.h>
  19. .P
  20. void flockfile(FILE *\fIfile\fP);
  21. int ftrylockfile(FILE *\fIfile\fP);
  22. void funlockfile(FILE *\fIfile\fP);
  23. .fi
  24. .SH DESCRIPTION
  25. These functions shall provide for explicit application-level locking of
  26. stdio (\c
  27. .BR "FILE *" )
  28. objects. These functions can be used by a thread to delineate a
  29. sequence of I/O statements that are executed as a unit.
  30. .P
  31. The
  32. \fIflockfile\fR()
  33. function shall acquire for a thread ownership of a (\c
  34. .BR "FILE *" )
  35. object.
  36. .P
  37. The
  38. \fIftrylockfile\fR()
  39. function shall acquire for a thread ownership of a (\c
  40. .BR "FILE *" )
  41. object if the object is available;
  42. \fIftrylockfile\fR()
  43. is a non-blocking version of
  44. \fIflockfile\fR().
  45. .P
  46. The
  47. \fIfunlockfile\fR()
  48. function shall relinquish the ownership granted to the thread.
  49. The behavior is undefined if a thread other than the current owner
  50. calls the
  51. \fIfunlockfile\fR()
  52. function.
  53. .P
  54. The functions shall behave as if there is a lock count associated with
  55. each (\c
  56. .BR "FILE *" )
  57. object. This count is implicitly initialized to zero when the (\c
  58. .BR "FILE *" )
  59. object is created. The (\c
  60. .BR "FILE *" )
  61. object is unlocked when the count is zero. When the count is positive,
  62. a single thread owns the (\c
  63. .BR "FILE *" )
  64. object. When the
  65. \fIflockfile\fR()
  66. function is called, if the count is zero or if the count is positive
  67. and the caller owns the (\c
  68. .BR "FILE *" )
  69. object, the count shall be incremented. Otherwise, the calling thread
  70. shall be suspended, waiting for the count to return to zero. Each call
  71. to
  72. \fIfunlockfile\fR()
  73. shall decrement the count. This allows matching calls to
  74. \fIflockfile\fR()
  75. (or successful calls to
  76. \fIftrylockfile\fR())
  77. and
  78. \fIfunlockfile\fR()
  79. to be nested.
  80. .P
  81. All functions that reference (\c
  82. .BR "FILE *" )
  83. objects, except those with names ending in
  84. .IR _unlocked ,
  85. shall behave as if they use
  86. \fIflockfile\fR()
  87. and
  88. \fIfunlockfile\fR()
  89. internally to obtain ownership of these (\c
  90. .BR "FILE *" )
  91. objects.
  92. .SH "RETURN VALUE"
  93. None for
  94. \fIflockfile\fR()
  95. and
  96. \fIfunlockfile\fR().
  97. .P
  98. The
  99. \fIftrylockfile\fR()
  100. function shall return zero for success and non-zero to indicate
  101. that the lock cannot be acquired.
  102. .SH ERRORS
  103. No errors are defined.
  104. .LP
  105. .IR "The following sections are informative."
  106. .SH EXAMPLES
  107. None.
  108. .SH "APPLICATION USAGE"
  109. Applications using these functions may be subject to priority inversion,
  110. as discussed in the Base Definitions volume of POSIX.1\(hy2017,
  111. .IR "Section 3.291" ", " "Priority Inversion".
  112. .P
  113. A call to
  114. \fIexit\fR()
  115. can block until locked streams are unlocked because a thread having
  116. ownership of a (\c
  117. .BR FILE *)
  118. object blocks all function calls that reference that (\c
  119. .BR FILE *)
  120. object (except those with names ending in _unlocked) from other threads,
  121. including calls to
  122. \fIexit\fR().
  123. .SH RATIONALE
  124. The
  125. \fIflockfile\fR()
  126. and
  127. \fIfunlockfile\fR()
  128. functions provide an orthogonal mutual-exclusion lock for each
  129. .BR FILE .
  130. The
  131. \fIftrylockfile\fR()
  132. function provides a non-blocking attempt to acquire a file lock,
  133. analogous to
  134. \fIpthread_mutex_trylock\fR().
  135. .P
  136. These locks behave as if they are the same as those used internally by
  137. .IR stdio
  138. for thread-safety.
  139. This both provides thread-safety of these functions without requiring a
  140. second level of internal locking and allows functions in
  141. .IR stdio
  142. to be implemented in terms of other
  143. .IR stdio
  144. functions.
  145. .P
  146. Application developers and implementors should be aware that there are
  147. potential deadlock problems on
  148. .BR FILE
  149. objects. For example, the line-buffered flushing semantics of
  150. .IR stdio
  151. (requested via {_IOLBF})
  152. require that certain input operations sometimes cause the buffered
  153. contents of implementation-defined line-buffered output streams to be
  154. flushed. If two threads each hold the lock on the other's
  155. .BR FILE ,
  156. deadlock ensues. This type of deadlock can be avoided by acquiring
  157. .BR FILE
  158. locks in a consistent order. In particular, the line-buffered output
  159. stream deadlock can typically be avoided by acquiring locks on input
  160. streams before locks on output streams if a thread would be acquiring
  161. both.
  162. .P
  163. In summary, threads sharing
  164. .IR stdio
  165. streams with other threads can use
  166. \fIflockfile\fR()
  167. and
  168. \fIfunlockfile\fR()
  169. to cause sequences of I/O performed by a single thread to be kept
  170. bundled. The only case where the use of
  171. \fIflockfile\fR()
  172. and
  173. \fIfunlockfile\fR()
  174. is required is to provide a scope protecting uses of the
  175. .IR *_unlocked
  176. functions/macros. This moves the cost/performance tradeoff to the
  177. optimal point.
  178. .SH "FUTURE DIRECTIONS"
  179. None.
  180. .SH "SEE ALSO"
  181. .IR "\fIexit\fR\^(\|)",
  182. .IR "\fIgetc_unlocked\fR\^(\|)"
  183. .P
  184. The Base Definitions volume of POSIX.1\(hy2017,
  185. .IR "Section 3.291" ", " "Priority Inversion",
  186. .IR "\fB<stdio.h>\fP"
  187. .\"
  188. .SH COPYRIGHT
  189. Portions of this text are reprinted and reproduced in electronic form
  190. from IEEE Std 1003.1-2017, Standard for Information Technology
  191. -- Portable Operating System Interface (POSIX), The Open Group Base
  192. Specifications Issue 7, 2018 Edition,
  193. Copyright (C) 2018 by the Institute of
  194. Electrical and Electronics Engineers, Inc and The Open Group.
  195. In the event of any discrepancy between this version and the original IEEE and
  196. The Open Group Standard, the original IEEE and The Open Group Standard
  197. is the referee document. The original Standard can be obtained online at
  198. http://www.opengroup.org/unix/online.html .
  199. .PP
  200. Any typographical or formatting errors that appear
  201. in this page are most likely
  202. to have been introduced during the conversion of the source files to
  203. man page format. To report such errors, see
  204. https://www.kernel.org/doc/man-pages/reporting_bugs.html .