Changeset View
Changeset View
Standalone View
Standalone View
lib/libc/stdio/fgets.3
Show All 40 Lines | |||||
.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" | |||||
.Ft char * | |||||
bjk: Please remember to update .Dd when committing. | |||||
Not Done Inline ActionsI'll update it again just prior to commit. cy: I'll update it again just prior to commit. | |||||
Not Done Inline Actionsa post-commit comment: should gets_s also be in the title? .Sh NAME .Nm fgets , .Nm gets , .Nm gets_s .Nd get a line from a stream noticed while merging this to my working branch which has plain gets removed. emaste: a post-commit comment: should gets_s also be in the title?
```
.Sh NAME
.Nm fgets ,
.Nm gets ,
. | |||||
.Fn gets "char *str" | .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 | ||||
and stores them in the string | and stores them in the string | ||||
.Fa str . | .Fa str . | ||||
Reading stops when a newline character is found, | Reading stops when a newline character is found, | ||||
at end-of-file or error. | at end-of-file or error. | ||||
The newline, if any, is retained. | The newline, if any, is retained. | ||||
If any characters are read and there is no error, a | If any characters are read and there is no error, a | ||||
.Ql \e0 | .Ql \e0 | ||||
character is appended to end the string. | character is appended to end the string. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fn gets_s | |||||
function | |||||
is equivalent to | |||||
.Fn fgets | |||||
with a | |||||
.Fa stream | |||||
of | |||||
.Dv stdin , | |||||
except that the newline character (if any) is not stored in the string. | |||||
.Pp | |||||
The | |||||
.Fn gets | .Fn gets | ||||
function | function | ||||
is equivalent to | is equivalent to | ||||
.Fn fgets | .Fn fgets | ||||
with an infinite | with an infinite | ||||
.Fa size | .Fa size | ||||
and a | and a | ||||
.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. | ||||
It is the caller's responsibility to ensure that the input line, | It is the caller's responsibility to ensure that the input line, | ||||
if any, is sufficiently short to fit in the string. | 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 , | |||||
Not Done Inline Actions.Fn gets_s , wblock: [[ https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/writing-style-guidelines.html |… | |||||
and | and | ||||
.Fn gets | .Fn gets | ||||
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 , | |||||
Done Inline ActionsAs above: .Fn gets_s , wblock: As above:
```.Fn gets_s ,``` | |||||
and | and | ||||
.Fn gets | .Fn gets | ||||
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. | ||||
Show All 30 Lines | |||||
.Xr getline 3 | .Xr getline 3 | ||||
.Sh STANDARDS | .Sh STANDARDS | ||||
The functions | The functions | ||||
.Fn fgets | .Fn fgets | ||||
and | and | ||||
.Fn gets | .Fn gets | ||||
conform to | conform to | ||||
.St -isoC-99 . | .St -isoC-99 . | ||||
.Fn gets_s | |||||
conforms to | |||||
.St -isoC-2011 | |||||
K.3.7.4.1. | |||||
.Fn gets | |||||
has been removed from | |||||
.St -isoC-2011 . | |||||
.Sh SECURITY CONSIDERATIONS | .Sh SECURITY CONSIDERATIONS | ||||
The | The | ||||
.Fn gets | .Fn gets | ||||
function cannot be used securely. | function cannot be used securely. | ||||
Because of its lack of bounds checking, | Because of its lack of bounds checking, | ||||
and the inability for the calling program | and the inability for the calling program | ||||
to reliably determine the length of the next incoming line, | to reliably determine the length of the next incoming line, | ||||
the use of this function enables malicious users | the use of this function enables malicious users | ||||
to arbitrarily change a running program's functionality through | to arbitrarily change a running program's functionality through | ||||
a buffer overflow attack. | a buffer overflow attack. | ||||
It is strongly suggested that the | It is strongly suggested that the | ||||
.Fn fgets | .Fn fgets | ||||
function be used in all cases. | function be used in all cases. |
Please remember to update .Dd when committing.