Character Input - The GNU C Library

Next: Line Input, Previous: Simple Output, Up: I/O on Streams

### 12.8 Character Input

This section describes functions for performing character-oriented input. These narrow streams functions are declared in the header file `stdio.h` and the wide character functions are declared in `wchar.h`. These functions return an `int` or `wint_t` value (for narrow and wide stream functions respectively) that is either a character of input, or the special value `EOF`/`WEOF` (usually -1). For the narrow stream functions it is important to store the result of these functions in a variable of type `int` instead of `char`, even when you plan to use it only as a character. Storing `EOF` in a `char` variable truncates its value to the size of a character, so that it is no longer distinguishable from the valid character ‘`(char) -1`’. So always use an `int` for the result of `getc` and friends, and check for `EOF` after the call; once you've verified that the result is not `EOF`, you can be sure that it will fit in a ‘`char`’ variable without loss of information.

— Function: int fgetc (FILE *stream)

> This function reads the next character as an `unsigned char` from the stream stream and returns its value, converted to an `int`. If an end-of-file condition or read error occurs, `EOF` is returned instead.

— Function: wint_t fgetwc (FILE *stream)

> This function reads the next wide character from the stream stream and returns its value. If an end-of-file condition or read error occurs, `WEOF` is returned instead.

— Function: int fgetc_unlocked (FILE *stream)

> The `fgetc_unlocked` function is equivalent to the `fgetc` function except that it does not implicitly lock the stream.

— Function: wint_t fgetwc_unlocked (FILE *stream)

> The `fgetwc_unlocked` function is equivalent to the `fgetwc` function except that it does not implicitly lock the stream.

> This function is a GNU extension.

— Function: int getc (FILE *stream)

> This is just like `fgetc`, except that it is permissible (and typical) for it to be implemented as a macro that evaluates the stream argument more than once. `getc` is often highly optimized, so it is usually the best function to use to read a single character.

— Function: wint_t getwc (FILE *stream)

> This is just like `fgetwc`, except that it is permissible for it to be implemented as a macro that evaluates the stream argument more than once. `getwc` can be highly optimized, so it is usually the best function to use to read a single wide character.

— Function: int getc_unlocked (FILE *stream)

> The `getc_unlocked` function is equivalent to the `getc` function except that it does not implicitly lock the stream.

— Function: wint_t getwc_unlocked (FILE *stream)

> The `getwc_unlocked` function is equivalent to the `getwc` function except that it does not implicitly lock the stream.

> This function is a GNU extension.

— Function: int getchar (void)

> The `getchar` function is equivalent to `getc` with `stdin` as the value of the stream argument.

— Function: wint_t getwchar (void)

> The `getwchar` function is equivalent to `getwc` with `stdin` as the value of the stream argument.

— Function: int getchar_unlocked (void)

> The `getchar_unlocked` function is equivalent to the `getchar` function except that it does not implicitly lock the stream.

— Function: wint_t getwchar_unlocked (void)

> The `getwchar_unlocked` function is equivalent to the `getwchar` function except that it does not implicitly lock the stream.

> This function is a GNU extension.

Here is an example of a function that does input using `fgetc`. It would work just as well using `getc` instead, or using `getchar ()` instead of `fgetc (stdin)`. The code would also work the same for the wide character stream functions.

         int
         y_or_n_p (const char *question)
         {
           fputs (question, stdout);
           while (1)
             {
               int c, answer;
               /* Write a space to separate answer from question. */
               fputc (' ', stdout);
               /* Read the first character of the line.
                  This should be the answer character, but might not be. */
               c = tolower (fgetc (stdin));
               answer = c;
               /* Discard rest of input line. */
               while (c != '\n' && c != EOF)
                 c = fgetc (stdin);
               /* Obey the answer if it was valid. */
               if (answer == 'y')
                 return 1;
               if (answer == 'n')
                 return 0;
               /* Answer was invalid: ask for valid answer. */
               fputs ("Please answer y or n:", stdout);
             }
         }

— Function: int getw (FILE *stream)

> This function reads a word (that is, an `int`) from stream. It's provided for compatibility with SVID. We recommend you use `fread` instead (see Block Input/Output). Unlike `getc`, any `int` value could be a valid result. `getw` returns `EOF` when it encounters end-of-file or an error, but there is no way to distinguish this from an input word with value -1.