man3/fread.3

   1 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
   2 .\" and Copyright (c) 2020 Arkadiusz Drabczyk <arkadiusz@drabczyk.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to Berkeley by
   6 .\" Chris Torek and the American National Standards Committee X3,
   7 .\" on Information Processing Systems.
   8 .\"
   9 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. All advertising materials mentioning features or use of this software
  19 .\"    must display the following acknowledgement:
  20 .\"     This product includes software developed by the University of
  21 .\"     California, Berkeley and its contributors.
  22 .\" 4. Neither the name of the University nor the names of its contributors
  23 .\"    may be used to endorse or promote products derived from this software
  24 .\"    without specific prior written permission.
  25 .\"
  26 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  27 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  28 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  29 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  30 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  31 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  32 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  33 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  34 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  35 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  36 .\" SUCH DAMAGE.
  37 .\" %%%LICENSE_END
  38 .\"
  39 .\"     @(#)fread.3     6.6 (Berkeley) 6/29/91
  40 .\"
  41 .\" Converted for Linux, Mon Nov 29 15:37:33 1993, faith@cs.unc.edu
  42 .\" Sun Feb 19 21:26:54 1995 by faith, return values
  43 .\" Modified Thu Apr 20 20:43:53 1995 by Jim Van Zandt <jrv@vanzandt.mv.com>
  44 .\" Modified Fri May 17 10:21:51 1996 by Martin Schulze <joey@infodrom.north.de>
  45 .\"
  46 .TH FREAD 3  2021-03-22 "GNU" "Linux Programmer's Manual"
  47 .SH NAME
  48 fread, fwrite \- binary stream input/output
  49 .SH SYNOPSIS
  50 .nf
  51 .B #include <stdio.h>
  52 .PP
  53 .BI "size_t fread(void *restrict " ptr ", size_t " size ", size_t " nmemb ,
  54 .BI "             FILE *restrict " stream );
  55 .BI "size_t fwrite(const void *restrict " ptr ", size_t " size \
  56 ", size_t " nmemb ,
  57 .BI "             FILE *restrict " stream );
  58 .fi
  59 .SH DESCRIPTION
  60 The function
  61 .BR fread ()
  62 reads
  63 .I nmemb
  64 items of data, each
  65 .I size
  66 bytes long, from the stream pointed to by
  67 .IR stream ,
  68 storing them at the location given by
  69 .IR ptr .
  70 .PP
  71 The function
  72 .BR fwrite ()
  73 writes
  74 .I nmemb
  75 items of data, each
  76 .I size
  77 bytes long, to the stream pointed to by
  78 .IR stream ,
  79 obtaining them from the location given by
  80 .IR ptr .
  81 .PP
  82 For nonlocking counterparts, see
  83 .BR unlocked_stdio (3).
  84 .SH RETURN VALUE
  85 On success,
  86 .BR fread ()
  87 and
  88 .BR fwrite ()
  89 return the number of items read or written.
  90 This number equals the number of bytes transferred only when
  91 .I size
  92 is 1.
  93 If an error occurs, or the end of the file is reached,
  94 the return value is a short item count (or zero).
  95 .PP
  96 The file position indicator for the stream is advanced by the number
  97 of bytes successfully read or written.
  98 .PP
  99 .BR fread ()
 100 does not distinguish between end-of-file and error, and callers must use
 101 .BR feof (3)
 102 and
 103 .BR ferror (3)
 104 to determine which occurred.
 105 .SH ATTRIBUTES
 106 For an explanation of the terms used in this section, see
 107 .BR attributes (7).
 108 .ad l
 109 .nh
 110 .TS
 111 allbox;
 112 lbx lb lb
 113 l l l.
 114 Interface       Attribute       Value
 115 T{
 116 .BR fread (),
 117 .BR fwrite ()
 118 T}      Thread safety   MT-Safe
 119 .TE
 120 .hy
 121 .ad
 122 .sp 1
 123 .SH CONFORMING TO
 124 POSIX.1-2001, POSIX.1-2008, C89.
 125 .SH EXAMPLES
 126 The program below demonstrates the use of
 127 .BR fread ()
 128 by parsing /bin/sh ELF executable in binary mode and printing its
 129 magic and class:
 130 .PP
 131 .in +4n
 132 .EX
 133 $ \fB./a.out\fP
 134 ELF magic: 0x7f454c46
 135 Class: 0x02
 136 .EE
 137 .in
 138 .SS Program source
 139 \&
 140 .EX
 141 #include <stdio.h>
 142 #include <stdlib.h>
 143
 144 #define ARRAY_SIZE(arr) (sizeof(arr) / sizeof((arr)[0]))
 145
 146 int
 147 main(void)
 148 {
 149     FILE *fp = fopen("/bin/sh", "rb");
 150     if (!fp) {
 151         perror("fopen");
 152         return EXIT_FAILURE;
 153     }
 154
 155     unsigned char buffer[4];
 156
 157     size_t ret = fread(buffer, sizeof(*buffer), ARRAY_SIZE(buffer), fp);
 158     if (ret != ARRAY_SIZE(buffer)) {
 159         fprintf(stderr, "fread() failed: %zu\en", ret);
 160         exit(EXIT_FAILURE);
 161     }
 162
 163     printf("ELF magic: %#04x%02x%02x%02x\en", buffer[0], buffer[1],
 164            buffer[2], buffer[3]);
 165
 166     ret = fread(buffer, 1, 1, fp);
 167     if (ret != 1) {
 168         fprintf(stderr, "fread() failed: %zu\en", ret);
 169         exit(EXIT_FAILURE);
 170     }
 171
 172     printf("Class: %#04x\en", buffer[0]);
 173
 174     fclose(fp);
 175
 176     exit(EXIT_SUCCESS);
 177 }
 178 .EE
 179 .SH SEE ALSO
 180 .BR read (2),
 181 .BR write (2),
 182 .BR feof (3),
 183 .BR ferror (3),
 184 .BR unlocked_stdio (3)