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.