Debian Codegraph @

upstream/debian-unstable/man3/fgetc.3

raw
1 '\" t
2 .\" Copyright 1993, Thomas Koenig <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH fgetc 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 fgetc, fgets, 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 .P
17 .BI "int fgetc(FILE *" stream );
18 .B "int getchar(void);"
19 .P
20 .BR "char *fgets(" "int size;"
21 .BI " char " s "[restrict " size "], int " size ", FILE *restrict " stream );
22 .P
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 .P
37 .BR getchar ()
38 is equivalent to
39 .IR fgetc(stdin) .
40 .P
41 .BR fgets ()
42 reads in at most one less than
43 .I size
44 characters from
45 .I stream
46 and stores them into the buffer pointed to by
47 .IR s .
48 Reading stops after an
49 .B EOF
50 or a newline.
51 If a newline is read, it is stored into the buffer.
52 A terminating null byte (\[aq]\[rs]0\[aq])
53 is stored after the last character in the buffer.
54 .P
55 .BR ungetc ()
56 pushes
57 .I c
58 back to
59 .IR stream ,
60 cast to
61 .IR "unsigned char" ,
62 where it is available for subsequent read operations.
63 Pushed-back characters
64 will be returned in reverse order;
65 only one pushback is guaranteed.
66 .P
67 Calls to the functions described here can be mixed with each other and with
68 calls to other input functions from the
69 .I stdio
70 library for the same input stream.
71 .P
72 For nonlocking counterparts, see
73 .BR unlocked_stdio (3).
74 .SH RETURN VALUE
75 .BR fgetc ()
76 and
77 .BR getchar ()
78 return the character read as an
79 .I unsigned char
80 cast to an
81 .I int
82 or
83 .B EOF
84 on end of file or error.
85 .P
86 .BR fgets ()
87 returns
88 .I s
89 on success, and NULL
90 on error or when end of file occurs while no characters have been read.
91 .P
92 .BR ungetc ()
93 returns
94 .I c
95 on success, or
96 .B EOF
97 on error.
98 .SH ATTRIBUTES
99 For an explanation of the terms used in this section, see
100 .BR attributes (7).
101 .TS
102 allbox;
103 lbx lb lb
104 l l l.
105 Interface Attribute Value
106 T{
107 .na
108 .nh
109 .BR fgetc (),
110 .BR fgets (),
111 .BR getchar (),
112 .BR ungetc ()
113 T} Thread safety MT-Safe
114 .TE
115 .SH STANDARDS
116 C11, POSIX.1-2008.
117 .SH HISTORY
118 POSIX.1-2001, C89.
119 .SH NOTES
120 It is not advisable to mix calls to input functions from the
121 .I stdio
122 library with low-level calls to
123 .BR read (2)
124 for the file descriptor associated with the input stream;
125 the results will be undefined
126 and very probably not what you want.
127 .SH SEE ALSO
128 .BR read (2),
129 .BR write (2),
130 .BR ferror (3),
131 .BR fgetwc (3),
132 .BR fgetws (3),
133 .BR fopen (3),
134 .BR fread (3),
135 .BR fseek (3),
136 .BR getline (3),
137 .BR gets (3),
138 .BR getwchar (3),
139 .BR puts (3),
140 .BR scanf (3),
141 .BR ungetwc (3),
142 .BR unlocked_stdio (3),
143 .BR feature_test_macros (7)