original/man3/fread.3

   1 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Chris Torek and the American National Standards Committee X3,
   6 .\" on Information Processing Systems.
   7 .\"
   8 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"     This product includes software developed by the University of
  20 .\"     California, Berkeley and its contributors.
  21 .\" 4. Neither the name of the University nor the names of its contributors
  22 .\"    may be used to endorse or promote products derived from this software
  23 .\"    without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  35 .\" SUCH DAMAGE.
  36 .\" %%%LICENSE_END
  37 .\"
  38 .\"     @(#)fread.3     6.6 (Berkeley) 6/29/91
  39 .\"
  40 .\" Converted for Linux, Mon Nov 29 15:37:33 1993, faith@cs.unc.edu
  41 .\" Sun Feb 19 21:26:54 1995 by faith, return values
  42 .\" Modified Thu Apr 20 20:43:53 1995 by Jim Van Zandt <jrv@vanzandt.mv.com>
  43 .\" Modified Fri May 17 10:21:51 1996 by Martin Schulze <joey@infodrom.north.de>
  44 .\"
  45 .TH FREAD 3  2012-03-30 "GNU" "Linux Programmer's Manual"
  46 .SH NAME
  47 fread, fwrite \- binary stream input/output
  48 .SH SYNOPSIS
  49 .nf
  50 .B #include <stdio.h>
  51 .sp
  52 .BI "size_t fread(void *" ptr ", size_t " size ", size_t " nmemb \
  53 ", FILE *" stream );
  54 .sp
  55 .BI "size_t fwrite(const void *" ptr ", size_t " size ", size_t " nmemb ,
  56 .BI "              FILE *" stream );
  57 .fi
  58 .SH DESCRIPTION
  59 The function
  60 .BR fread ()
  61 reads
  62 .I nmemb
  63 elements of data, each
  64 .I size
  65 bytes long, from the stream pointed to by
  66 .IR stream ,
  67 storing them at the location given by
  68 .IR ptr .
  69 .PP
  70 The function
  71 .BR fwrite ()
  72 writes
  73 .I nmemb
  74 elements of data, each
  75 .I size
  76 bytes long, to the stream pointed to by
  77 .IR stream ,
  78 obtaining them from the location given by
  79 .IR ptr .
  80 .PP
  81 For nonlocking counterparts, see
  82 .BR unlocked_stdio (3).
  83 .SH RETURN VALUE
  84 On success,
  85 .BR fread ()
  86 and
  87 .BR fwrite ()
  88 return the number of
  89 .I items
  90 read or written.
  91 This number equals the number of bytes transferred only when
  92 .I size
  93 is 1.
  94 If an error occurs, or the end of the file is reached,
  95 the return value is a short item count (or zero).
  96 .PP
  97 .BR fread ()
  98 does not distinguish between end-of-file and error, and callers must use
  99 .BR feof (3)
 100 and
 101 .BR ferror (3)
 102 to determine which occurred.
 103 .SH CONFORMING TO
 104 C89, POSIX.1-2001.
 105 .SH SEE ALSO
 106 .BR read (2),
 107 .BR write (2),
 108 .BR feof (3),
 109 .BR ferror (3),
 110 .BR unlocked_stdio (3)
 111 .SH COLOPHON
 112 This page is part of release 3.68 of the Linux
 113 .I man-pages
 114 project.
 115 A description of the project,
 116 information about reporting bugs,
 117 and the latest version of this page,
 118 can be found at
 119 \%http://www.kernel.org/doc/man\-pages/.