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

fgetwc.3p (4997B)


  1. '\" et
  2. .TH FGETWC "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. fgetwc
  12. \(em get a wide-character code from a stream
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdio.h>
  17. #include <wchar.h>
  18. .P
  19. wint_t fgetwc(FILE *\fIstream\fP);
  20. .fi
  21. .SH DESCRIPTION
  22. The functionality described on this reference page is aligned with the
  23. ISO\ C standard. Any conflict between the requirements described here and the
  24. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  25. .P
  26. The
  27. \fIfgetwc\fR()
  28. function shall obtain the next character (if present) from the input
  29. stream pointed to by
  30. .IR stream ,
  31. convert that to the corresponding wide-character code, and advance the
  32. associated file position indicator for the stream (if defined).
  33. .P
  34. If an error occurs, the resulting value of the file position indicator
  35. for the stream is unspecified.
  36. .P
  37. The
  38. \fIfgetwc\fR()
  39. function may mark the last data access timestamp of the file associated
  40. with
  41. .IR stream
  42. for update. The last data access timestamp shall be marked for update
  43. by the first successful execution of
  44. \fIfgetwc\fR(),
  45. \fIfgetws\fR(),
  46. \fIfwscanf\fR(),
  47. \fIgetwc\fR(),
  48. \fIgetwchar\fR(),
  49. \fIvfwscanf\fR(),
  50. \fIvwscanf\fR(),
  51. or
  52. \fIwscanf\fR()
  53. using
  54. .IR stream
  55. that returns data not supplied by a prior call to
  56. \fIungetwc\fR().
  57. .P
  58. The
  59. \fIfgetwc\fR()
  60. function shall not change the setting of
  61. .IR errno
  62. if successful.
  63. .SH "RETURN VALUE"
  64. Upon successful completion, the
  65. \fIfgetwc\fR()
  66. function shall return the wide-character code of the character read from the
  67. input stream pointed to by
  68. .IR stream
  69. converted to a type
  70. .BR wint_t .
  71. If the end-of-file indicator for the stream is set, or if the stream is
  72. at end-of-file, the end-of-file indicator for the stream shall be set
  73. and
  74. \fIfgetwc\fR()
  75. shall return WEOF. If a read error occurs, the error indicator for the
  76. stream shall be set,
  77. \fIfgetwc\fR()
  78. shall return WEOF,
  79. and shall set
  80. .IR errno
  81. to indicate the error.
  82. If an encoding error occurs, the error indicator for the stream
  83. shall be set,
  84. \fIfgetwc\fR()
  85. shall return WEOF, and shall set
  86. .IR errno
  87. to indicate the error.
  88. .SH ERRORS
  89. The
  90. \fIfgetwc\fR()
  91. function shall fail if data needs to be read and:
  92. .TP
  93. .BR EAGAIN
  94. The O_NONBLOCK flag is set for the file descriptor underlying
  95. .IR stream
  96. and the thread would be delayed in the
  97. \fIfgetwc\fR()
  98. operation.
  99. .TP
  100. .BR EBADF
  101. The file descriptor underlying
  102. .IR stream
  103. is not a valid file descriptor open for reading.
  104. .TP
  105. .BR EILSEQ
  106. The data obtained from the input stream does not form a valid
  107. character.
  108. .TP
  109. .BR EINTR
  110. The read operation was terminated due to the receipt of a signal, and
  111. no data was transferred.
  112. .TP
  113. .BR EIO
  114. A physical I/O error has occurred, or the process is in a background
  115. process group attempting to read from its controlling terminal, and
  116. either the calling thread is blocking SIGTTIN or the process is ignoring
  117. SIGTTIN or the process group of the process is orphaned.
  118. This error may also be generated for implementation-defined reasons.
  119. .TP
  120. .BR EOVERFLOW
  121. The file is a regular file and an attempt was made to read at or beyond
  122. the offset maximum associated with the corresponding stream.
  123. .br
  124. .P
  125. The
  126. \fIfgetwc\fR()
  127. function may fail if:
  128. .TP
  129. .BR ENOMEM
  130. Insufficient storage space is available.
  131. .TP
  132. .BR ENXIO
  133. A request was made of a nonexistent device, or the request was outside
  134. the capabilities of the device.
  135. .LP
  136. .IR "The following sections are informative."
  137. .SH EXAMPLES
  138. None.
  139. .SH "APPLICATION USAGE"
  140. The
  141. \fIferror\fR()
  142. or
  143. \fIfeof\fR()
  144. functions must be used to distinguish between an error condition and an
  145. end-of-file condition.
  146. .SH RATIONALE
  147. None.
  148. .SH "FUTURE DIRECTIONS"
  149. None.
  150. .SH "SEE ALSO"
  151. .IR "Section 2.5" ", " "Standard I/O Streams",
  152. .IR "\fIfeof\fR\^(\|)",
  153. .IR "\fIferror\fR\^(\|)",
  154. .IR "\fIfopen\fR\^(\|)"
  155. .P
  156. The Base Definitions volume of POSIX.1\(hy2017,
  157. .IR "\fB<stdio.h>\fP",
  158. .IR "\fB<wchar.h>\fP"
  159. .\"
  160. .SH COPYRIGHT
  161. Portions of this text are reprinted and reproduced in electronic form
  162. from IEEE Std 1003.1-2017, Standard for Information Technology
  163. -- Portable Operating System Interface (POSIX), The Open Group Base
  164. Specifications Issue 7, 2018 Edition,
  165. Copyright (C) 2018 by the Institute of
  166. Electrical and Electronics Engineers, Inc and The Open Group.
  167. In the event of any discrepancy between this version and the original IEEE and
  168. The Open Group Standard, the original IEEE and The Open Group Standard
  169. is the referee document. The original Standard can be obtained online at
  170. http://www.opengroup.org/unix/online.html .
  171. .PP
  172. Any typographical or formatting errors that appear
  173. in this page are most likely
  174. to have been introduced during the conversion of the source files to
  175. man page format. To report such errors, see
  176. https://www.kernel.org/doc/man-pages/reporting_bugs.html .