Editing Standard streams

{{Short description|Connected input and output streams for computer programs}}
{{About|standard I/O file descriptors|System V streams|STREAMS}}
In [[computer programming]], '''standard streams''' are preconnected input and output [[communication channel]]s<ref>D. M. Ritchie, [https://cseweb.ucsd.edu/classes/fa01/cse221/papers/ritchie-stream-io-belllabs84.pdf "A Stream Input-Output System"], AT&T Bell Laboratories Technical Journal, 68(8), October 1984.</ref> between a computer program and its environment when it begins execution. The three [[input/output]] (I/O) connections are called '''standard input''' ('''stdin'''), '''standard output''' ('''stdout''') and '''standard error''' ('''stderr'''). Originally I/O happened via a physically connected [[system console]] (input via keyboard, output via monitor), but standard streams abstract this. When a command is executed via an interactive [[Shell (computing)|shell]], the streams are typically connected to the [[text terminal]] on which the shell is running, but can be changed with [[Redirection (computing)|redirection]] or a [[Pipeline (Unix)|pipeline]]. More generally, a [[child process]] inherits the standard streams of its [[parent process]].

==Application ==
[[File:Stdstreams-notitle.svg|thumb|right|The standard streams for input, output, and error in a common default configuration|206x206px]]
Users generally know standard streams as input and output channels that handle data coming from an input device, or that write data from the application. The data may be text with any encoding, or [[Binary file|binary data]].
When a program is run as a [[Daemon (computing)|daemon]], its standard error stream is redirected into a log file, typically for error analysis purposes.

Streams may be used to chain applications, meaning that the output stream of one program can be redirected to be the input stream to another application. In many operating systems this is expressed by listing the application names, separated by the vertical bar character, for this reason often called the [[pipeline (Unix)|pipeline]] character. A well-known example is the use of a [[pagination]] application, such as [[more (command)|more]], providing the user control over the display of the output stream on the display.

==Background==
In most operating systems predating [[Unix]], programs had to explicitly connect to the appropriate input and output devices. OS-specific intricacies caused this to be a tedious programming task. On many systems it was necessary to obtain control of environment settings, access a local file table, determine the intended data set, and handle hardware correctly in the case of a [[punch card reader]], [[magnetic tape drive]], [[disk drive]], [[line printer]], card punch, or interactive terminal.

One of Unix's several groundbreaking advances was ''abstract devices'', which removed the need for a program to know or care what kind of devices it was communicating with{{citation needed|date=December 2013}}. Older operating systems forced upon the programmer a record structure and frequently [[orthogonal#Computer science|non-orthogonal]] data semantics and device control.  Unix eliminated this complexity with the concept of a data stream:  an ordered sequence of data bytes which can be read until the [[End-of-file|end of file]].  A program may also write bytes as desired and need not, and cannot easily declare their count or grouping.

Another Unix breakthrough was to automatically associate input and output to terminal keyboard and terminal display, respectively, by default{{citation needed|date=December 2013}} — the program (and programmer) did absolutely nothing to establish input and output for a typical input-process-output program (unless it chose a different paradigm).  In contrast, previous operating systems usually required some—often complex—[[Job Control Language|job control language]] to establish connections, or the equivalent burden had to be orchestrated by the program.{{citation needed|date=October 2017}}

Since Unix provided standard streams, the Unix [[C (programming language)|C]] runtime environment was obliged to support it as well.  As a result, most C runtime environments (and [[C (programming language)#Related languages|C's descendants]]), regardless of the operating system, provide equivalent functionality.

{{anchor|stdin}}
==Standard input (stdin)==<!-- This section is linked from [[COMMAND.COM]] -->
Standard input is a stream from which a program reads its input data. The program requests data transfers by use of the ''read'' operation. Not all programs require stream input. For example, the ''[[dir (command)|dir]]'' and ''[[ls]]'' programs (which display file names contained in a directory) may take [[Command-line interface#Arguments|command-line arguments]], but perform their operations without any stream data input.

Unless [[Redirection (computing)|redirected]], standard input is inherited from the parent process.  In the case of an interactive shell, that is usually associated with the input device of a [[Computer terminal|terminal]] (or [[Pseudoterminal|pseudo terminal]]) which is ultimately linked to a user's [[Keyboard (computing)|keyboard]].

On [[POSIX]] systems, the [[file descriptor]] for standard input is 0 (zero); the [[POSIX]] <code><unistd.h></code> definition is <code>STDIN_FILENO</code>; the corresponding C <code><stdio.h></code> abstraction is provided via the <code>FILE* stdin</code> global variable. Similarly, the global C++  <code>std::cin</code> variable of type <code><iostream></code> provides an abstraction via [[Input/output_(C%2B%2B)#Input/output_streams|C++ streams]]. Similar abstractions exist in the standard I/O libraries of practically every [[programming language]].

==Standard output (stdout)==<!-- This section is linked from [[COMMAND.COM]] -->
Standard output is a stream to which a program writes its output data.  The program requests data transfer with the ''write'' operation.  Not all programs generate output.  For example, the ''[[rename (computing)|file rename]]'' command (variously called ''[[mv (Unix)|mv]]'', ''[[move (command)|move]]'', or ''[[ren (command)|ren]]'') is silent on success.

Unless [[Redirection (computing)|redirected]], standard output is inherited from the parent process.  In the case of an interactive shell, that is usually the [[text terminal]] which initiated the program.

The [[file descriptor]] for standard output is 1 (one); the [[POSIX]] <code><unistd.h></code> definition is <code>STDOUT_FILENO</code>; the corresponding C <code><stdio.h></code> variable is <code>FILE* stdout</code>; similarly, the C++ <code><iostream></code> variable is <code>std::cout</code>.

==Standard error (stderr)==<!-- This section is linked from [[COMMAND.COM]] -->
Standard error is another output stream typically used by programs to output [[error message]]s or diagnostics.  It is a stream independent of standard output and can be redirected separately.

This solves the [[semipredicate problem|semi-predicate problem]], allowing output and errors to be distinguished, and is analogous to a function returning a pair of values – see {{section link|Semipredicate problem|Multivalued return}}. The usual destination is the [[text terminal]] which started the program to provide the best chance of being seen even if ''standard output'' is redirected (so not readily observed). For example, output of a program in a [[pipeline (Unix)|pipeline]] is redirected to input of the next program or a text file, but errors from each program still go directly to the text terminal so they can be reviewed by the user in real time.

It is acceptable and normal to direct ''standard output'' and ''standard error'' to the same destination, such as the text terminal.  Messages appear in the same order as the program writes them, unless [[Data buffer|buffering]] is involved. For example, in common situations the standard error stream is unbuffered but the standard output stream is line-buffered; in this case, text written to standard error later may appear on the terminal earlier, if the standard output stream buffer is not yet full.

The [[file descriptor]] for standard error is defined by [[POSIX]] as 2 (two); the ''&lt;unistd.h>'' header file provides the symbol <code>STDERR_FILENO</code>;<ref>{{cite web |url=http://pubs.opengroup.org/onlinepubs/009695399/basedefs/unistd.h.html |work=The Open Group Base Specifications Issue 6&mdash;IEEE Std 1003.1, 2004 Edition |title=&lt;unistd.h> |publisher=The Open Group |year=2004 }}</ref> the corresponding C <code><stdio.h></code> variable is <code>FILE* stderr</code>. The C++ <code><iostream></code> standard header provides two variables associated with this stream: <code>std::cerr</code> and <code>std::clog</code>, the former being unbuffered and the latter using the same buffering mechanism as all other C++ streams.

[[Bourne shell|Bourne]]-style shells allow ''standard error'' to be redirected to the same destination that standard output is directed to using
  2&gt;&amp;1

[[C shell|csh]]-style shells allow ''standard error'' to be redirected to the same destination that standard output is directed to using
  &gt;&amp;

Standard error was added to Unix in the 1970s after several wasted phototypesetting runs ended with error messages being typeset instead of displayed on the user's terminal.<ref>{{cite mailing list |url=https://minnie.tuhs.org/pipermail/tuhs/2013-December/006113.html |title=[TUHS] Graphic Systems C/A/T phototypesetter |work=The Unix Heritage Society |date=2013-12-11 |first=Steve |last=Johnson |author-link=Stephen C. Johnson |access-date=2020-11-07 |url-status=live |archive-url=https://web.archive.org/web/20200925010614/https://minnie.tuhs.org/pipermail/tuhs/2013-December/006113.html |archive-date=2020-09-25}}</ref>

== Timeline ==

=== 1950s: Fortran ===
[[Fortran]] has the equivalent of Unix file descriptors: By convention, many Fortran implementations use unit numbers <code>UNIT=5</CODE> for stdin, <CODE>UNIT=6</CODE> for stdout and <CODE>UNIT=0</CODE> for stderr.  In Fortran-2003, the intrinsic <code>ISO_FORTRAN_ENV</code> module was standardized to include the named constants <code>INPUT_UNIT</code>, <code>OUTPUT_UNIT</code>, and <code>ERROR_UNIT</code> to portably specify the unit numbers.
<syntaxhighlight lang="fortran">
! FORTRAN 77 example
      PROGRAM MAIN
        INTEGER NUMBER
        READ(UNIT=5,*) NUMBER
        WRITE(UNIT=6,'(A,I3)') ' NUMBER IS: ',NUMBER
      END
</syntaxhighlight>
<syntaxhighlight lang="fortran">
! Fortran 2003 example
program main
  use iso_fortran_env
  implicit none
  integer :: number
  read (unit=INPUT_UNIT,*) number
  write (unit=OUTPUT_UNIT,'(a,i3)') 'Number is: ', number
end program
</syntaxhighlight>

=== 1960: ALGOL 60===
[[ALGOL 60]] was criticized for having no standard file access.{{citation needed|date=February 2012}}

=== 1968: ALGOL 68===
[[ALGOL 68]]'s input and output facilities were collectively referred to as the transput.<ref>"[http://www.softwarepreservation.org/projects/ALGOL/report/Algol68_revised_report-AB.pdf Revised Report on the Algorithmic Language Algol 68]", edited by A. van Wijngaarden, B.J. Mailloux, J.E.L. Peck, C.H.A. Koster, M. Sintzoff, C.H. Lindsey, L.G.L.T. Meertens and R.G. Fisker, Section 10.3.</ref> [[Cornelis H. A. Koster|Koster]]  coordinated the definition of the ''transput'' standard.  The model included three standard channels: <code>stand in</code>, <code>stand out</code>, and <code>stand back</code>.

{|
|+ '''Example'''
|colspan="2"|<syntaxhighlight lang="text">
# ALGOL 68 example #
main:(
  REAL number;
  getf(stand in,($g$,number));
  printf(($"Number is: "g(6,4)"OR "$,number)); # OR #
  putf(stand out,($" Number is: "g(6,4)"!"$,number));
  newline(stand out)
)</syntaxhighlight>
|-
!align="left"|Input:
!align="left"|Output: 
|-
|<pre>3.14159</pre>
|<pre>Number is: +3.142 OR Number is: +3.142!</pre>
|}

=== 1970s: C and Unix ===
In the [[C programming language]], the standard input, output, and error streams are attached to the existing Unix file descriptors 0, 1 and 2 respectively.<ref>{{Cite web|url=http://linux.die.net/man/3/stdin|title = Stdin(3): Standard I/O streams - Linux man page |website=die.net |url-status=live |archive-url=https://web.archive.org/web/20230608111413/https://linux.die.net/man/3/stdin |archive-date= Jun 8, 2023 }}</ref> In a [[POSIX]] environment the ''<[[unistd.h]]>'' definitions ''STDIN_FILENO'', ''STDOUT_FILENO'' or ''STDERR_FILENO'' should be used instead rather than [[Magic number (programming)|magic numbers]].   File pointers ''stdin'', ''stdout'', and ''stderr'' are also provided.

[[Ken Thompson]] (designer and implementer of the original Unix operating system) modified [[sort (Unix)|sort]] in [[Version 5 Unix]] to accept "-" as representing standard input, which spread to other utilities and became a part of the operating system as a [[special file]] in [[Version 8 Unix|Version 8]]. Diagnostics were part of standard output through [[Version 6 Unix|Version 6]], after which [[Dennis M. Ritchie]] created the concept of standard error.<ref name="reader">{{cite tech report |first1=M. D. |last1=McIlroy |author-link1=Doug McIlroy |year=1987 |url=http://www.cs.dartmouth.edu/~doug/reader.pdf |title=A Research Unix reader: annotated excerpts from the Programmer's Manual, 1971–1986 |series=CSTR |number=139 |institution=Bell Labs |url-status=live |archive-url=https://web.archive.org/web/20231215143742/https://www.cs.dartmouth.edu/~doug/reader.pdf |archive-date= Dec 15, 2023 }}</ref>

===1995: Java ===
In [[Java (programming language)|Java]], the standard streams are referred to by {{Javadoc:SE|java/lang|System|in}} (for stdin), {{Javadoc:SE|java/lang|System|out}} (for stdout), and  {{Javadoc:SE|java/lang|System|err}} (for stderr).<ref>{{cite web|title=System (Java Platform SE 7)|url=http://docs.oracle.com/javase/7/docs/api/java/lang/System.html |website=Oracle Help Center |access-date=20 July 2012}}</ref> 
<syntaxhighlight lang="java">
public static void main(String args[]) {
    try {
        BufferedReader br = 
          new BufferedReader(new InputStreamReader(System.in));
        String s = br.readLine();
        double number = Double.parseDouble(s);
        System.out.println("Number is:" + number);
    } catch (Exception e) {
        System.err.println("Error:" + e.getMessage());
    }
}
</syntaxhighlight>

===2000s: .NET ===
In [[C Sharp (programming language)|C#]] and other [[.NET Framework|.NET]] languages, the standard streams are referred to by <code>System.Console.In</code> (for stdin), <code>System.Console.Out</code> (for stdout) and <code>System.Console.Error</code> (for stderr).<ref>{{Cite web|url=https://referencesource.microsoft.com/#mscorlib/system/console.cs,34|title= .NET Framework 4.7.1, mscorlib, console.cs |website=Reference Source - Microsoft |access-date=2017-12-10 |url-status=live |archive-url= https://web.archive.org/web/20171210072215/https://referencesource.microsoft.com/#mscorlib/system/console.cs,34 |archive-date= Dec 10, 2017 }}</ref> Basic read and write capabilities for the stdin and stdout streams are also accessible directly through the class <code>System.Console</code> (e.g. <code>System.Console.WriteLine()</code> can be used instead of <code>System.Console.Out.WriteLine()</code>).

<code>System.Console.In</code>, <code>System.Console.Out</code> and <code>System.Console.Error</code> are <code>System.IO.TextReader</code> (stdin) and <code>System.IO.TextWriter</code> (stdout, stderr) objects, which only allow access to the underlying standard streams on a text basis. Full binary access to the standard streams must be performed through the <code>System.IO.Stream</code> objects returned by <code>System.Console.OpenStandardInput()</code>, <code>System.Console.OpenStandardOutput()</code> and <code>System.Console.OpenStandardError()</code> respectively.
<syntaxhighlight lang="c#">
// C# example
public static int Main(string[] args)
{
    try {
        string s = System.Console.In.ReadLine();
        double number = double.Parse(s);
        System.Console.Out.WriteLine("Number is: {0:F3}", number);
        return 0;

    // If Parse() threw an exception
    } catch (ArgumentNullException) { 
        System.Console.Error.WriteLine("No number was entered!");
    } catch (FormatException) {
        System.Console.Error.WriteLine("The specified value is not a valid number!");
    } catch (OverflowException) {
        System.Console.Error.WriteLine("The specified number is too big!");
    }

    return -1;
}
</syntaxhighlight>

<syntaxhighlight lang="vbnet">
' Visual Basic .NET example

Public Function Main() As Integer
    Try
        Dim s As String = System.Console.[In].ReadLine()
        Dim number As Double = Double.Parse(s)
        System.Console.Out.WriteLine("Number is: {0:F3}", number)
        Return 0

    ' If Parse() threw an exception
    Catch ex As System.ArgumentNullException
        System.Console.[Error].WriteLine("No number was entered!")
    Catch ex2 As System.FormatException
        System.Console.[Error].WriteLine("The specified value is not a valid number!")
    Catch ex3 As System.OverflowException
        System.Console.[Error].WriteLine("The specified number is too big!")
    End Try

    Return -1
End Function
</syntaxhighlight>

When applying the <code>System.Diagnostics.Process</code> [[class (computer science)|class]] one can use the instance [[Property (programming)|properties]] <code>StandardInput</code>, <code>StandardOutput</code>, and <code>StandardError</code> of that class to access the standard streams of the process.

===2000 - : Python (2 or 3) ===
The following example, written in [[Python (programming language)|Python]], shows how to redirect the standard input both to the standard output
and to a text file.

<syntaxhighlight lang="python" line="1">
#!/usr/bin/env python
import sys
# Save the current stdout so that we can revert sys.stdout
# after we complete our redirection
stdin_fileno = sys.stdin
stdout_fileno = sys.stdout
# Redirect sys.stdout to the file
sys.stdout = open("myfile.txt", "w")
ctr = 0
for inps in stdin_fileno:
    ctrs = str(ctr)
    # Prints to the redirected stdout ()
    sys.stdout.write(ctrs + ") this is to the redirected --->" + inps + "\n")
    # Prints to the actual saved stdout handler
    stdout_fileno.write(ctrs + ") this is to the actual  --->" + inps + "\n")
    ctr = ctr + 1
# Close the file
sys.stdout.close()
# Restore sys.stdout to our old saved file handler
sys.stdout = stdout_fileno
</syntaxhighlight>

===GUIs===
[[Graphical user interface]]s (GUIs) do not always make use of the standard streams; they do when GUIs are wrappers of underlying scripts and/or console programs, for instance the [[Synaptic (software)|Synaptic]] package manager GUI, which wraps apt commands in Debian and/or Ubuntu. GUIs created with scripting tools like Zenity and KDialog by [[KDE]] project<ref>{{cite web |url=https://www.linux-magazine.com/Issues/2009/99/Zenity-and-KDialog |first=Kristian |last=Kißling |title=Adding graphic elements to your scripts with Zenity and KDialog |website=[[Linux Magazine]] |date=2009 |access-date=2021-04-11}}</ref> make use of stdin, stdout, and stderr, and are based on simple scripts rather than a complete GUI programmed and compiled in C/C++ using [[Qt (software)|Qt]], [[GTK]], or other equivalent proprietary widget framework.

The [[Services menu]], as implemented on [[NeXTSTEP]] and [[Mac OS X]], is also analogous to standard streams. On these operating systems, graphical applications can provide functionality through a system-wide menu that operates on the current [[wikt:selection|selection]] in the GUI, no matter in what application.

Some GUI programs, primarily on Unix, still write debug information to standard error. Others (such as many Unix media players) may read files from standard input. Popular Windows programs that open a separate console window in addition to their GUI windows are the emulators [[pSX (emulator)|pSX]] and [[DOSBox]].

[[GTK-server]] can use stdin as a communication interface with an interpreted program to realize a GUI.

The [[CLIM|Common Lisp Interface Manager]] paradigm "presents" GUI elements sent to an extended output stream.

==See also==
* [[Redirection (computing)]]
* [[Stream (computing)]]
* [[Input/output]]
* [[C file input/output]]
* [[SYSIN]] and [[SYSOUT]]
* [[Files-11#Logical_names|Standard streams in the Files-11 file system]]

==References==
{{Reflist}}

==Sources==
{{refbegin}}
* "[https://www.gnu.org/software/libc/manual/html_node/Standard-Streams.html Standard Streams]", [https://www.gnu.org/software/libc/manual/html_node/index.html The GNU C Library]
* ''KRONOS 2.1 Reference Manual'', Control Data Corporation, Part Number 60407000, 1974
* ''NOS Version 1 Applications Programmer's Instant'', Control Data Corporation, Part Number 60436000, 1978
* [http://www.bitsavers.org/pdf/honeywell/multics/AG90-03_PgmgIntro_Dec81.pdf Level 68 Introduction to Programming on MULTICS] {{Webarchive|url=https://web.archive.org/web/20210225022744/http://www.bitsavers.org/pdf/honeywell/multics/AG90-03_PgmgIntro_Dec81.pdf |date=2021-02-25 }}, Honeywell Corporation, 1981
* [https://web.archive.org/web/20191009002342/https://pdfs.semanticscholar.org/a8e4/4d068a376c42513a4e10d6a751702710afee.pdf Evolution of the MVS Operating System], IBM Corporation, 1981
* ''Lions' Commentary on UNIX Sixth Edition'', John Lions, {{ISBN|1-57398-013-7}}, 1977
* [http://msdn2.microsoft.com/en-us/library/system.console.aspx Console Class, .NET Framework Class Library], Microsoft Corporation, 2008
{{refend}}

==External links==
* [http://www.linfo.org/standard_input.html Standard Input Definition] - by The Linux Information Project
* [http://www.linfo.org/standard_output.html Standard Output Definition] - by The Linux Information Project
* [http://www.linfo.org/standard_error.html Standard Error Definition] - by The Linux Information Project

{{DEFAULTSORT:Standard Streams}}
[[Category:Unix]]