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

fread.3p (4980B)


  1. '\" et
  2. .TH FREAD "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. fread
  12. \(em binary input
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdio.h>
  17. .P
  18. size_t fread(void *restrict \fIptr\fP, size_t \fIsize\fP, size_t \fInitems\fP,
  19. FILE *restrict \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. \fIfread\fR()
  28. function shall read into the array pointed to by
  29. .IR ptr
  30. up to
  31. .IR nitems
  32. elements whose size is specified by
  33. .IR size
  34. in bytes, from the stream pointed to by
  35. .IR stream .
  36. For each object,
  37. .IR size
  38. calls shall be made to the
  39. \fIfgetc\fR()
  40. function and the results stored, in the order read, in an array of
  41. .BR "unsigned char"
  42. exactly overlaying the object. The file position indicator for the
  43. stream (if defined) shall be advanced by the number of bytes
  44. successfully read. If an error occurs, the resulting value of the file
  45. position indicator for the stream is unspecified. If a partial element
  46. is read, its value is unspecified.
  47. .P
  48. The
  49. \fIfread\fR()
  50. function may mark the last data access timestamp of the file
  51. associated with
  52. .IR stream
  53. for update. The last data access timestamp shall be
  54. marked for update by the first successful execution of
  55. \fIfgetc\fR(),
  56. \fIfgets\fR(),
  57. \fIfread\fR(),
  58. \fIfscanf\fR(),
  59. \fIgetc\fR(),
  60. \fIgetchar\fR(),
  61. \fIgetdelim\fR(),
  62. \fIgetline\fR(),
  63. \fIgets\fR(),
  64. or
  65. \fIscanf\fR()
  66. using
  67. .IR stream
  68. that returns data not supplied by a prior call to
  69. \fIungetc\fR().
  70. .SH "RETURN VALUE"
  71. Upon successful completion,
  72. \fIfread\fR()
  73. shall return the number of elements successfully read which is less than
  74. .IR nitems
  75. only if a read error or end-of-file is encountered. If
  76. .IR size
  77. or
  78. .IR nitems
  79. is 0,
  80. \fIfread\fR()
  81. shall return 0 and the contents of the array and the state of the
  82. stream remain unchanged. Otherwise, if a read error occurs, the error
  83. indicator for the stream shall be set,
  84. and
  85. .IR errno
  86. shall be set to indicate the error.
  87. .SH ERRORS
  88. Refer to
  89. .IR "\fIfgetc\fR\^(\|)".
  90. .LP
  91. .IR "The following sections are informative."
  92. .SH EXAMPLES
  93. .SS "Reading from a Stream"
  94. .P
  95. The following example transfers a single 100-byte fixed length
  96. record from the
  97. .IR fp
  98. stream into the array pointed to by
  99. .IR buf .
  100. .sp
  101. .RS 4
  102. .nf
  103. #include <stdio.h>
  104. \&...
  105. size_t elements_read;
  106. char buf[100];
  107. FILE *fp;
  108. \&...
  109. elements_read = fread(buf, sizeof(buf), 1, fp);
  110. \&...
  111. .fi
  112. .P
  113. .RE
  114. .P
  115. If a read error occurs,
  116. .IR elements_read
  117. will be zero but the number of bytes read from the stream could be
  118. anything from zero to
  119. .IR sizeof ( buf )\-1.
  120. .P
  121. The following example reads multiple single-byte elements from the
  122. .IR fp
  123. stream into the array pointed to by
  124. .IR buf .
  125. .sp
  126. .RS 4
  127. .nf
  128. #include <stdio.h>
  129. \&...
  130. size_t bytes_read;
  131. char buf[100];
  132. FILE *fp;
  133. \&...
  134. bytes_read = fread(buf, 1, sizeof(buf), fp);
  135. \&...
  136. .fi
  137. .P
  138. .RE
  139. .P
  140. If a read error occurs,
  141. .IR bytes_read
  142. will contain the number of bytes read from the stream.
  143. .SH "APPLICATION USAGE"
  144. The
  145. \fIferror\fR()
  146. or
  147. \fIfeof\fR()
  148. functions must be used to distinguish between an error condition and an
  149. end-of-file condition.
  150. .P
  151. Because of possible differences in element length and byte ordering,
  152. files written using
  153. \fIfwrite\fR()
  154. are application-dependent, and possibly cannot be read using
  155. \fIfread\fR()
  156. by a different application or by the same application on a different
  157. processor.
  158. .SH RATIONALE
  159. None.
  160. .SH "FUTURE DIRECTIONS"
  161. None.
  162. .SH "SEE ALSO"
  163. .IR "Section 2.5" ", " "Standard I/O Streams",
  164. .IR "\fIfeof\fR\^(\|)",
  165. .IR "\fIferror\fR\^(\|)",
  166. .IR "\fIfgetc\fR\^(\|)",
  167. .IR "\fIfopen\fR\^(\|)",
  168. .IR "\fIfscanf\fR\^(\|)",
  169. .IR "\fIgetc\fR\^(\|)",
  170. .IR "\fIgets\fR\^(\|)"
  171. .P
  172. The Base Definitions volume of POSIX.1\(hy2017,
  173. .IR "\fB<stdio.h>\fP"
  174. .\"
  175. .SH COPYRIGHT
  176. Portions of this text are reprinted and reproduced in electronic form
  177. from IEEE Std 1003.1-2017, Standard for Information Technology
  178. -- Portable Operating System Interface (POSIX), The Open Group Base
  179. Specifications Issue 7, 2018 Edition,
  180. Copyright (C) 2018 by the Institute of
  181. Electrical and Electronics Engineers, Inc and The Open Group.
  182. In the event of any discrepancy between this version and the original IEEE and
  183. The Open Group Standard, the original IEEE and The Open Group Standard
  184. is the referee document. The original Standard can be obtained online at
  185. http://www.opengroup.org/unix/online.html .
  186. .PP
  187. Any typographical or formatting errors that appear
  188. in this page are most likely
  189. to have been introduced during the conversion of the source files to
  190. man page format. To report such errors, see
  191. https://www.kernel.org/doc/man-pages/reporting_bugs.html .