Changeset View
Changeset View
Standalone View
Standalone View
lib/libc/stdio/fgets.3
Show All 31 Lines | |||||
.\" @(#)fgets.3 8.1 (Berkeley) 6/4/93 | .\" @(#)fgets.3 8.1 (Berkeley) 6/4/93 | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd April 3, 2018 | .Dd April 3, 2018 | ||||
.Dt FGETS 3 | .Dt FGETS 3 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm fgets , | .Nm fgets , | ||||
.Nm gets , | |||||
.Nm gets_s | .Nm gets_s | ||||
.Nd get a line from a stream | .Nd get a line from a stream | ||||
.Sh LIBRARY | .Sh LIBRARY | ||||
.Lb libc | .Lb libc | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.In stdio.h | .In stdio.h | ||||
.Ft char * | .Ft char * | ||||
.Fn fgets "char * restrict str" "int size" "FILE * restrict stream" | .Fn fgets "char * restrict str" "int size" "FILE * restrict stream" | ||||
.Ft char * | .Ft char * | ||||
.Fn gets_s "char *str" "rsize_t size" | .Fn gets_s "char *str" "rsize_t size" | ||||
.Ft char * | |||||
.Fn gets "char *str" | |||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Fn fgets | .Fn fgets | ||||
function | function | ||||
reads at most one less than the number of characters specified by | reads at most one less than the number of characters specified by | ||||
.Fa size | .Fa size | ||||
from the given | from the given | ||||
.Fa stream | .Fa stream | ||||
Show All 15 Lines | |||||
.Fa stream | .Fa stream | ||||
of | of | ||||
.Dv stdin , | .Dv stdin , | ||||
except that the newline character (if any) is not stored in the string. | except that the newline character (if any) is not stored in the string. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn gets | .Fn gets | ||||
function | function | ||||
is equivalent to | was unsafe and is no longer available. | ||||
.Fn fgets | |||||
with an infinite | |||||
.Fa size | |||||
and a | |||||
.Fa stream | |||||
of | |||||
.Dv stdin , | |||||
except that the newline character (if any) is not stored in the string. | |||||
It is the caller's responsibility to ensure that the input line, | |||||
if any, is sufficiently short to fit in the string. | |||||
.Sh RETURN VALUES | .Sh RETURN VALUES | ||||
Upon successful completion, | Upon successful completion, | ||||
.Fn fgets , | .Fn fgets | ||||
.Fn gets_s , | |||||
and | and | ||||
.Fn gets | .Fn gets_s | ||||
return | return | ||||
a pointer to the string. | a pointer to the string. | ||||
If end-of-file occurs before any characters are read, | If end-of-file occurs before any characters are read, | ||||
they return | they return | ||||
.Dv NULL | .Dv NULL | ||||
and the buffer contents remain unchanged. | and the buffer contents remain unchanged. | ||||
If an error occurs, | If an error occurs, | ||||
they return | they return | ||||
.Dv NULL | .Dv NULL | ||||
and the buffer contents are indeterminate. | and the buffer contents are indeterminate. | ||||
The | The | ||||
.Fn fgets , | .Fn fgets | ||||
.Fn gets_s , | |||||
and | and | ||||
.Fn gets | .Fn gets_s | ||||
functions | functions | ||||
do not distinguish between end-of-file and error, and callers must use | do not distinguish between end-of-file and error, and callers must use | ||||
.Xr feof 3 | .Xr feof 3 | ||||
and | and | ||||
.Xr ferror 3 | .Xr ferror 3 | ||||
to determine which occurred. | to determine which occurred. | ||||
.Sh ERRORS | .Sh ERRORS | ||||
.Bl -tag -width Er | .Bl -tag -width Er | ||||
.It Bq Er EBADF | .It Bq Er EBADF | ||||
The given | The given | ||||
.Fa stream | .Fa stream | ||||
is not a readable stream. | is not a readable stream. | ||||
.El | .El | ||||
.Pp | .Pp | ||||
The function | The function | ||||
.Fn fgets | .Fn fgets | ||||
may also fail and set | may also fail and set | ||||
.Va errno | .Va errno | ||||
for any of the errors specified for the routines | for any of the errors specified for the routines | ||||
.Xr fflush 3 , | .Xr fflush 3 , | ||||
.Xr fstat 2 , | .Xr fstat 2 , | ||||
.Xr read 2 , | .Xr read 2 , | ||||
or | or | ||||
.Xr malloc 3 . | .Xr malloc 3 . | ||||
emaste: Do we need a `The function gets_s may also fail and set errno for any of the errors specified… | |||||
.Pp | |||||
The function | |||||
.Fn gets | |||||
may also fail and set | |||||
.Va errno | |||||
for any of the errors specified for the routine | |||||
.Xr getchar 3 . | |||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr feof 3 , | .Xr feof 3 , | ||||
.Xr ferror 3 , | .Xr ferror 3 , | ||||
.Xr fgetln 3 , | .Xr fgetln 3 , | ||||
.Xr fgetws 3 , | .Xr fgetws 3 , | ||||
.Xr getline 3 | .Xr getline 3 | ||||
.Sh STANDARDS | .Sh STANDARDS | ||||
The functions | The | ||||
.Fn fgets | .Fn fgets | ||||
and | function conforms to | ||||
.Fn gets | |||||
conform to | |||||
.St -isoC-99 . | .St -isoC-99 . | ||||
.Fn gets_s | .Fn gets_s | ||||
conforms to | conforms to | ||||
.St -isoC-2011 | .St -isoC-2011 | ||||
K.3.7.4.1. | K.3.7.4.1. | ||||
.Fn gets | .Fn gets | ||||
has been removed from | has been removed from | ||||
.St -isoC-2011 . | .St -isoC-2011 . | ||||
.Sh SECURITY CONSIDERATIONS | |||||
The | |||||
.Fn gets | |||||
function cannot be used securely. | |||||
Because of its lack of bounds checking, | |||||
and the inability for the calling program | |||||
to reliably determine the length of the next incoming line, | |||||
the use of this function enables malicious users | |||||
to arbitrarily change a running program's functionality through | |||||
a buffer overflow attack. | |||||
It is strongly suggested that the | |||||
.Fn fgets | |||||
function be used in all cases. |
Do we need a The function gets_s may also fail and set errno for any of the errors specified for the routine getchar.? This text existed for gets() and not updated to reference gets_s when it was added. @cy?