]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
beef2770 DM |
2 | .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
beef2770 DM |
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) | |
4c1c5274 | 8 | .TH fgetc 3 (date) "Linux man-pages (unreleased)" |
beef2770 DM |
9 | .SH NAME |
10 | fgetc, fgets, getc, getchar, ungetc \- input of characters and strings | |
afa8db94 AC |
11 | .SH LIBRARY |
12 | Standard C library | |
13 | .RI ( libc ", " \-lc ) | |
beef2770 DM |
14 | .SH SYNOPSIS |
15 | .nf | |
16 | .B #include <stdio.h> | |
68e4db0a | 17 | .PP |
beef2770 | 18 | .BI "int fgetc(FILE *" stream ); |
beef2770 | 19 | .BI "int getc(FILE *" stream ); |
beef2770 | 20 | .B "int getchar(void);" |
dbfe9c70 | 21 | .PP |
1eed67e7 AC |
22 | .BI "char *fgets(char " s "[restrict ." size "], int " size ", \ |
23 | FILE *restrict " stream ); | |
15d65653 | 24 | .PP |
beef2770 DM |
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. | |
b957f81f | 61 | A terminating null byte (\[aq]\e0\[aq]) |
beef2770 DM |
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 (), | |
d556548b | 84 | .BR getc (), |
beef2770 DM |
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. | |
c8ed841a MS |
107 | .SH ATTRIBUTES |
108 | For an explanation of the terms used in this section, see | |
109 | .BR attributes (7). | |
110 | .TS | |
111 | allbox; | |
c466875e | 112 | lbx lb lb |
c8ed841a MS |
113 | l l l. |
114 | Interface Attribute Value | |
115 | T{ | |
9e54434e BR |
116 | .na |
117 | .nh | |
c8ed841a MS |
118 | .BR fgetc (), |
119 | .BR fgets (), | |
120 | .BR getc (), | |
c8ed841a MS |
121 | .BR getchar (), |
122 | .BR ungetc () | |
123 | T} Thread safety MT-Safe | |
124 | .TE | |
847e0d88 | 125 | .sp 1 |
3113c7f3 | 126 | .SH STANDARDS |
4131356c AC |
127 | C11, POSIX.1-2008. |
128 | .SH HISTORY | |
129 | POSIX.1-2001, C89. | |
130 | .SH NOTES | |
beef2770 DM |
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), | |
d4df4e8a | 147 | .BR gets (3), |
beef2770 DM |
148 | .BR getwchar (3), |
149 | .BR puts (3), | |
beef2770 DM |
150 | .BR scanf (3), |
151 | .BR ungetwc (3), | |
152 | .BR unlocked_stdio (3), | |
153 | .BR feature_test_macros (7) |