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)

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

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

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)

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.

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.