9.12. Character I/O
A number of functions provide for character oriented I/O. Their declarations are:
#include <stdio.h> /* character input */ int fgetc(FILE *stream); int getc(FILE *stream); int getchar(void); int ungetc(int c, FILE *stream); /* character output */ int fputc(int c, FILE *stream); int putc(int c, FILE *stream); int putchar(int c); /* string input */ char *fgets(char *s, int n, FILE *stream); char *gets(char *s); /* string output */ int fputs(const char *s, FILE *stream); int puts(const char *s);
Their descriptions are as follows.
These read an
unsigned char from the input stream where
specified, or otherwise
stdin. In each case, the next
character is obtained from the input stream. It is treated as an
unsigned char and converted to an
int, which is
the return value. On End of File, the constant
returned, and the end-of-file indicator is set for the associated stream.
On error, EOF is returned, and the error indicator is set for the
associated stream. Successive calls will obtain characters sequentially.
The functions, if implemented as macros, may evaluate their
stream argument more than once, so do not use side effects
There is also the supporting
ungetc routine, which is used
to push back a character on to a stream, causing it to become the next
character to be read. This is not an output operation and can never cause
the external contents of a file to be changed. A
rewind operation on the stream between
the pushback and the read will cause the pushback to be forgotten. Only
one character of pushback is guaranteed, and attempts to pushback
EOF are ignored. In every case, pushing back a number of
characters then reading or discarding them leaves the file position
indicator unchanged. The file position indicator is decremented by every
successful call to
ungetc for a binary stream, but unspecified
for a text stream, or a binary stream which is positioned at the beginning
of the file.
These are identical in description to the input functions already
described, except performing output. They return the character written, or
EOF on error. There is no equivalent to End of File for an
These write strings to the output file;
stdout. The terminating null is not
written. Non-zero is returned on error, zero otherwise. Beware:
puts appends a newline to the string output;
fputs does not!
Fgets reads a string into the array pointed to by
s from the stream
stream. It stops on either
EOF or the first newline (which it reads), and appends a null
character. At most n−1 characters are read (leaving room for
Gets works similarly for the stream stdin, but discards the newline!
Both return s if successful, or a null pointer otherwise. In each case, if EOF is encountered before any characters have been read, the array is unchanged and a null pointer is returned. A read error in the middle of a string leaves the array contents undefined and a null pointer is returned.