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 .ad l
  86 .nh
  87 .TS
  88 allbox;
  89 lbx lb lb
  90 l l l.
  91 Interface       Attribute       Value
  92 T{
  93 .BR fread (),
  94 .BR fwrite ()
  95 T}      Thread safety   MT-Safe
  96 .TE
  97 .hy
  98 .ad
  99 .sp 1
 100 .SH STANDARDS
 101 POSIX.1-2001, POSIX.1-2008, C99.
 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)