Overview
This chapter describes the standard C I/O functions. It includes the functions defined by C89 and those added by C99. The functions defined by C89 are also supported by C++, and there is no fundamental reason that you cannot use them in a C++ program when you deem it appropriate.
In C, the header associated with the I/O functions is <stdio.h>. In C++, this header is called <cstdio>. For ease of discussion, this chapter will use the C header name, but references to <stdio.h> also apply to <cstdio>.
The <stdio.h> header defines several macros and types required by the C file system. The most important type is FILE, which is used to declare a file pointer. Two other frequently used types are size_t and fpos_t. The size_t type, which is some form of unsigned integer, is the type of the result returned by sizeof. The fpos_t type defines an object that can uniquely specify each location within a file. The most commonly used macro defined by the header is EOF, which is the value that indicates end of file. Other data types and macros in <stdio.h> are described in conjunction with the functions to which they relate.
Many of the I/O functions set the built-in global integer variable errno when an error occurs. Your program can check this variable to obtain more information about the error. The values that errno may have are implementation dependent.
The C I/O system operates through streams. A stream is a logical device that is connected to an actual physical device, which is referred to as a file, when a file is opened. In the C I/O system, all streams have the same capabilities, but files may have differing qualities. For example, a disk file allows random access, but a modem does not. Thus, the C I/O system provides a level of abstraction between the programmer and the physical device. The abstraction is the stream and the device is the file. In this way, a consistent logical interface can be maintained, even though the actual physical devices may differ.
A stream is connected to a file via a call to fopen( ). Streams are operated upon through a file pointer (which is a pointer of type FILE *). In a sense, the file pointer is the glue that holds the C I/O system together.
When a C program begins execution, three predefined streams are auto- matically opened. They are stdin, stdout, and stderr, referring to standard input, standard output, and standard error, respectively. By default, these are connected to the console, but they may be redirected to any other type of device.
C99 adds the restrict qualifier to certain parameters of several functions originally defined by C89. When this is the case, the function will be shown using its C89 prototype (which is also the prototype used by C++), but the restrict-qualified parameters will be pointed out in the function’s description.
clearerr
#include <stdio.h>void clearerr(FILE *stream);
The clearerr( ) function resets (i.e., sets to zero) the error flag associated with the stream pointed to by stream. The end-of-file indicator is also reset.
The error flags for each stream are initially set to zero by a successful call to fopen( ). File errors can occur for a wide variety of reasons, many of which are system dependent. The exact nature of the error can be determined by calling perror( ), which displays a message describing the error. See perror( ).
Related functions are feof( ), ferror( ), and perror( ).
fclose
#include <stdio.h>int fclose(FILE *stream);
The fclose( ) function closes the file associated with stream and flushes its buffer. After a call to fclose( ), stream is no longer connected with the file, and any automatically allocated buffers are deallocated.
If fclose( ) is successful, zero is returned; otherwise, EOF is returned. Trying to close a file that has already been closed is an error. Removing the storage media before closing a file will also generate an error, as will lack of sufficient free disk space.
Related functions are fopen( ), freopen( ), and fflush( ).
feof
#include <stdio.h>int feof(FILE *stream);
The feof( ) function determines if the end of the file associated with stream has been reached. A nonzero value is returned if the file position indicator is at end-of-file; zero is returned otherwise.
Once the end of the file has been reached, subsequent read operations will return EOF until either rewind( ) is called or the file position indicator is moved using fseek( ).
The feof( ) function is particularly useful when working with binary files because the end-of-file marker is also a valid binary integer. Explicit calls must be made to feof( ) rather than simply testing the return value of getc( ), for example, to determine when the end of a binary file has been reached.
Related functions are clearerr( ), ferror( ), perror( ), putc( ), and getc( ).
ferror
#include <stdio.h>int ferror(FILE *stream);
The ferror( ) function checks for a file error on the given stream. A return value of zero indicates that no error has occurred, while a nonzero value means an error.
To determine the exact nature of the error, use the perror( ) function.
Related functions are clearerr( ), feof( ), and perror( ).
fflush
#include <stdio.h>int fflush(FILE *stream);
If stream is associated with a file opened for writing, a call to fflush( ) causes the contents of the output buffer to be physically written to the file. The file remains open.
A return value of zero indicates success; EOF indicates that a write error has occurred.
All buffers are automatically flushed upon normal termination of the program or when they are full. Also, closing a file flushes its buffer.
Related functions are fclose( ), fopen( ), fread( ), fwrite( ), getc( ), and putc( ).
fgetc
#include <stdio.h>int fgetc(FILE *stream);
The fgetc( ) function returns the next character from the specified input stream and increments the file position indicator. The character is read as an unsigned char that is converted to an integer.
If the end of the file is reached, fgetc( ) returns EOF. However, since EOF is a valid integer value, when working with binary files you must use feof( ) to check for the end of the file. If fgetc( ) encounters an error, EOF is also returned. If working with binary files, you must use ferror( ) to check for file errors.
Related functions are fputc( ), getc( ), putc( ), and fopen( ).
fgetpos
#include <stdio.h>int fgetpos(FILE *stream, fpos_t *position);
For the specified stream, the fgetpos( ) function stores the current value of the file position indicator in the object pointed to by position. The object pointed to by position must be of type fpos_t. The value stored there is useful only in a subsequent call to fsetpos( ).
In C99, both stream and position are qualified by restrict.
If an error occurs, fgetpos( ) returns nonzero; otherwise, it returns zero.
Related functions are fsetpos( ), fseek( ), and ftell( ).
