xref: /freebsd/lib/libc/stdio/fgets.3 (revision 74bf4e164ba5851606a27d4feff27717452583e5)
1.\" Copyright (c) 1990, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" Chris Torek and the American National Standards Committee X3,
6.\" on Information Processing Systems.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\" 3. All advertising materials mentioning features or use of this software
17.\"    must display the following acknowledgement:
18.\"	This product includes software developed by the University of
19.\"	California, Berkeley and its contributors.
20.\" 4. Neither the name of the University nor the names of its contributors
21.\"    may be used to endorse or promote products derived from this software
22.\"    without specific prior written permission.
23.\"
24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34.\" SUCH DAMAGE.
35.\"
36.\"     @(#)fgets.3	8.1 (Berkeley) 6/4/93
37.\" $FreeBSD$
38.\"
39.Dd June 4, 1993
40.Dt FGETS 3
41.Os
42.Sh NAME
43.Nm fgets ,
44.Nm gets
45.Nd get a line from a stream
46.Sh LIBRARY
47.Lb libc
48.Sh SYNOPSIS
49.In stdio.h
50.Ft char *
51.Fn fgets "char * restrict str" "int size" "FILE * restrict stream"
52.Ft char *
53.Fn gets "char *str"
54.Sh DESCRIPTION
55The
56.Fn fgets
57function
58reads at most one less than the number of characters specified by
59.Fa size
60from the given
61.Fa stream
62and stores them in the string
63.Fa str .
64Reading stops when a newline character is found,
65at end-of-file or error.
66The newline, if any, is retained.
67If any characters are read and there is no error, a
68.Ql \e0
69character is appended to end the string.
70.Pp
71The
72.Fn gets
73function
74is equivalent to
75.Fn fgets
76with an infinite
77.Fa size
78and a
79.Fa stream
80of
81.Dv stdin ,
82except that the newline character (if any) is not stored in the string.
83It is the caller's responsibility to ensure that the input line,
84if any, is sufficiently short to fit in the string.
85.Sh RETURN VALUES
86Upon successful completion,
87.Fn fgets
88and
89.Fn gets
90return
91a pointer to the string.
92If end-of-file occurs before any characters are read,
93they return
94.Dv NULL
95and the buffer contents remain unchanged.
96If an error occurs,
97they return
98.Dv NULL
99and the buffer contents are indeterminate.
100The
101.Fn fgets
102and
103.Fn gets
104functions
105do not distinguish between end-of-file and error, and callers must use
106.Xr feof 3
107and
108.Xr ferror 3
109to determine which occurred.
110.Sh ERRORS
111.Bl -tag -width Er
112.It Bq Er EBADF
113The given
114.Fa stream
115is not a readable stream.
116.El
117.Pp
118The function
119.Fn fgets
120may also fail and set
121.Va errno
122for any of the errors specified for the routines
123.Xr fflush 3 ,
124.Xr fstat 2 ,
125.Xr read 2 ,
126or
127.Xr malloc 3 .
128.Pp
129The function
130.Fn gets
131may also fail and set
132.Va errno
133for any of the errors specified for the routine
134.Xr getchar 3 .
135.Sh SECURITY CONSIDERATIONS
136The
137.Fn gets
138function cannot be used securely.
139Because of its lack of bounds checking,
140and the inability for the calling program
141to reliably determine the length of the next incoming line,
142the use of this function enables malicious users
143to arbitrarily change a running program's functionality through
144a buffer overflow attack.
145It is strongly suggested that the
146.Fn fgets
147function be used in all cases.
148(See
149the FSA.)
150.Sh SEE ALSO
151.Xr feof 3 ,
152.Xr ferror 3 ,
153.Xr fgetln 3 ,
154.Xr fgetws 3
155.Rs
156.%T "The FreeBSD Security Architecture"
157.Re
158(See
159.Pa /usr/share/doc/{to be determined} . )
160.Sh STANDARDS
161The functions
162.Fn fgets
163and
164.Fn gets
165conform to
166.St -isoC-99 .
167