EOF.3const: Add documentation for EOF
PATCH 1/1 EOF.3const: Add documentation for EOF
Reported-by "G. Branden Robinson" <[email protected]>
Signed-off-by Alejandro Colomar <[email protected]>
---
Hi Branden!
How do you feel about this page?
I wasn't inspired to write an example program. I welcome any input if you or someone reading the list has a trivial one at hand.
Cheers,
Alex
man3const/EOF.3const | 54 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 man3const/EOF.3const
man3const/EOF.3const new file +54 -0
@@ -0,0 +1,54 @@ +.\" Copyright (c) 2022 by Alejandro Colomar <[email protected]> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH EOF 3const (date) "Linux man-pages (unreleased)" +.SH NAME +EOF \- end of file or error indicator +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.PP +.B "#define EOF /* ... */" +.fi +.SH DESCRIPTION +.B EOF +represents the end of an input file, or an error indication. +It is a negative value, of type +.IR int . +.PP +.B EOF +is not a character +(it can't be represented by +.IR "unsigned char" ). +It is instead a sentinel value outside of the valid range for valid characters. +.SH CONFORMING TO +C99 and later; +POSIX.1-2001 and later. +.SH CAVEATS +.SS Input +Programs should read the return value of an input function +before using functions of the +.BR feof (3) +family. +Only when the function returned the sentinel value +.B EOF +it makes sense to distinguish between the end of a file or an error with +.BR feof (3) +or +.BR ferror (3). +.SS Output +Programs can't pass this value to an output function +to "write" the end of a file. +That would likely result in undefined behavior. +Instead, +closing the writing stream or file descriptor +that refers to such file +is the way to signal the end of that file. +.SH SEE ALSO +.BR feof (3), +.BR fgetc (3)
Signature · 1 line
2.37.2
Quoted 57 lines · Alejandro Colomar
Reported-by "G. Branden Robinson" <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
Hi Branden!
How do you feel about this page?
I wasn't inspired to write an example program. I welcome any input if you or someone reading the list has a trivial one at hand.
Cheers,
Alexman3const/EOF.3const | 54 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+)create mode 100644 man3const/EOF.3const
man3const/EOF.3const new file +33
-0@@ -0,0 +1,54 @@ +.\" Copyright (c) 2022 by Alejandro Colomar <[email protected]> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" +.TH EOF 3const (date) "Linux man-pages (unreleased)" +.SH NAME +EOF \- end of file or error indicator +.SH LIBRARY +Standard C library +.RI ( libc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.PP +.B "#define EOF /* ... */" +.fi +.SH DESCRIPTION +.B EOF +represents the end of an input file, or an error indication. +It is a negative value, of type +.IR int . +.PP +.B EOF +is not a character +(it can't be represented by +.IR "unsigned char" ). +It is instead a sentinel value outside of the valid range for valid characters. +.SH CONFORMING TO +C99 and later; +POSIX.1-2001 and later. +.SH CAVEATS +.SS Input
man3const/EOF.3const line 43
Quoted 10 lines
man3const/EOF.3const new file +10
-0+Programs should read the return value of an input function +before using functions of the +.BR feof (3) +family. +Only when the function returned the sentinel value +.B EOF +it makes sense to distinguish between the end of a file or an error with +.BR feof (3) +or +.BR ferror (3).
While the 'Output' caveat is a proper caveat of EOF, I'm feeling that the 'Input' caveat is more a caveat of feof(3), and belongs to that other page.
Quoted 11 lines
man3const/EOF.3const new file +11
-0+.SS Output +Programs can't pass this value to an output function +to "write" the end of a file. +That would likely result in undefined behavior. +Instead, +closing the writing stream or file descriptor +that refers to such file +is the way to signal the end of that file. +.SH SEE ALSO +.BR feof (3), +.BR fgetc (3)
Signature · 1 line
<http://www.alejandro-colomar.es/>