Quarantine "gets.3" into its own "do not use" manpage
PATCH 1/1 Quarantine "gets.3" into its own "do not use" manpage
Currently man3/gets.3 documents various safe I/O functions, along with the toxic "gets" function.
At the risk of being melodramatic, this strikes me as akin to storing rat poison in a food cabinet, in the same style of packaging as the food, but with a post-it note on it saying "see warnings below".
I think such "never use this" functions should be quarantined into their own manpages, rather than listing them alongside sane functions.
The attached patch does this for "gets", moving the documentation of the good functions from man3/gets.3 into man3/fgetc.3, updating the SO links in the relevant functions to point at the latter.
It then rewrites man3/gets.3 to spell out that "gets" is toxic and should never be used (with a link to CWE-242 for good measure).
Thoughts?
Dave
[Note to self: I filed this downstream as:
https://bugzilla.redhat.com/show_bug.cgi?id=1030030 ]
commit b80d17cf9cee57ab88d8d2b1bf01a2d82aef26e8
Author: David Malcolm <[email protected]> Date: Wed Nov 13 14:14:58 2013 -0500
Move gets.3 into its own page and more clearly label it as toxic
man3/fgetc.3 +150 -1
@@ -1 +1,150 @@ -.so man3/gets.3 +.\" Copyright (c) 1993 by Thomas Koenig (ig25-L38z05uLna+pU24hk/[email protected]) +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.\" Modified Wed Jul 28 11:12:07 1993 by Rik Faith ([email protected]) +.\" Modified Fri Sep 8 15:48:13 1995 by Andries Brouwer ([email protected]) +.TH FGETC 3 2012-01-18 "GNU" "Linux Programmer's Manual" +.SH NAME +fgetc, fgets, getc, getchar, ungetc \- input of characters and strings +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.sp +.BI "int fgetc(FILE *" stream ); + +.BI "char *fgets(char *" "s" ", int " "size" ", FILE *" "stream" ); + +.BI "int getc(FILE *" stream ); + +.B "int getchar(void);" + +.BI "int ungetc(int " c ", FILE *" stream ); +.fi +.SH DESCRIPTION +.BR fgetc () +reads the next character from +.I stream +and returns it as an +.I unsigned char +cast to an +.IR int , +or +.B EOF +on end of file or error. +.PP +.BR getc () +is equivalent to +.BR fgetc () +except that it may be implemented as a macro which evaluates +.I stream +more than once. +.PP +.BR getchar () +is equivalent to +.BI "getc(" stdin ) \fR. +.PP +.BR fgets () +reads in at most one less than +.I size +characters from +.I stream +and stores them into the buffer pointed to by +.IR s . +Reading stops after an +.B EOF +or a newline. +If a newline is read, it is stored into the buffer. +A terminating null byte (\(aq\e0\(aq) +is stored after the last character in the buffer. +.PP +.BR ungetc () +pushes +.I c +back to +.IR stream , +cast to +.IR "unsigned char" , +where it is available for subsequent read operations. +Pushed-back characters +will be returned in reverse order; only one pushback is guaranteed. +.PP +Calls to the functions described here can be mixed with each other and with +calls to other input functions from the +.I stdio +library for the same input stream. +.PP +For nonlocking counterparts, see +.BR unlocked_stdio (3). +.SH RETURN VALUE +.BR fgetc (), +.BR getc () +and +.BR getchar () +return the character read as an +.I unsigned char +cast to an +.I int +or +.B EOF +on end of file or error. +.PP +.BR fgets () +returns +.I s +on success, and NULL +on error or when end of file occurs while no characters have been read. +.PP +.BR ungetc () +returns +.I c +on success, or +.B EOF +on error. +.SH CONFORMING TO +C89, C99, POSIX.1-2001. + +.PP +It is not advisable to mix calls to input functions from the +.I stdio +library with low-level calls to +.BR read (2) +for the file descriptor associated with the input stream; the results +will be undefined and very probably not what you want. +.SH SEE ALSO +.BR read (2), +.BR write (2), +.BR ferror (3), +.BR fgetwc (3), +.BR fgetws (3), +.BR fopen (3), +.BR fread (3), +.BR fseek (3), +.BR getline (3), +.BR getwchar (3), +.BR puts (3), +.BR gets (3), +.BR scanf (3), +.BR ungetwc (3), +.BR unlocked_stdio (3), +.BR feature_test_macros (7)
man3/fgets.3 +1 -1
@@ -1 +1 @@ -.so man3/gets.3 +.so man3/fgetc.3
man3/getc.3 +1 -1
@@ -1 +1 @@ -.so man3/gets.3 +.so man3/fgetc.3
man3/getchar.3 +1 -1
@@ -1 +1 @@ -.so man3/gets.3 +.so man3/fgetc.3
man3/gets.3 +19 -97
148 lines not on this page · raw message
man3/ungetc.3 +1 -1
@@ -1 +1 @@ -.so man3/gets.3 +.so man3/fgetc.3
Quoted 10 lines · David Malcolm
Currently man3/gets.3 documents various safe I/O functions, along with the toxic "gets" function.
At the risk of being melodramatic, this strikes me as akin to storing rat poison in a food cabinet, in the same style of packaging as the food, but with a post-it note on it saying "see warnings below".
I think such "never use this" functions should be quarantined into their own manpages, rather than listing them alongside sane functions.
Quoted 8 lines
The attached patch does this for "gets", moving the documentation of the good functions from man3/gets.3 into man3/fgetc.3, updating the SO links in the relevant functions to point at the latter.
It then rewrites man3/gets.3 to spell out that "gets" is toxic and should never be used (with a link to CWE-242 for good measure).
Thoughts?
For what my opinion's worth, I like this patch. it makes it harder to miss the warnings.
Two objections :
1. Seems C89, C99 and POSIX.1-2001 have been dropped from the CONFORMING TO section. If that is deliberate, I would like to know the rationale behind this change.
2. Rather than
gets() is supposed to return s on success, and NULL on error or when end of file occurs while no characters have been read. However, given the lack of buffer overrun checking, there can be no guarantees that the function will even return.
how about
gets() returns s on success and NULL on error or when end of file occurs while no characters have been read. Unless the buffer is overrun, in which case there is no guarantee that the function will even return.
The idea is to avoid "is supposed to", which feels out of place in a reference document. Refreshingly sarcastic as it may be. :->
The "For more information, see CWE-242" bit is in the BUGS section, right ? Can't tell from the diff alone.
Signature · 5 lines
André Majorel http://www.teaser.fr/~amajorel/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): 20131115185455.GA20757-956IwFboN44acnK+F/[email protected]
Andre,
Thanks for reviewing this patch.
Quoted 21 lines · Andre Majorel
Quoted 10 lines · David Malcolm
Currently man3/gets.3 documents various safe I/O functions, along with the toxic "gets" function.
At the risk of being melodramatic, this strikes me as akin to storing rat poison in a food cabinet, in the same style of packaging as the food, but with a post-it note on it saying "see warnings below".
I think such "never use this" functions should be quarantined into their own manpages, rather than listing them alongside sane functions.
Quoted 8 lines
The attached patch does this for "gets", moving the documentation of the good functions from man3/gets.3 into man3/fgetc.3, updating the SO links in the relevant functions to point at the latter.
It then rewrites man3/gets.3 to spell out that "gets" is toxic and should never be used (with a link to CWE-242 for good measure).
Thoughts?
Quoted 8 lines
For what my opinion's worth, I like this patch. it makes it harder to miss the warnings.
Two objections :
1. Seems C89, C99 and POSIX.1-2001 have been dropped from the CONFORMING TO section. If that is deliberate, I would like to know the rationale behind this change.
Good catch. It should not have been, and I've restored it.
Quoted 10 lines
2. Rather than
gets()is supposed to return s on success, and NULL on error or when end of file occurs while no characters have been read. However, given the lack of buffer overrun checking, there can be no guarantees that the function will even return.how about
Quoted 8 lines
gets()returns s on success and NULL on error or when end of file occurs while no characters have been read. Unless the buffer is overrun, in which case there is no guarantee that the function will even return.The idea is to avoid "is supposed to", which feels out of place in a reference document. Refreshingly sarcastic as it may be. :->
Agreed. I made the first of your suggested changes, but left the second sentence unchanged.
Quoted 2 lines
The "For more information, see CWE-242" bit is in the BUGS section, right ? Can't tell from the diff alone.
Yes, it's in BUGS.
Cheers,
Michael
Signature · 7 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Am 13.11.2013 20:20, schrieb David Malcolm:
Quoted 14 lines
Currently man3/gets.3 documents various safe I/O functions, along with the toxic "gets" function.
At the risk of being melodramatic, this strikes me as akin to storing rat poison in a food cabinet, in the same style of packaging as the food, but with a post-it note on it saying "see warnings below".
I think such "never use this" functions should be quarantined into their own manpages, rather than listing them alongside sane functions.
The attached patch does this for "gets", moving the documentation of the good functions from man3/gets.3 into man3/fgetc.3, updating the SO links in the relevant functions to point at the latter.
Quoted 10 lines
It then rewrites man3/gets.3 to spell out that "gets" is toxic and should never be used (with a link to CWE-242 for good measure).
Thoughts?
Dave[Note to self: I filed this downstream as:
https://bugzilla.redhat.com/show_bug.cgi?id=1030030 ]
This is a good idea, it would also be helpful to have a list of do-not-use function *including* the rational why in its own page. We already have pages like 'undocumented' so it is not uniq.
re,
wh
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Hello David,
Quoted 14 lines · David Malcolm
Currently man3/gets.3 documents various safe I/O functions, along with the toxic "gets" function.
At the risk of being melodramatic, this strikes me as akin to storing rat poison in a food cabinet, in the same style of packaging as the food, but with a post-it note on it saying "see warnings below".
I think such "never use this" functions should be quarantined into their own manpages, rather than listing them alongside sane functions.
The attached patch does this for "gets", moving the documentation of the good functions from man3/gets.3 into man3/fgetc.3, updating the SO links in the relevant functions to point at the latter.
Quoted 8 lines
It then rewrites man3/gets.3 to spell out that "gets" is toxic and should never be used (with a link to CWE-242 for good measure).
Thoughts?
Dave[Note to self: I filed this downstream as:
https://bugzilla.redhat.com/show_bug.cgi?id=1030030 ]
Seems reasonable to me. Applied, with a few tweaks.
Cheers,
Michael
Signature · 7 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html