]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da | 2 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
8ef8ccaa | 3 | .\" and Copyright (c) 2020 Arkadiusz Drabczyk <arkadiusz@drabczyk.org> |
fea681da MK |
4 | .\" All rights reserved. |
5 | .\" | |
6 | .\" This code is derived from software contributed to Berkeley by | |
7 | .\" Chris Torek and the American National Standards Committee X3, | |
8 | .\" on Information Processing Systems. | |
9 | .\" | |
47009d5e | 10 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
11 | .\" |
12 | .\" @(#)fread.3 6.6 (Berkeley) 6/29/91 | |
13 | .\" | |
14 | .\" Converted for Linux, Mon Nov 29 15:37:33 1993, faith@cs.unc.edu | |
15 | .\" Sun Feb 19 21:26:54 1995 by faith, return values | |
16 | .\" Modified Thu Apr 20 20:43:53 1995 by Jim Van Zandt <jrv@vanzandt.mv.com> | |
17 | .\" Modified Fri May 17 10:21:51 1996 by Martin Schulze <joey@infodrom.north.de> | |
18 | .\" | |
4c1c5274 | 19 | .TH fread 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
20 | .SH NAME |
21 | fread, fwrite \- binary stream input/output | |
cfba38f4 AC |
22 | .SH LIBRARY |
23 | Standard C library | |
24 | .RI ( libc ", " \-lc ) | |
fea681da | 25 | .SH SYNOPSIS |
b9f02710 | 26 | .nf |
fea681da | 27 | .B #include <stdio.h> |
68e4db0a | 28 | .PP |
c64cd13e AC |
29 | .BI "size_t fread(void " ptr "[restrict ." size " * ." nmemb ], |
30 | .BI " size_t " size ", size_t " nmemb , | |
93a4d1d5 | 31 | .BI " FILE *restrict " stream ); |
c64cd13e AC |
32 | .BI "size_t fwrite(const void " ptr "[restrict ." size " * ." nmemb ], |
33 | .BI " size_t " size ", size_t " nmemb , | |
93a4d1d5 | 34 | .BI " FILE *restrict " stream ); |
b9f02710 | 35 | .fi |
fea681da MK |
36 | .SH DESCRIPTION |
37 | The function | |
e511ffb6 | 38 | .BR fread () |
fea681da MK |
39 | reads |
40 | .I nmemb | |
981fffea | 41 | items of data, each |
fea681da MK |
42 | .I size |
43 | bytes long, from the stream pointed to by | |
44 | .IR stream , | |
45 | storing them at the location given by | |
46 | .IR ptr . | |
47 | .PP | |
48 | The function | |
e511ffb6 | 49 | .BR fwrite () |
fea681da MK |
50 | writes |
51 | .I nmemb | |
981fffea | 52 | items of data, each |
fea681da MK |
53 | .I size |
54 | bytes long, to the stream pointed to by | |
55 | .IR stream , | |
56 | obtaining them from the location given by | |
57 | .IR ptr . | |
58 | .PP | |
24b74457 | 59 | For nonlocking counterparts, see |
fea681da | 60 | .BR unlocked_stdio (3). |
47297adb | 61 | .SH RETURN VALUE |
c294cd69 | 62 | On success, |
e511ffb6 | 63 | .BR fread () |
fea681da | 64 | and |
e511ffb6 | 65 | .BR fwrite () |
981fffea | 66 | return the number of items read or written. |
c294cd69 RI |
67 | This number equals the number of bytes transferred only when |
68 | .I size | |
69 | is 1. | |
70 | If an error occurs, or the end of the file is reached, | |
71 | the return value is a short item count (or zero). | |
fea681da | 72 | .PP |
ef5cd40e AD |
73 | The file position indicator for the stream is advanced by the number |
74 | of bytes successfully read or written. | |
75 | .PP | |
e511ffb6 | 76 | .BR fread () |
fea681da MK |
77 | does not distinguish between end-of-file and error, and callers must use |
78 | .BR feof (3) | |
79 | and | |
80 | .BR ferror (3) | |
81 | to determine which occurred. | |
b7ab4b61 PH |
82 | .SH ATTRIBUTES |
83 | For an explanation of the terms used in this section, see | |
84 | .BR attributes (7). | |
85 | .TS | |
86 | allbox; | |
c466875e | 87 | lbx lb lb |
b7ab4b61 PH |
88 | l l l. |
89 | Interface Attribute Value | |
90 | T{ | |
9e54434e BR |
91 | .na |
92 | .nh | |
b7ab4b61 PH |
93 | .BR fread (), |
94 | .BR fwrite () | |
95 | T} Thread safety MT-Safe | |
96 | .TE | |
c466875e | 97 | .sp 1 |
3113c7f3 | 98 | .SH STANDARDS |
4131356c AC |
99 | C11, POSIX.1-2008. |
100 | .SH HISTORY | |
101 | POSIX.1-2001, C89. | |
8ef8ccaa AD |
102 | .SH EXAMPLES |
103 | The program below demonstrates the use of | |
104 | .BR fread () | |
105 | by parsing /bin/sh ELF executable in binary mode and printing its | |
106 | magic and class: | |
107 | .PP | |
108 | .in +4n | |
109 | .EX | |
110 | $ \fB./a.out\fP | |
8ef8ccaa AD |
111 | ELF magic: 0x7f454c46 |
112 | Class: 0x02 | |
113 | .EE | |
114 | .in | |
115 | .SS Program source | |
116 | \& | |
b0b6ab4e | 117 | .\" SRC BEGIN (fread.c) |
8ef8ccaa AD |
118 | .EX |
119 | #include <stdio.h> | |
120 | #include <stdlib.h> | |
fe5dba13 | 121 | \& |
cbb22338 | 122 | #define ARRAY_SIZE(arr) (sizeof(arr) / sizeof((arr)[0])) |
fe5dba13 | 123 | \& |
8ef8ccaa AD |
124 | int |
125 | main(void) | |
126 | { | |
0f6f10d5 AC |
127 | FILE *fp; |
128 | size_t ret; | |
129 | unsigned char buffer[4]; | |
fe5dba13 | 130 | \& |
0f6f10d5 | 131 | fp = fopen("/bin/sh", "rb"); |
8ef8ccaa AD |
132 | if (!fp) { |
133 | perror("fopen"); | |
134 | return EXIT_FAILURE; | |
135 | } | |
fe5dba13 | 136 | \& |
0f6f10d5 | 137 | ret = fread(buffer, sizeof(*buffer), ARRAY_SIZE(buffer), fp); |
d5de9d1d | 138 | if (ret != ARRAY_SIZE(buffer)) { |
8ef8ccaa AD |
139 | fprintf(stderr, "fread() failed: %zu\en", ret); |
140 | exit(EXIT_FAILURE); | |
141 | } | |
fe5dba13 | 142 | \& |
8ef8ccaa AD |
143 | printf("ELF magic: %#04x%02x%02x%02x\en", buffer[0], buffer[1], |
144 | buffer[2], buffer[3]); | |
fe5dba13 | 145 | \& |
8ef8ccaa AD |
146 | ret = fread(buffer, 1, 1, fp); |
147 | if (ret != 1) { | |
148 | fprintf(stderr, "fread() failed: %zu\en", ret); | |
149 | exit(EXIT_FAILURE); | |
150 | } | |
fe5dba13 | 151 | \& |
8ef8ccaa | 152 | printf("Class: %#04x\en", buffer[0]); |
fe5dba13 | 153 | \& |
8ef8ccaa | 154 | fclose(fp); |
fe5dba13 | 155 | \& |
8ef8ccaa AD |
156 | exit(EXIT_SUCCESS); |
157 | } | |
158 | .EE | |
b0b6ab4e | 159 | .\" SRC END |
47297adb | 160 | .SH SEE ALSO |
fea681da MK |
161 | .BR read (2), |
162 | .BR write (2), | |
163 | .BR feof (3), | |
164 | .BR ferror (3), | |
165 | .BR unlocked_stdio (3) |