man3/fgetc.3

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" Modified Wed Jul 28 11:12:07 1993 by Rik Faith (faith@cs.unc.edu)
  26 .\" Modified Fri Sep  8 15:48:13 1995 by Andries Brouwer (aeb@cwi.nl)
  27 .TH FGETC 3  2021-03-22 "GNU" "Linux Programmer's Manual"
  28 .SH NAME
  29 fgetc, fgets, getc, getchar, ungetc \- input of characters and strings
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <stdio.h>
  33 .PP
  34 .BI "int fgetc(FILE *" stream );
  35 .BI "int getc(FILE *" stream );
  36 .B "int getchar(void);"
  37 .PP
  38 .BI "char *fgets(char *restrict " s ", int " size ", FILE *restrict " stream );
  39 .PP
  40 .BI "int ungetc(int " c ", FILE *" stream );
  41 .fi
  42 .SH DESCRIPTION
  43 .BR fgetc ()
  44 reads the next character from
  45 .I stream
  46 and returns it as an
  47 .I unsigned char
  48 cast to an
  49 .IR int ,
  50 or
  51 .B EOF
  52 on end of file or error.
  53 .PP
  54 .BR getc ()
  55 is equivalent to
  56 .BR fgetc ()
  57 except that it may be implemented as a macro which evaluates
  58 .I stream
  59 more than once.
  60 .PP
  61 .BR getchar ()
  62 is equivalent to
  63 .BI "getc(" stdin ) \fR.
  64 .PP
  65 .BR fgets ()
  66 reads in at most one less than
  67 .I size
  68 characters from
  69 .I stream
  70 and stores them into the buffer pointed to by
  71 .IR s .
  72 Reading stops after an
  73 .B EOF
  74 or a newline.
  75 If a newline is read, it is stored into the buffer.
  76 A terminating null byte (\(aq\e0\(aq)
  77 is stored after the last character in the buffer.
  78 .PP
  79 .BR ungetc ()
  80 pushes
  81 .I c
  82 back to
  83 .IR stream ,
  84 cast to
  85 .IR "unsigned char" ,
  86 where it is available for subsequent read operations.
  87 Pushed-back characters
  88 will be returned in reverse order; only one pushback is guaranteed.
  89 .PP
  90 Calls to the functions described here can be mixed with each other and with
  91 calls to other input functions from the
  92 .I stdio
  93 library for the same input stream.
  94 .PP
  95 For nonlocking counterparts, see
  96 .BR unlocked_stdio (3).
  97 .SH RETURN VALUE
  98 .BR fgetc (),
  99 .BR getc (),
 100 and
 101 .BR getchar ()
 102 return the character read as an
 103 .I unsigned char
 104 cast to an
 105 .I int
 106 or
 107 .B EOF
 108 on end of file or error.
 109 .PP
 110 .BR fgets ()
 111 returns
 112 .I s
 113 on success, and NULL
 114 on error or when end of file occurs while no characters have been read.
 115 .PP
 116 .BR ungetc ()
 117 returns
 118 .I c
 119 on success, or
 120 .B EOF
 121 on error.
 122 .SH ATTRIBUTES
 123 For an explanation of the terms used in this section, see
 124 .BR attributes (7).
 125 .ad l
 126 .nh
 127 .TS
 128 allbox;
 129 lbx lb lb
 130 l l l.
 131 Interface       Attribute       Value
 132 T{
 133 .BR fgetc (),
 134 .BR fgets (),
 135 .BR getc (),
 136 .BR getchar (),
 137 .BR ungetc ()
 138 T}      Thread safety   MT-Safe
 139 .TE
 140 .hy
 141 .ad
 142 .sp 1
 143 .SH CONFORMING TO
 144 POSIX.1-2001, POSIX.1-2008, C89, C99.
 145 .PP
 146 It is not advisable to mix calls to input functions from the
 147 .I stdio
 148 library with low-level calls to
 149 .BR read (2)
 150 for the file descriptor associated with the input stream; the results
 151 will be undefined and very probably not what you want.
 152 .SH SEE ALSO
 153 .BR read (2),
 154 .BR write (2),
 155 .BR ferror (3),
 156 .BR fgetwc (3),
 157 .BR fgetws (3),
 158 .BR fopen (3),
 159 .BR fread (3),
 160 .BR fseek (3),
 161 .BR getline (3),
 162 .BR gets (3),
 163 .BR getwchar (3),
 164 .BR puts (3),
 165 .BR scanf (3),
 166 .BR ungetwc (3),
 167 .BR unlocked_stdio (3),
 168 .BR feature_test_macros (7)