Commit | Line | Data |
---|---|---|
ae59e04c | 1 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
952018c5 | 2 | .\" All rights reserved. |
2e146d0b | 3 | .\" |
639aed4c | 4 | .\" This code is derived from software contributed to Berkeley by |
043368e6 KB |
5 | .\" Chris Torek and the American National Standards Committee X3, |
6 | .\" on Information Processing Systems. | |
7 | .\" | |
91cff1e1 | 8 | .\" %sccs.include.redist.man% |
952018c5 | 9 | .\" |
043368e6 | 10 | .\" @(#)fgets.3 6.9 (Berkeley) %G% |
952018c5 | 11 | .\" |
ae59e04c CL |
12 | .Dd |
13 | .Dt FGETS 3 | |
14 | .Os | |
15 | .Sh NAME | |
16 | .Nm fgets , | |
17 | .Nm gets | |
18 | .Nd get a line from a stream | |
19 | .Sh SYNOPSIS | |
20 | .Fd #include <stdio.h> | |
21 | .Ft char * | |
22 | .Fn fgets "char *str" "size_t size" "FILE *stream" | |
23 | .Ft char * | |
24 | .Fn gets "char *str" | |
25 | .Sh DESCRIPTION | |
26 | The | |
27 | .Fn fgets | |
28 | function | |
639aed4c | 29 | reads at most one less than the number of characters specified by |
ae59e04c | 30 | .Xr size |
639aed4c | 31 | from the given |
ae59e04c CL |
32 | .Fa stream |
33 | and stores them in the string | |
34 | .Fa str . | |
639aed4c KB |
35 | Reading stops when a newline character is found, |
36 | at end-of-file or error. | |
37 | The newline, if any, is retained. | |
ae59e04c CL |
38 | In any case a |
39 | .Ql \e0 | |
40 | character is appended to end the string. | |
41 | .Pp | |
42 | The | |
43 | .Fn gets | |
44 | function | |
639aed4c | 45 | is equivalent to |
ae59e04c | 46 | .Fn fgets |
639aed4c | 47 | with an infinite |
ae59e04c | 48 | .Xr size |
639aed4c | 49 | and a |
ae59e04c | 50 | .Fa stream |
639aed4c | 51 | of |
ae59e04c | 52 | .Em stdin , |
639aed4c KB |
53 | except that the newline character (if any) is not stored in the string. |
54 | It is the caller's responsibility to ensure that the input line, | |
55 | if any, is sufficiently short to fit in the string. | |
ae59e04c CL |
56 | .Sh RETURN VALUES |
57 | .Pp | |
639aed4c | 58 | Upon successful completion, |
ae59e04c | 59 | .Fn fgets |
639aed4c | 60 | and |
ae59e04c | 61 | .Fn gets |
639aed4c | 62 | return |
ae59e04c | 63 | a pointer to the string. |
639aed4c | 64 | If end-of-file or an error occurs before any characters are read, |
ae59e04c CL |
65 | they return |
66 | .Dv NULL. | |
67 | The | |
68 | .Fn fgets | |
1382c0b2 | 69 | and |
ae59e04c CL |
70 | functions |
71 | .Fn gets | |
1382c0b2 | 72 | do not distinguish between end-of-file and error, and callers must use |
ae59e04c | 73 | .Xr feof 3 |
639aed4c | 74 | and |
ae59e04c | 75 | .Xr ferror 3 |
639aed4c | 76 | to determine which occurred. |
ae59e04c CL |
77 | .Sh ERRORS |
78 | .Bl -tag -width [EBADF] | |
79 | .It Bq Er EBADF | |
80 | The given | |
81 | .Fa stream | |
639aed4c | 82 | is not a readable stream. |
ae59e04c CL |
83 | .El |
84 | .Pp | |
85 | The function | |
86 | .Fn fgets | |
639aed4c | 87 | may also fail and set |
ae59e04c | 88 | .Va errno |
639aed4c | 89 | for any of the errors specified for the routines |
ae59e04c CL |
90 | .Xr fflush 3 , |
91 | .Xr fstat 2 , | |
92 | .Xr read 2 , | |
639aed4c | 93 | or |
ae59e04c CL |
94 | .Xr malloc 3 . |
95 | .Pp | |
96 | The function | |
97 | .Fn gets | |
639aed4c | 98 | may also fail and set |
ae59e04c | 99 | .Va errno |
639aed4c | 100 | for any of the errors specified for the routine |
ae59e04c CL |
101 | .Xr getchar 3 . |
102 | .Sh SEE ALSO | |
103 | .Xr feof 3 , | |
104 | .Xr ferror 3 , | |
105 | .Xr fgetline 3 | |
106 | .Sh STANDARDS | |
107 | The functions | |
108 | .Fn fgets | |
78a22176 | 109 | and |
ae59e04c CL |
110 | .Fn gets |
111 | conform to | |
112 | .St -ansiC . | |
113 | .Sh BUGS | |
639aed4c KB |
114 | Since it is usually impossible to ensure that the next input line |
115 | is less than some arbitrary length, and because overflowing the | |
116 | input buffer is almost invariably a security violation, programs | |
117 | should | |
ae59e04c | 118 | .Em NEVER |
639aed4c | 119 | use |
ae59e04c CL |
120 | .Fn gets . |
121 | The | |
122 | .Fn gets | |
123 | function | |
124 | exists purely to conform to | |
125 | .St -ansiC . |