Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 160 insertions, 0 deletions

diff --git a/man/man3/stdin.3 b/man/man3/stdin.3
new file mode 100644
index 0000000..7ffbc9a
--- /dev/null
+++ b/man/man3/stdin.3
@@ -0,0 +1,160 @@
+.\" From dholland@burgundy.eecs.harvard.edu Tue Mar 24 18:08:15 1998
+.\"
+.\" This man page was written in 1998 by David A. Holland
+.\" Polished a bit by aeb.
+.\"
+.\" %%%LICENSE_START(PUBLIC_DOMAIN)
+.\" Placed in the Public Domain.
+.\" %%%LICENSE_END
+.\"
+.\" 2005-06-16 mtk, mentioned freopen()
+.\" 2007-12-08, mtk, Converted from mdoc to man macros
+.\"
+.TH stdin 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+stdin, stdout, stderr \- standard I/O streams
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdio.h>
+.P
+.BI "extern FILE *" stdin ;
+.BI "extern FILE *" stdout ;
+.BI "extern FILE *" stderr ;
+.fi
+.SH DESCRIPTION
+Under normal circumstances every UNIX program has three streams opened
+for it when it starts up, one for input, one for output, and one for
+printing diagnostic or error messages.
+These are typically attached to
+the user's terminal (see
+.BR tty (4))
+but might instead refer to files or other devices, depending on what
+the parent process chose to set up.
+(See also the "Redirection" section of
+.BR sh (1).)
+.P
+The input stream is referred to as "standard input"; the output stream is
+referred to as "standard output"; and the error stream is referred to
+as "standard error".
+These terms are abbreviated to form the symbols
+used to refer to these files, namely
+.IR stdin ,
+.IR stdout ,
+and
+.IR stderr .
+.P
+Each of these symbols is a
+.BR stdio (3)
+macro of type pointer to
+.IR FILE ,
+and can be used with functions like
+.BR fprintf (3)
+or
+.BR fread (3).
+.P
+Since
+.IR FILE s
+are a buffering wrapper around UNIX file descriptors, the
+same underlying files may also be accessed using the raw UNIX file
+interface, that is, the functions like
+.BR read (2)
+and
+.BR lseek (2).
+.P
+On program startup, the integer file descriptors
+associated with the streams
+.IR stdin ,
+.IR stdout ,
+and
+.I stderr
+are 0, 1, and 2, respectively.
+The preprocessor symbols
+.BR STDIN_FILENO ,
+.BR STDOUT_FILENO ,
+and
+.B STDERR_FILENO
+are defined with these values in
+.IR <unistd.h> .
+(Applying
+.BR freopen (3)
+to one of these streams can change the file descriptor number
+associated with the stream.)
+.P
+Note that mixing use of
+.IR FILE s
+and raw file descriptors can produce
+unexpected results and should generally be avoided.
+(For the masochistic among you: POSIX.1, section 8.2.3, describes
+in detail how this interaction is supposed to work.)
+A general rule is that file descriptors are handled in the kernel,
+while stdio is just a library.
+This means for example, that after an
+.BR exec (3),
+the child inherits all open file descriptors, but all old streams
+have become inaccessible.
+.P
+Since the symbols
+.IR stdin ,
+.IR stdout ,
+and
+.I stderr
+are specified to be macros, assigning to them is nonportable.
+The standard streams can be made to refer to different files
+with help of the library function
+.BR freopen (3),
+specially introduced to make it possible to reassign
+.IR stdin ,
+.IR stdout ,
+and
+.IR stderr .
+The standard streams are closed by a call to
+.BR exit (3)
+and by normal program termination.
+.SH STANDARDS
+C11, POSIX.1-2008.
+.P
+The standards also stipulate that these three
+streams shall be open at program startup.
+.SH HISTORY
+C89, POSIX.1-2001.
+.SH NOTES
+The stream
+.I stderr
+is unbuffered.
+The stream
+.I stdout
+is line-buffered when it points to a terminal.
+Partial lines will not
+appear until
+.BR fflush (3)
+or
+.BR exit (3)
+is called, or a newline is printed.
+This can produce unexpected
+results, especially with debugging output.
+The buffering mode of the standard streams (or any other stream)
+can be changed using the
+.BR setbuf (3)
+or
+.BR setvbuf (3)
+call.
+Note that in case
+.I stdin
+is associated with a terminal, there may also be input buffering
+in the terminal driver, entirely unrelated to stdio buffering.
+(Indeed, normally terminal input is line buffered in the kernel.)
+This kernel input handling can be modified using calls like
+.BR tcsetattr (3);
+see also
+.BR stty (1),
+and
+.BR termios (3).
+.SH SEE ALSO
+.BR csh (1),
+.BR sh (1),
+.BR open (2),
+.BR fopen (3),
+.BR stdio (3)