From 399644e47874bff147afb19c89228901ac39340e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:40:15 +0200 Subject: Adding upstream version 6.05.01. Signed-off-by: Daniel Baumann --- man3/stdin.3 | 160 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 man3/stdin.3 (limited to 'man3/stdin.3') diff --git a/man3/stdin.3 b/man3/stdin.3 new file mode 100644 index 0000000..afe1fa5 --- /dev/null +++ b/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 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +stdin, stdout, stderr \- standard I/O streams +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.PP +.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).) +.PP +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 . +.PP +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). +.PP +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). +.PP +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 . +(Applying +.BR freopen (3) +to one of these streams can change the file descriptor number +associated with the stream.) +.PP +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. +.PP +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. +.PP +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) -- cgit v1.2.3