Re: [PATCH] EOF.3const: Add documentation for EOF

[Alejandro Colomar <alx.manpages@gmail.com>]

On 10/14/22 21:18, Alejandro Colomar wrote:
> Reported-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> ---
> 
> 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
> 
> diff --git a/man3const/EOF.3const b/man3const/EOF.3const
> new file mode 100644
> index 000000000..f59511a47
> --- /dev/null
> +++ b/man3const/EOF.3const
> @@ -0,0 +1,54 @@
> +.\" Copyright (c) 2022 by Alejandro Colomar <alx@kernel.org>
> +.\"
> +.\" 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).

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.

> +.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)

-- 
<http://www.alejandro-colomar.es/>