man3/fread.3

   1 '\" t
   2 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
   3 .\" and Copyright (c) 2020 Arkadiusz Drabczyk <arkadiusz@drabczyk.org>
   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 .\"
  10 .\" SPDX-License-Identifier: BSD-4-Clause-UC
  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 .\"
  19 .TH fread 3 (date) "Linux man-pages (unreleased)"
  20 .SH NAME
  21 fread, fwrite \- binary stream input/output
  22 .SH LIBRARY
  23 Standard C library
  24 .RI ( libc ", " \-lc )
  25 .SH SYNOPSIS
  26 .nf
  27 .B #include <stdio.h>
  28 .PP
  29 .BI "size_t fread(void " ptr "[restrict ." size " * ." nmemb ],
  30 .BI "             size_t " size ", size_t " nmemb ,
  31 .BI "             FILE *restrict " stream );
  32 .BI "size_t fwrite(const void " ptr "[restrict ." size " * ." nmemb ],
  33 .BI "             size_t " size ", size_t " nmemb ,
  34 .BI "             FILE *restrict " stream );
  35 .fi
  36 .SH DESCRIPTION
  37 The function
  38 .BR fread ()
  39 reads
  40 .I nmemb
  41 items of data, each
  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
  49 .BR fwrite ()
  50 writes
  51 .I nmemb
  52 items of data, each
  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
  59 For nonlocking counterparts, see
  60 .BR unlocked_stdio (3).
  61 .SH RETURN VALUE
  62 On success,
  63 .BR fread ()
  64 and
  65 .BR fwrite ()
  66 return the number of items read or written.
  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).
  72 .PP
  73 The file position indicator for the stream is advanced by the number
  74 of bytes successfully read or written.
  75 .PP
  76 .BR fread ()
  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.
  82 .SH ATTRIBUTES
  83 For an explanation of the terms used in this section, see
  84 .BR attributes (7).
  85 .TS
  86 allbox;
  87 lbx lb lb
  88 l l l.
  89 Interface       Attribute       Value
  90 T{
  91 .na
  92 .nh
  93 .BR fread (),
  94 .BR fwrite ()
  95 T}      Thread safety   MT-Safe
  96 .TE
  97 .sp 1
  98 .SH STANDARDS
  99 C11, POSIX.1-2008.
 100 .SH HISTORY
 101 POSIX.1-2001, C89.
 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
 111 ELF magic: 0x7f454c46
 112 Class: 0x02
 113 .EE
 114 .in
 115 .SS Program source
 116 \&
 117 .\" SRC BEGIN (fread.c)
 118 .EX
 119 #include <stdio.h>
 120 #include <stdlib.h>
 121 \&
 122 #define ARRAY_SIZE(arr) (sizeof(arr) / sizeof((arr)[0]))
 123 \&
 124 int
 125 main(void)
 126 {
 127     FILE           *fp;
 128     size_t         ret;
 129     unsigned char  buffer[4];
 130 \&
 131     fp = fopen("/bin/sh", "rb");
 132     if (!fp) {
 133         perror("fopen");
 134         return EXIT_FAILURE;
 135     }
 136 \&
 137     ret = fread(buffer, sizeof(*buffer), ARRAY_SIZE(buffer), fp);
 138     if (ret != ARRAY_SIZE(buffer)) {
 139         fprintf(stderr, "fread() failed: %zu\en", ret);
 140         exit(EXIT_FAILURE);
 141     }
 142 \&
 143     printf("ELF magic: %#04x%02x%02x%02x\en", buffer[0], buffer[1],
 144            buffer[2], buffer[3]);
 145 \&
 146     ret = fread(buffer, 1, 1, fp);
 147     if (ret != 1) {
 148         fprintf(stderr, "fread() failed: %zu\en", ret);
 149         exit(EXIT_FAILURE);
 150     }
 151 \&
 152     printf("Class: %#04x\en", buffer[0]);
 153 \&
 154     fclose(fp);
 155 \&
 156     exit(EXIT_SUCCESS);
 157 }
 158 .EE
 159 .\" SRC END
 160 .SH SEE ALSO
 161 .BR read (2),
 162 .BR write (2),
 163 .BR feof (3),
 164 .BR ferror (3),
 165 .BR unlocked_stdio (3)