Character Input (The GNU C Library)

### 12.8 Character Input ¶

This section describes functions for performing character-oriented input. These narrow stream 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)` ¶

  Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt | See POSIX Safety Concepts.

  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)` ¶

  Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt | See POSIX Safety Concepts.

  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)` ¶

  Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe corrupt | See POSIX Safety Concepts.

  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)` ¶

  Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe corrupt | See POSIX Safety Concepts.

  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)` ¶

  Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt | See POSIX Safety Concepts.

  This is just like `fgetc`, except that it may be implemented as a macro and may evaluate the stream argument more than once. Therefore, stream should never be an expression with side-effects.

Function: `wint_t` getwc `(FILE *stream)` ¶

  Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt | See POSIX Safety Concepts.

  This is just like `fgetwc`, except that it may be implemented as a macro and may evaluate the stream argument more than once. Therefore, stream should never be an expression with side-effects.

Function: `int` getc_unlocked `(FILE *stream)` ¶

  Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe corrupt | See POSIX Safety Concepts.

  The `getc_unlocked` function is equivalent to the `getc` function except that it does not implicitly lock the stream. Like `getc`, it may be implemented as a macro and may evaluate the stream argument more than once. Therefore, stream should not be an expression with side-effects.

Function: `wint_t` getwc_unlocked `(FILE *stream)` ¶

  Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe corrupt | See POSIX Safety Concepts.

  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)` ¶

  Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt | See POSIX Safety Concepts.

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

Function: `wint_t` getwchar `(void)` ¶

  Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt | See POSIX Safety Concepts.

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

Function: `int` getchar_unlocked `(void)` ¶

  Preliminary: | MT-Unsafe race:stdin | AS-Unsafe corrupt | AC-Unsafe corrupt | See POSIX Safety Concepts.

  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)` ¶

  Preliminary: | MT-Unsafe race:stdin | AS-Unsafe corrupt | AC-Unsafe corrupt | See POSIX Safety Concepts.

  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)` ¶

  Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt | See POSIX Safety Concepts.

  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.