Debian Codegraph @

upstream/debian-trixie/man3/fgetc.3

raw
1 '\" t
2 .\" Copyright (c) 1993 by Thomas Koenig ([email protected])
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" Modified Wed Jul 28 11:12:07 1993 by Rik Faith ([email protected])
7 .\" Modified Fri Sep 8 15:48:13 1995 by Andries Brouwer ([email protected])
8 .TH fgetc 3 2024-06-15 "Linux man-pages 6.9.1"
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 .P
18 .BI "int fgetc(FILE *" stream );
19 .BI "int getc(FILE *" stream );
20 .B "int getchar(void);"
21 .P
22 .BI "char *fgets(char " s "[restrict ." size "], int " size ", \
23 FILE *restrict " stream );
24 .P
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 .P
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 .P
46 .BR getchar ()
47 is equivalent to
48 .BI "getc(" stdin ) \fR.
49 .P
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]\[rs]0\[aq])
62 is stored after the last character in the buffer.
63 .P
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 .P
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 .P
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 .P
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 .P
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 .TS
111 allbox;
112 lbx lb lb
113 l l l.
114 Interface Attribute Value
115 T{
116 .na
117 .nh
118 .BR fgetc (),
119 .BR fgets (),
120 .BR getc (),
121 .BR getchar (),
122 .BR ungetc ()
123 T} Thread safety MT-Safe
124 .TE
125 .SH STANDARDS
126 C11, POSIX.1-2008.
127 .SH HISTORY
128 POSIX.1-2001, C89.
129 .SH NOTES
130 It is not advisable to mix calls to input functions from the
131 .I stdio
132 library with low-level calls to
133 .BR read (2)
134 for the file descriptor associated with the input stream; the results
135 will be undefined and very probably not what you want.
136 .SH SEE ALSO
137 .BR read (2),
138 .BR write (2),
139 .BR ferror (3),
140 .BR fgetwc (3),
141 .BR fgetws (3),
142 .BR fopen (3),
143 .BR fread (3),
144 .BR fseek (3),
145 .BR getline (3),
146 .BR gets (3),
147 .BR getwchar (3),
148 .BR puts (3),
149 .BR scanf (3),
150 .BR ungetwc (3),
151 .BR unlocked_stdio (3),
152 .BR feature_test_macros (7)