]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) |
2 | .\" | |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
c13182ef | 11 | .\" |
fea681da MK |
12 | .\" Since the Linux kernel and libraries are constantly changing, this |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. The author(s) may not | |
16 | .\" have taken the same level of care in the production of this manual, | |
17 | .\" which is licensed free of charge, as they might when working | |
18 | .\" professionally. | |
c13182ef | 19 | .\" |
fea681da MK |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" License. | |
23 | .\" Modified Wed Jul 28 11:12:07 1993 by Rik Faith (faith@cs.unc.edu) | |
24 | .\" Modified Fri Sep 8 15:48:13 1995 by Andries Brouwer (aeb@cwi.nl) | |
5d83f9cd | 25 | .TH GETS 3 2012-01-18 "GNU" "Linux Programmer's Manual" |
fea681da MK |
26 | .SH NAME |
27 | fgetc, fgets, getc, getchar, gets, ungetc \- input of characters and strings | |
28 | .SH SYNOPSIS | |
29 | .nf | |
30 | .B #include <stdio.h> | |
31 | .sp | |
32 | .BI "int fgetc(FILE *" stream ); | |
5895e7eb | 33 | |
fea681da | 34 | .BI "char *fgets(char *" "s" ", int " "size" ", FILE *" "stream" ); |
5895e7eb | 35 | |
fea681da | 36 | .BI "int getc(FILE *" stream ); |
5895e7eb | 37 | |
0daa9e92 | 38 | .B "int getchar(void);" |
5895e7eb | 39 | |
fea681da | 40 | .BI "char *gets(char *" "s" ); |
5895e7eb | 41 | |
fea681da | 42 | .BI "int ungetc(int " c ", FILE *" stream ); |
c8250206 | 43 | .fi |
fea681da | 44 | .SH DESCRIPTION |
63aa9df0 | 45 | .BR fgetc () |
fea681da | 46 | reads the next character from |
c13182ef | 47 | .I stream |
fea681da | 48 | and returns it as an |
9ff08aad | 49 | .I unsigned char |
fea681da | 50 | cast to an |
9ff08aad | 51 | .IR int , |
fea681da MK |
52 | or |
53 | .B EOF | |
54 | on end of file or error. | |
55 | .PP | |
63aa9df0 | 56 | .BR getc () |
fea681da | 57 | is equivalent to |
63aa9df0 | 58 | .BR fgetc () |
fea681da MK |
59 | except that it may be implemented as a macro which evaluates |
60 | .I stream | |
61 | more than once. | |
62 | .PP | |
63aa9df0 | 63 | .BR getchar () |
fea681da MK |
64 | is equivalent to |
65 | .BI "getc(" stdin ) \fR. | |
66 | .PP | |
c13182ef | 67 | .BR gets () |
e1d6264d | 68 | reads a line from |
fea681da MK |
69 | .I stdin |
70 | into the buffer pointed to by | |
71 | .I s | |
72 | until either a terminating newline or | |
73 | .BR EOF , | |
9f8e673e | 74 | which it replaces with a null byte (\(aq\\0\(aq). |
3d341b33 | 75 | No check for buffer overrun is performed (see BUGS below). |
fea681da | 76 | .PP |
63aa9df0 | 77 | .BR fgets () |
fea681da MK |
78 | reads in at most one less than |
79 | .I size | |
80 | characters from | |
81 | .I stream | |
82 | and stores them into the buffer pointed to by | |
83 | .IR s . | |
84 | Reading stops after an | |
85 | .B EOF | |
c13182ef MK |
86 | or a newline. |
87 | If a newline is read, it is stored into the buffer. | |
9f8e673e | 88 | A terminating null byte (\(aq\\0\(aq) |
fea681da MK |
89 | is stored after the last character in the buffer. |
90 | .PP | |
63aa9df0 | 91 | .BR ungetc () |
fea681da MK |
92 | pushes |
93 | .I c | |
94 | back to | |
95 | .IR stream , | |
96 | cast to | |
9ff08aad | 97 | .IR "unsigned char" , |
c13182ef MK |
98 | where it is available for subsequent read operations. |
99 | Pushed-back characters | |
fea681da MK |
100 | will be returned in reverse order; only one pushback is guaranteed. |
101 | .PP | |
102 | Calls to the functions described here can be mixed with each other and with | |
103 | calls to other input functions from the | |
f19a0f03 | 104 | .I stdio |
fea681da MK |
105 | library for the same input stream. |
106 | .PP | |
24b74457 | 107 | For nonlocking counterparts, see |
fea681da MK |
108 | .BR unlocked_stdio (3). |
109 | .SH "RETURN VALUE" | |
c13182ef MK |
110 | .BR fgetc (), |
111 | .BR getc () | |
112 | and | |
e1d6264d | 113 | .BR getchar () |
fea681da | 114 | return the character read as an |
9ff08aad | 115 | .I unsigned char |
fea681da | 116 | cast to an |
9ff08aad | 117 | .I int |
fea681da MK |
118 | or |
119 | .B EOF | |
120 | on end of file or error. | |
121 | .PP | |
c13182ef MK |
122 | .BR gets () |
123 | and | |
4d52e8f8 | 124 | .BR fgets () |
fea681da MK |
125 | return |
126 | .I s | |
8478ee02 | 127 | on success, and NULL |
fea681da MK |
128 | on error or when end of file occurs while no characters have been read. |
129 | .PP | |
63aa9df0 | 130 | .BR ungetc () |
c13182ef | 131 | returns |
fea681da MK |
132 | .I c |
133 | on success, or | |
134 | .B EOF | |
135 | on error. | |
136 | .SH "CONFORMING TO" | |
a0a77264 | 137 | C89, C99, POSIX.1-2001. |
5d83f9cd | 138 | |
fea681da | 139 | LSB deprecates |
63aa9df0 | 140 | .BR gets (). |
1f04081f MK |
141 | POSIX.1-2008 marks |
142 | .BR gets () | |
143 | obsolescent. | |
5d83f9cd MK |
144 | ISO C11 removes the specification of |
145 | .BR gets () | |
146 | from the C language, and since version 2.16, | |
147 | glibc header files don't expose the function declaration if the | |
148 | .B _ISOC11_SOURCE | |
149 | feature test macro is defined. | |
fea681da MK |
150 | .SH BUGS |
151 | Never use | |
63aa9df0 | 152 | .BR gets (). |
fea681da MK |
153 | Because it is impossible to tell without knowing the data in advance how many |
154 | characters | |
63aa9df0 | 155 | .BR gets () |
fea681da | 156 | will read, and because |
63aa9df0 | 157 | .BR gets () |
c13182ef MK |
158 | will continue to store characters past the end of the buffer, |
159 | it is extremely dangerous to use. | |
160 | It has been used to break computer security. | |
161 | Use | |
63aa9df0 | 162 | .BR fgets () |
fea681da MK |
163 | instead. |
164 | .PP | |
165 | It is not advisable to mix calls to input functions from the | |
f19a0f03 | 166 | .I stdio |
c65433e6 | 167 | library with low-level calls to |
9daa4fb9 | 168 | .BR read (2) |
fea681da MK |
169 | for the file descriptor associated with the input stream; the results |
170 | will be undefined and very probably not what you want. | |
171 | .SH "SEE ALSO" | |
172 | .BR read (2), | |
173 | .BR write (2), | |
174 | .BR ferror (3), | |
1709027c | 175 | .BR fgetwc (3), |
37f58312 | 176 | .BR fgetws (3), |
fea681da MK |
177 | .BR fopen (3), |
178 | .BR fread (3), | |
179 | .BR fseek (3), | |
bb47b54b | 180 | .BR getline (3), |
1709027c | 181 | .BR getwchar (3), |
fea681da MK |
182 | .BR puts (3), |
183 | .BR scanf (3), | |
1709027c | 184 | .BR ungetwc (3), |
5d83f9cd MK |
185 | .BR unlocked_stdio (3), |
186 | .BR feature_test_macros (7) |