Commit | Line | Data |
---|---|---|
639aed4c | 1 | .\" Copyright (c) 1990 The Regents of the University of California. |
952018c5 | 2 | .\" All rights reserved. |
2e146d0b | 3 | .\" |
639aed4c KB |
4 | .\" This code is derived from software contributed to Berkeley by |
5 | .\" Chris Torek. | |
6 | .\" | |
91cff1e1 | 7 | .\" %sccs.include.redist.man% |
952018c5 | 8 | .\" |
1382c0b2 | 9 | .\" @(#)fgets.3 6.7 (Berkeley) %G% |
952018c5 KB |
10 | .\" |
11 | .TH FGETS 3 "" | |
639aed4c | 12 | .UC 7 |
2e146d0b | 13 | .SH NAME |
639aed4c | 14 | fgets, gets \- get a line from a stream |
2e146d0b | 15 | .SH SYNOPSIS |
952018c5 | 16 | .nf |
639aed4c KB |
17 | .ft B |
18 | #include <stdio.h> | |
19 | ||
20 | char * | |
21 | fgets(char *str, size_t size, FILE *stream); | |
952018c5 | 22 | |
639aed4c KB |
23 | char * |
24 | gets(char *str); | |
25 | .ft R | |
952018c5 | 26 | .fi |
2e146d0b | 27 | .SH DESCRIPTION |
639aed4c KB |
28 | .I Fgets |
29 | reads at most one less than the number of characters specified by | |
30 | .IR size | |
31 | from the given | |
2e146d0b | 32 | .I stream |
639aed4c KB |
33 | into the string |
34 | .IR str . | |
35 | Reading stops when a newline character is found, | |
36 | at end-of-file or error. | |
37 | The newline, if any, is retained. | |
38 | In any case a '\e0' character is appended to end the string. | |
952018c5 | 39 | .PP |
639aed4c KB |
40 | .I Gets |
41 | is equivalent to | |
952018c5 | 42 | .I fgets |
639aed4c KB |
43 | with an infinite |
44 | .I size | |
45 | and a | |
46 | .I stream | |
47 | of | |
48 | .BR stdin , | |
49 | except that the newline character (if any) is not stored in the string. | |
50 | It is the caller's responsibility to ensure that the input line, | |
51 | if any, is sufficiently short to fit in the string. | |
639aed4c KB |
52 | .SH "RETURN VALUE" |
53 | .PP | |
54 | Upon successful completion, | |
2e146d0b | 55 | .I fgets |
639aed4c KB |
56 | and |
57 | .I gets | |
58 | return | |
59 | .IR s . | |
60 | If end-of-file or an error occurs before any characters are read, | |
61 | they return NULL. | |
1382c0b2 KB |
62 | .I Fgets |
63 | and | |
64 | .I gets | |
65 | do not distinguish between end-of-file and error, and callers must use | |
66 | .IR feof (3) | |
639aed4c | 67 | and |
1382c0b2 | 68 | .I ferror (3) |
639aed4c KB |
69 | to determine which occurred. |
70 | .SH ERRORS | |
71 | .TP 15 | |
72 | [EBADF] | |
73 | .I Stream | |
74 | is not a readable stream. | |
75 | .PP | |
76 | .I Fgets | |
77 | may also fail and set | |
78 | .I errno | |
79 | for any of the errors specified for the routines | |
80 | .IR fflush (3), | |
81 | .IR fstat (2), | |
82 | .IR read (2), | |
83 | or | |
84 | .IR malloc (3). | |
85 | .PP | |
86 | .I Gets | |
87 | may also fail and set | |
88 | .I errno | |
89 | for any of the errors specified for the routine | |
90 | .IR getchar (3). | |
78a22176 KB |
91 | .SH "SEE ALSO" |
92 | feof(3), ferror(3), fgetline(3) | |
93 | .SH STANDARDS | |
94 | .I Fgets | |
95 | and | |
96 | .I gets | |
97 | conform to ANSI X3.159-1989 (``ANSI C''). | |
639aed4c KB |
98 | .SH BUGS |
99 | Since it is usually impossible to ensure that the next input line | |
100 | is less than some arbitrary length, and because overflowing the | |
101 | input buffer is almost invariably a security violation, programs | |
102 | should | |
103 | .B NEVER | |
104 | use | |
105 | .IR gets . | |
106 | .I Gets | |
107 | exists purely to conform to ANSI X3.159-1989. |