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