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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Reported-by: "G. Branden Robinson" <g.branden.robinson@xxxxxxxxx>
Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx>
---

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@xxxxxxxxxx>
+.\"
+.\" 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




[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux