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