fread(3p)

1FREAD(3P)                  POSIX Programmer's Manual                 FREAD(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       fread — binary input
13

SYNOPSIS

15       #include <stdio.h>
16
17       size_t fread(void *restrict ptr, size_t size, size_t nitems,
18           FILE *restrict stream);
19

DESCRIPTION

21       The functionality described on this reference page is aligned with  the
22       ISO C  standard.  Any  conflict between the requirements described here
23       and the ISO C standard is unintentional. This  volume  of  POSIX.1‐2017
24       defers to the ISO C standard.
25
26       The  fread() function shall read into the array pointed to by ptr up to
27       nitems elements whose size is specified by  size  in  bytes,  from  the
28       stream pointed to by stream.  For each object, size calls shall be made
29       to the fgetc() function and the results stored, in the order  read,  in
30       an array of unsigned char exactly overlaying the object. The file posi‐
31       tion indicator for the stream (if defined) shall  be  advanced  by  the
32       number  of  bytes  successfully read. If an error occurs, the resulting
33       value of the file position indicator for the stream is unspecified.  If
34       a partial element is read, its value is unspecified.
35
36       The  fread()  function  may  mark the last data access timestamp of the
37       file associated with stream for update. The last data access  timestamp
38       shall  be  marked  for  update  by  the  first  successful execution of
39       fgetc(), fgets(), fread(),  fscanf(),  getc(),  getchar(),  getdelim(),
40       getline(),  gets(),  or scanf() using stream that returns data not sup‐
41       plied by a prior call to ungetc().
42

RETURN VALUE

44       Upon successful completion, fread() shall return the number of elements
45       successfully  read  which  is  less than nitems only if a read error or
46       end-of-file is encountered. If size  or  nitems  is  0,  fread()  shall
47       return  0  and  the  contents  of the array and the state of the stream
48       remain unchanged. Otherwise, if a read error occurs, the error  indica‐
49       tor for the stream shall be set, and errno shall be set to indicate the
50       error.
51

ERRORS

53       Refer to fgetc().
54
55       The following sections are informative.
56

EXAMPLES

58   Reading from a Stream
59       The following example transfers a single 100-byte fixed  length  record
60       from the fp stream into the array pointed to by buf.
61
62
63           #include <stdio.h>
64           ...
65           size_t elements_read;
66           char buf[100];
67           FILE *fp;
68           ...
69           elements_read = fread(buf, sizeof(buf), 1, fp);
70           ...
71
72       If  a  read  error occurs, elements_read will be zero but the number of
73       bytes  read  from  the  stream  could  be   anything   from   zero   to
74       sizeof(buf)-1.
75
76       The  following  example reads multiple single-byte elements from the fp
77       stream into the array pointed to by buf.
78
79
80           #include <stdio.h>
81           ...
82           size_t bytes_read;
83           char buf[100];
84           FILE *fp;
85           ...
86           bytes_read = fread(buf, 1, sizeof(buf), fp);
87           ...
88
89       If a read error occurs, bytes_read will contain  the  number  of  bytes
90       read from the stream.
91

APPLICATION USAGE

93       The ferror() or feof() functions must be used to distinguish between an
94       error condition and an end-of-file condition.
95
96       Because of possible differences in element length  and  byte  ordering,
97       files  written  using  fwrite() are application-dependent, and possibly
98       cannot be read using fread() by a different application or by the  same
99       application on a different processor.
100

RATIONALE

102       None.
103

FUTURE DIRECTIONS

105       None.
106

COPYRIGHT

114       Portions of this text are reprinted and reproduced in  electronic  form
115       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
116       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
117       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
118       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
119       event of any discrepancy between this version and the original IEEE and
120       The Open Group Standard, the original IEEE and The Open Group  Standard
121       is  the  referee document. The original Standard can be obtained online
122       at http://www.opengroup.org/unix/online.html .
123
124       Any typographical or formatting errors that appear  in  this  page  are
125       most likely to have been introduced during the conversion of the source
126       files to man page format. To report such errors,  see  https://www.ker‐
127       nel.org/doc/man-pages/reporting_bugs.html .
128
129
130
131IEEE/The Open Group                  2017                            FREAD(3P)