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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .ad l
  75 .nh
  76 .TS
  77 allbox;
  78 lbx lb lb
  79 l l l.
  80 Interface       Attribute       Value
  81 T{
  82 .BR clearerr (),
  83 .BR feof (),
  84 .BR ferror ()
  85 T}      Thread safety   MT-Safe
  86 .TE
  87 .hy
  88 .ad
  89 .sp 1
  90 .SH STANDARDS
  91 C11, POSIX.1-2008.
  92 .SH HISTORY
  93 C89, POSIX.1-2001.
  94 .SH NOTES
  95 POSIX.1-2008 specifies
  96 .\"https://www.austingroupbugs.net/view.php?id=401
  97 that these functions shall not change the value of
  98 .I errno
  99 if
 100 .I stream
 101 is valid.
 102 .SH CAVEATS
 103 Normally,
 104 programs should read the return value of an input function,
 105 such as
 106 .BR fgetc (3),
 107 before using functions of the
 108 .BR feof (3)
 109 family.
 110 Only when the function returned the sentinel value
 111 .B EOF
 112 it makes sense to distinguish between the end of a file or an error with
 113 .BR feof (3)
 114 or
 115 .BR ferror (3).
 116 .SH SEE ALSO
 117 .BR open (2),
 118 .BR fdopen (3),
 119 .BR fileno (3),
 120 .BR stdio (3),
 121 .BR unlocked_stdio (3)