diff options
Diffstat (limited to 'manual')
| -rw-r--r-- | manual/stdio.texi | 50 |
1 files changed, 40 insertions, 10 deletions
diff --git a/manual/stdio.texi b/manual/stdio.texi index 4764003443..5c37698fc6 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -27,6 +27,7 @@ representing a communications channel to a file, device, or process. @code{printf} and friends. * Formatted Input:: @code{scanf} and related functions. * EOF and Errors:: How you can tell if an I/O error happens. +* Error Recovery:: What you can do about errors. * Binary Streams:: Some systems distinguish between text files and binary files. * File Positioning:: About random-access streams. @@ -3055,16 +3056,6 @@ value may be some other negative number. @comment stdio.h @comment ISO -@deftypefun void clearerr (FILE *@var{stream}) -This function clears the end-of-file and error indicators for the -stream @var{stream}. - -The file positioning functions (@pxref{File Positioning}) also clear the -end-of-file indicator for the stream. -@end deftypefun - -@comment stdio.h -@comment ISO @deftypefun int feof (FILE *@var{stream}) The @code{feof} function returns nonzero if and only if the end-of-file indicator for the stream @var{stream} is set. @@ -3088,6 +3079,45 @@ conditions defined for @code{write} are meaningful for these functions. For more information about the descriptor-level I/O functions, see @ref{Low-Level I/O}. +@node Error Recovery +@section Recovering from errors + +You may explicitly clear the error and EOF flags with the @code{clearerr} +function. + +@comment stdio.h +@comment ISO +@deftypefun void clearerr (FILE *@var{stream}) +This function clears the end-of-file and error indicators for the +stream @var{stream}. + +The file positioning functions (@pxref{File Positioning}) also clear the +end-of-file indicator for the stream. +@end deftypefun + +Note that it is @emph{not} correct to just clear the error flag and retry +a failed stream operation. After a failed write, any number of +characters since the last buffer flush may have been committed to the +file, while some buffered data may have been discarded. Merely retrying +can thus cause lost or repeated data. + +A failed read may leave the file pointer in an inappropriate position for +a second try. In both cases, you should seek to a known position before +retrying. + +Most errors that can happen are not recoverable --- a second try will +always fail again in the same way. So usually it is best to give up and +report the error to the user, rather than install complicated recovery +logic. + +One important exception is @code{EINTR} (@pxref{Interrupted Primitives}). +Many stream I/O implementations will treat it as an ordinary error, which +can be quite inconvenient. You can avoid this hassle by installing all +signals with the @code{SA_RESTART} flag. + +For similar reasons, setting nonblocking I/O on a stream's file +descriptor is not usually advisable. + @node Binary Streams @section Text and Binary Streams |