man3/ferror.3

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