GNU Info

(libc.info)Character Input

---

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

---

Enter node , (file) or (file)node

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 (Note: 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.