Debian Codegraph @

upstream/debian-unstable/man3/fread.3

raw
1 '\" t
2 .\" Copyright 1990-1991, The Regents of the University of California.
3 .\" Copyright 2020, Arkadiusz Drabczyk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: BSD-4-Clause-UC
7 .\"
8 .TH fread 3 2026-02-10 "Linux man-pages 6.18"
9 .SH NAME
10 fread, fwrite \- binary stream input/output
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <stdio.h>
17 .P
18 .BR "size_t fread(" "size_t size, size_t n;"
19 .BI " void " ptr "[restrict " size " * " n ],
20 .BI " size_t " size ", size_t " n ,
21 .BI " FILE *restrict " stream );
22 .BR "size_t fwrite(" "size_t size, size_t n;"
23 .BI " const void " ptr "[restrict " size " * " n ],
24 .BI " size_t " size ", size_t " n ,
25 .BI " FILE *restrict " stream );
26 .fi
27 .SH DESCRIPTION
28 The function
29 .BR fread ()
30 reads
31 .I n
32 items of data, each
33 .I size
34 bytes long, from the stream pointed to by
35 .IR stream ,
36 storing them at the location given by
37 .IR ptr .
38 .P
39 The function
40 .BR fwrite ()
41 writes
42 .I n
43 items of data, each
44 .I size
45 bytes long, to the stream pointed to by
46 .IR stream ,
47 obtaining them from the location given by
48 .IR ptr .
49 .P
50 For nonlocking counterparts, see
51 .BR unlocked_stdio (3).
52 .SH RETURN VALUE
53 On success,
54 .BR fread ()
55 and
56 .BR fwrite ()
57 return the number of items read or written.
58 This number equals the number of bytes transferred only when
59 .I size
60 is 1.
61 If an error occurs, or the end of the file is reached,
62 the return value is a short item count (or zero).
63 .P
64 The file position indicator for the stream is advanced by the number
65 of bytes successfully read or written.
66 .P
67 .BR fread ()
68 does not distinguish between end-of-file and error, and callers must use
69 .BR feof (3)
70 and
71 .BR ferror (3)
72 to determine which occurred.
73 .SH ATTRIBUTES
74 For an explanation of the terms used in this section, see
75 .BR attributes (7).
76 .TS
77 allbox;
78 lbx lb lb
79 l l l.
80 Interface Attribute Value
81 T{
82 .na
83 .nh
84 .BR fread (),
85 .BR fwrite ()
86 T} Thread safety MT-Safe
87 .TE
88 .SH STANDARDS
89 C11, POSIX.1-2008.
90 .SH HISTORY
91 POSIX.1-2001, C89.
92 .SH EXAMPLES
93 The program below demonstrates the use of
94 .BR fread ()
95 by parsing /bin/sh ELF executable in binary mode and printing its
96 magic and class:
97 .P
98 .in +4n
99 .EX
100 .RB $ " ./a.out" ;
101 ELF magic: 0x7f454c46
102 Class: 0x02
103 .EE
104 .in
105 .SS Program source
106 \&
107 .\" SRC BEGIN (fread.c)
108 .EX
109 #include <stdcountof.h>
110 #include <stdio.h>
111 #include <stdlib.h>
112 \&
113 int
114 main(void)
115 {
116 FILE *fp;
117 size_t ret;
118 unsigned char buffer[4];
119 \&
120 fp = fopen("/bin/sh", "rb");
121 if (!fp) {
122 perror("fopen");
123 return EXIT_FAILURE;
124 }
125 \&
126 ret = fread(buffer, sizeof(*buffer), countof(buffer), fp);
127 if (ret != countof(buffer)) {
128 fprintf(stderr, "fread() failed: %zu\[rs]n", ret);
129 exit(EXIT_FAILURE);
130 }
131 \&
132 printf("ELF magic: %#04x%02x%02x%02x\[rs]n", buffer[0], buffer[1],
133 buffer[2], buffer[3]);
134 \&
135 ret = fread(buffer, 1, 1, fp);
136 if (ret != 1) {
137 fprintf(stderr, "fread() failed: %zu\[rs]n", ret);
138 exit(EXIT_FAILURE);
139 }
140 \&
141 printf("Class: %#04x\[rs]n", buffer[0]);
142 \&
143 fclose(fp);
144 \&
145 exit(EXIT_SUCCESS);
146 }
147 .EE
148 .\" SRC END
149 .SH SEE ALSO
150 .BR read (2),
151 .BR write (2),
152 .BR feof (3),
153 .BR ferror (3),
154 .BR unlocked_stdio (3)