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

getc_unlocked.3p (6412B)


  1. '\" et
  2. .TH GETC_UNLOCKED "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. getc_unlocked,
  12. getchar_unlocked,
  13. putc_unlocked,
  14. putchar_unlocked
  15. \(em stdio with explicit client locking
  16. .SH SYNOPSIS
  17. .LP
  18. .nf
  19. #include <stdio.h>
  20. .P
  21. int getc_unlocked(FILE *\fIstream\fP);
  22. int getchar_unlocked(void);
  23. int putc_unlocked(int \fIc\fP, FILE *\fIstream\fP);
  24. int putchar_unlocked(int \fIc\fP);
  25. .fi
  26. .SH DESCRIPTION
  27. Versions of the functions
  28. \fIgetc\fR(),
  29. \fIgetchar\fR(),
  30. \fIputc\fR(),
  31. and
  32. \fIputchar\fR()
  33. respectively named
  34. \fIgetc_unlocked\fR(),
  35. \fIgetchar_unlocked\fR(),
  36. \fIputc_unlocked\fR(),
  37. and
  38. \fIputchar_unlocked\fR()
  39. shall be provided which are functionally equivalent to the original
  40. versions, with the exception that they are not required to be
  41. implemented in a fully thread-safe manner. They shall be thread-safe
  42. when used within a scope protected by
  43. \fIflockfile\fR()
  44. (or
  45. \fIftrylockfile\fR())
  46. and
  47. \fIfunlockfile\fR().
  48. These functions can safely be used in a multi-threaded program if and
  49. only if they are called while the invoking thread owns the (\c
  50. .BR "FILE *" )
  51. object, as is the case after a successful call to the
  52. \fIflockfile\fR()
  53. or
  54. \fIftrylockfile\fR()
  55. functions.
  56. .P
  57. If
  58. \fIgetc_unlocked\fR()
  59. or
  60. \fIputc_unlocked\fR()
  61. are implemented as macros they may evaluate
  62. .IR stream
  63. more than once, so the
  64. .IR stream
  65. argument should never be an expression with side-effects.
  66. .SH "RETURN VALUE"
  67. See
  68. .IR "\fIgetc\fR\^(\|)",
  69. .IR "\fIgetchar\fR\^(\|)",
  70. .IR "\fIputc\fR\^(\|)",
  71. and
  72. .IR "\fIputchar\fR\^(\|)".
  73. .SH ERRORS
  74. See
  75. .IR "\fIgetc\fR\^(\|)",
  76. .IR "\fIgetchar\fR\^(\|)",
  77. .IR "\fIputc\fR\^(\|)",
  78. and
  79. .IR "\fIputchar\fR\^(\|)".
  80. .LP
  81. .IR "The following sections are informative."
  82. .SH EXAMPLES
  83. None.
  84. .SH "APPLICATION USAGE"
  85. Since they may be implemented as macros,
  86. \fIgetc_unlocked\fR()
  87. and
  88. \fIputc_unlocked\fR()
  89. may treat incorrectly a
  90. .IR stream
  91. argument with side-effects. In particular, \fIgetc_unlocked\fP(*f++)
  92. and \fIputc_unlocked\fP(c,*f++) do not necessarily work as expected.
  93. Therefore, use of these functions in such situations should be preceded
  94. by the following statement as appropriate:
  95. .sp
  96. .RS 4
  97. .nf
  98. #undef getc_unlocked
  99. #undef putc_unlocked
  100. .fi
  101. .P
  102. .RE
  103. .SH RATIONALE
  104. Some I/O functions are typically implemented as macros for performance
  105. reasons (for example,
  106. \fIputc\fR()
  107. and
  108. \fIgetc\fR()).
  109. For safety, they need to be synchronized, but it is often too expensive
  110. to synchronize on every character. Nevertheless, it was felt that the
  111. safety concerns were more important; consequently, the
  112. \fIgetc\fR(),
  113. \fIgetchar\fR(),
  114. \fIputc\fR(),
  115. and
  116. \fIputchar\fR()
  117. functions are required to be thread-safe. However, unlocked versions
  118. are also provided with names that clearly indicate the unsafe nature of
  119. their operation but can be used to exploit their higher performance.
  120. These unlocked versions can be safely used only within explicitly
  121. locked program regions, using exported locking primitives. In
  122. particular, a sequence such as:
  123. .sp
  124. .RS 4
  125. .nf
  126. flockfile(fileptr);
  127. putc_unlocked(\(aq1\(aq, fileptr);
  128. putc_unlocked(\(aq\en\(aq, fileptr);
  129. fprintf(fileptr, "Line 2\en");
  130. funlockfile(fileptr);
  131. .fi
  132. .P
  133. .RE
  134. .br
  135. .P
  136. is permissible, and results in the text sequence:
  137. .sp
  138. .RS 4
  139. .nf
  140. 1
  141. Line 2
  142. .fi
  143. .P
  144. .RE
  145. .P
  146. being printed without being interspersed with output from other
  147. threads.
  148. .P
  149. It would be wrong to have the standard names such as
  150. \fIgetc\fR(),
  151. \fIputc\fR(),
  152. and so on, map to the ``faster, but unsafe'' rather than the ``slower,
  153. but safe'' versions. In either case, you would still want to inspect
  154. all uses of
  155. \fIgetc\fR(),
  156. \fIputc\fR(),
  157. and so on, by hand when converting existing code. Choosing the safe
  158. bindings as the default, at least, results in correct code and
  159. maintains the ``atomicity at the function'' invariant. To do otherwise
  160. would introduce gratuitous synchronization errors into converted code.
  161. Other routines that modify the
  162. .IR stdio
  163. (\c
  164. .BR "FILE *" )
  165. structures or buffers are also safely synchronized.
  166. .P
  167. Note that there is no need for functions of the form
  168. \fIgetc_locked\fR(),
  169. \fIputc_locked\fR(),
  170. and so on, since this is the functionality of
  171. \fIgetc\fR(),
  172. \fIputc\fR(),
  173. .IR "et al" .
  174. It would be inappropriate to use a feature test macro to
  175. switch a macro definition of
  176. \fIgetc\fR()
  177. between
  178. \fIgetc_locked\fR()
  179. and
  180. \fIgetc_unlocked\fR(),
  181. since the ISO\ C standard requires an actual function to exist,
  182. a function whose behavior could not be changed by the
  183. feature test macro. Also, providing both the
  184. \fIxxx_locked\fR()
  185. and
  186. \fIxxx_unlocked\fR()
  187. forms leads to the confusion of whether the suffix describes the
  188. behavior of the function or the circumstances under which it should be
  189. used.
  190. .P
  191. Three additional routines,
  192. \fIflockfile\fR(),
  193. \fIftrylockfile\fR(),
  194. and
  195. \fIfunlockfile\fR()
  196. (which may be macros), are provided to allow the user to delineate a
  197. sequence of I/O statements that are executed synchronously.
  198. .P
  199. The
  200. \fIungetc\fR()
  201. function is infrequently called relative to the other functions/macros
  202. so no unlocked variation is needed.
  203. .SH "FUTURE DIRECTIONS"
  204. None.
  205. .SH "SEE ALSO"
  206. .IR "Section 2.5" ", " "Standard I/O Streams",
  207. .IR "\fIflockfile\fR\^(\|)",
  208. .IR "\fIgetc\fR\^(\|)",
  209. .IR "\fIgetchar\fR\^(\|)",
  210. .IR "\fIputc\fR\^(\|)",
  211. .IR "\fIputchar\fR\^(\|)"
  212. .P
  213. The Base Definitions volume of POSIX.1\(hy2017,
  214. .IR "\fB<stdio.h>\fP"
  215. .\"
  216. .SH COPYRIGHT
  217. Portions of this text are reprinted and reproduced in electronic form
  218. from IEEE Std 1003.1-2017, Standard for Information Technology
  219. -- Portable Operating System Interface (POSIX), The Open Group Base
  220. Specifications Issue 7, 2018 Edition,
  221. Copyright (C) 2018 by the Institute of
  222. Electrical and Electronics Engineers, Inc and The Open Group.
  223. In the event of any discrepancy between this version and the original IEEE and
  224. The Open Group Standard, the original IEEE and The Open Group Standard
  225. is the referee document. The original Standard can be obtained online at
  226. http://www.opengroup.org/unix/online.html .
  227. .PP
  228. Any typographical or formatting errors that appear
  229. in this page are most likely
  230. to have been introduced during the conversion of the source files to
  231. man page format. To report such errors, see
  232. https://www.kernel.org/doc/man-pages/reporting_bugs.html .