man3/fgetc.3

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Modified Wed Jul 28 11:12:07 1993 by Rik Faith (faith@cs.unc.edu)
   6 .\" Modified Fri Sep  8 15:48:13 1995 by Andries Brouwer (aeb@cwi.nl)
   7 .TH fgetc 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 fgetc, fgets, getc, getchar, ungetc \- input of characters and strings
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <stdio.h>
  16 .PP
  17 .BI "int fgetc(FILE *" stream );
  18 .BI "int getc(FILE *" stream );
  19 .B "int getchar(void);"
  20 .PP
  21 .BI "char *fgets(char *restrict " s ", int " size ", FILE *restrict " stream );
  22 .PP
  23 .BI "int ungetc(int " c ", FILE *" stream );
  24 .fi
  25 .SH DESCRIPTION
  26 .BR fgetc ()
  27 reads the next character from
  28 .I stream
  29 and returns it as an
  30 .I unsigned char
  31 cast to an
  32 .IR int ,
  33 or
  34 .B EOF
  35 on end of file or error.
  36 .PP
  37 .BR getc ()
  38 is equivalent to
  39 .BR fgetc ()
  40 except that it may be implemented as a macro which evaluates
  41 .I stream
  42 more than once.
  43 .PP
  44 .BR getchar ()
  45 is equivalent to
  46 .BI "getc(" stdin ) \fR.
  47 .PP
  48 .BR fgets ()
  49 reads in at most one less than
  50 .I size
  51 characters from
  52 .I stream
  53 and stores them into the buffer pointed to by
  54 .IR s .
  55 Reading stops after an
  56 .B EOF
  57 or a newline.
  58 If a newline is read, it is stored into the buffer.
  59 A terminating null byte (\(aq\e0\(aq)
  60 is stored after the last character in the buffer.
  61 .PP
  62 .BR ungetc ()
  63 pushes
  64 .I c
  65 back to
  66 .IR stream ,
  67 cast to
  68 .IR "unsigned char" ,
  69 where it is available for subsequent read operations.
  70 Pushed-back characters
  71 will be returned in reverse order; only one pushback is guaranteed.
  72 .PP
  73 Calls to the functions described here can be mixed with each other and with
  74 calls to other input functions from the
  75 .I stdio
  76 library for the same input stream.
  77 .PP
  78 For nonlocking counterparts, see
  79 .BR unlocked_stdio (3).
  80 .SH RETURN VALUE
  81 .BR fgetc (),
  82 .BR getc (),
  83 and
  84 .BR getchar ()
  85 return the character read as an
  86 .I unsigned char
  87 cast to an
  88 .I int
  89 or
  90 .B EOF
  91 on end of file or error.
  92 .PP
  93 .BR fgets ()
  94 returns
  95 .I s
  96 on success, and NULL
  97 on error or when end of file occurs while no characters have been read.
  98 .PP
  99 .BR ungetc ()
 100 returns
 101 .I c
 102 on success, or
 103 .B EOF
 104 on error.
 105 .SH ATTRIBUTES
 106 For an explanation of the terms used in this section, see
 107 .BR attributes (7).
 108 .ad l
 109 .nh
 110 .TS
 111 allbox;
 112 lbx lb lb
 113 l l l.
 114 Interface       Attribute       Value
 115 T{
 116 .BR fgetc (),
 117 .BR fgets (),
 118 .BR getc (),
 119 .BR getchar (),
 120 .BR ungetc ()
 121 T}      Thread safety   MT-Safe
 122 .TE
 123 .hy
 124 .ad
 125 .sp 1
 126 .SH STANDARDS
 127 POSIX.1-2001, POSIX.1-2008, C89, C99.
 128 .PP
 129 It is not advisable to mix calls to input functions from the
 130 .I stdio
 131 library with low-level calls to
 132 .BR read (2)
 133 for the file descriptor associated with the input stream; the results
 134 will be undefined and very probably not what you want.
 135 .SH SEE ALSO
 136 .BR read (2),
 137 .BR write (2),
 138 .BR ferror (3),
 139 .BR fgetwc (3),
 140 .BR fgetws (3),
 141 .BR fopen (3),
 142 .BR fread (3),
 143 .BR fseek (3),
 144 .BR getline (3),
 145 .BR gets (3),
 146 .BR getwchar (3),
 147 .BR puts (3),
 148 .BR scanf (3),
 149 .BR ungetwc (3),
 150 .BR unlocked_stdio (3),
 151 .BR feature_test_macros (7)