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

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

[Alejandro Colomar]

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

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

[Alejandro Colomar]

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/>