man3/fgetc.3

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