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.
9.12.1. Character input
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 EOF is
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
here.
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 fflush ,
fseek , or 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.
9.12.2. Character output
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
output file.
9.12.3. String output
These write strings to the output file; stream where
specified, otherwise 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!
9.12.4. String input
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
the null).
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.
|
Printer-friendly version
The C Book
This book is published as a matter of historical interest.
Please read the
copyright and disclaimer information.
GBdirect Ltd provides up-to-date training and consultancy in
C,
Embedded C,
C++
and a wide range of
other subjects based on
open standards if you happen to be interested.
|