man3/ferror.3

   1 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
   2 .\" and Copyright (C) 2021 Michael Kerrisk <mtk.manpages@gmail.com>
   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 .\"     @(#)ferror.3    6.8 (Berkeley) 6/29/91
  12 .\"
  13 .\"
  14 .\" Converted for Linux, Mon Nov 29 14:24:40 1993, faith@cs.unc.edu
  15 .\"
  16 .TH ferror 3 (date) "Linux man-pages (unreleased)"
  17 .SH NAME
  18 clearerr, feof, ferror \- check and reset stream status
  19 .SH LIBRARY
  20 Standard C library
  21 .RI ( libc ", " \-lc )
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <stdio.h>
  25 .PP
  26 .BI "void clearerr(FILE *" stream );
  27 .BI "int feof(FILE *" stream );
  28 .BI "int ferror(FILE *" stream );
  29 .fi
  30 .SH DESCRIPTION
  31 The function
  32 .BR clearerr ()
  33 clears the end-of-file and error indicators for the stream pointed to by
  34 .IR stream .
  35 .PP
  36 The function
  37 .BR feof ()
  38 tests the end-of-file indicator for the stream pointed to by
  39 .IR stream ,
  40 returning nonzero if it is set.
  41 The end-of-file indicator can be cleared only by the function
  42 .BR clearerr ().
  43 .PP
  44 The function
  45 .BR ferror ()
  46 tests the error indicator for the stream pointed to by
  47 .IR stream ,
  48 returning nonzero if it is set.
  49 The error indicator can be reset only by the
  50 .BR clearerr ()
  51 function.
  52 .PP
  53 For nonlocking counterparts, see
  54 .BR unlocked_stdio (3).
  55 .SH RETURN VALUE
  56 The
  57 .BR feof ()
  58 function returns nonzero if the end-of-file indicator is set for
  59 .IR stream ;
  60 otherwise, it returns zero.
  61 .PP
  62 The
  63 .BR ferror ()
  64 function returns nonzero if the error indicator is set for
  65 .IR stream ;
  66 otherwise, it returns zero.
  67 .SH ERRORS
  68 These functions should not fail and do not set
  69 .IR errno .
  70 .SH ATTRIBUTES
  71 For an explanation of the terms used in this section, see
  72 .BR attributes (7).
  73 .ad l
  74 .nh
  75 .TS
  76 allbox;
  77 lbx lb lb
  78 l l l.
  79 Interface       Attribute       Value
  80 T{
  81 .BR clearerr (),
  82 .BR feof (),
  83 .BR ferror ()
  84 T}      Thread safety   MT-Safe
  85 .TE
  86 .hy
  87 .ad
  88 .sp 1
  89 .SH STANDARDS
  90 The functions
  91 .BR clearerr (),
  92 .BR feof (),
  93 and
  94 .BR ferror ()
  95 conform to C89, C99, POSIX.1-2001, and POSIX.1-2008.
  96 .SH NOTES
  97 POSIX.1-2008 specifies
  98 .\"https://www.austingroupbugs.net/view.php?id=401
  99 that these functions shall not change the value of
 100 .I errno
 101 if
 102 .I stream
 103 is valid.
 104 .SH CAVEATS
 105 Normally,
 106 programs should read the return value of an input function,
 107 such as
 108 .BR fgetc (3),
 109 before using functions of the
 110 .BR feof (3)
 111 family.
 112 Only when the function returned the sentinel value
 113 .B EOF
 114 it makes sense to distinguish between the end of a file or an error with
 115 .BR feof (3)
 116 or
 117 .BR ferror (3).
 118 .SH SEE ALSO
 119 .BR open (2),
 120 .BR fdopen (3),
 121 .BR fileno (3),
 122 .BR stdio (3),
 123 .BR unlocked_stdio (3)