{Begin Chapter Input/Output Functions}
{Title Input/Output Functions}
{Text

{index *PRIMARY* Input/Output functions}

This chapter describes the standard I/O functions used for reading and printing characters and Interlisp expressions on files and other streams.  First, the primitive input functions are presented, then the output functions, then functions for random-access operations (such as searching a file for a given stream, or changing the "next-character" pointer to a position in a file).  Next, the {lisp PRINTOUT} statement is documented ({PageRef Tag PRINTOUT}), which provides an easy way to write complex output operations.  Finally, read tables, used to parse characters as Interlisp expressions, are documented.



{Begin SubSec Specifying Streams for Input/Output Functions}
{Title Specifying Streams for Input/Output Functions}
{Text

Most of the input/output functions in Interlisp-D have an argument named {arg STREAM} or {arg FILE}, specifying on which open stream the function's action should occur (the name {arg FILE} is used in older functions that predate the concept of stream; the two should, however, be treated synonymously).  The value of this argument should be one of the following:

{Begin LabeledList Values of stream arg}

{Label a stream}
{Text 
An object of type {lisp STREAM}, as returned by {fn OPENSTREAM} ({PageRef Fn OPENSTREAM}) or other stream-producing functions, is always the most precise and efficient way to designate a stream argument.
}

{Label {lisp T}}
{Text 
{index *PRIMARY* Terminal streams}
{Index *PRIMARY* T (Terminal stream)}
The litatom {lisp T} designates the terminal input or output stream of the currently running process, controlling input from the keyboard and output to the display screen.  For functions where the direction (input or output) is ambiguous, {lisp T} is taken to designate the terminal output stream.  The {lisp T} streams are always open; they cannot be closed.

The terminal output stream can be set to a given window or display stream by using {fn TTYDISPLAYSTREAM} ({PageRef Fn TTYDISPLAYSTREAM}).  The terminal input stream cannot be changed.  For more information on terminal I/O, see {PageRef Term Terminal Input/Output}.

{note Terminal streams may deserve their own little extra section once we provide real fns to change them.}
}

{Label {lisp NIL}}
{Text
{index *PRIMARY* Primary streams}
{Index *PRIMARY* NIL (Primary stream)}
The litatom {lisp NIL} designates the "primary" input or output stream.  These streams are initially the same as the terminal input/output streams, but they can be changed by using the functions {fn INPUT} ({PageRef fn INPUT}) and {fn OUTPUT} ({PageRef fn OUTPUT}).

For functions where the direction (input or output) is ambiguous, e.g., {fn GETFILEPTR}, the argument {lisp NIL} is taken to mean the primary input stream, if that stream is not identical to the terminal input stream, else the primary output stream. 
}

{Label a window}
{Text 
Uses the display stream of the window ({PageRef (Window Property) DSP}).  Valid for output only.
}

{Label a file name}
{Text 
As of this writing, the name of an open file (as a litatom) can be used as a stream argument.  However, there are inefficiencies and possible future incompatibilities associated with doing so.  See page {PageRef Tag StreamFileNames} for details.
}

{End LabeledList Values of stream arg}


{FnDef {Name GETSTREAM} {Args FILE ACCESS}
{Text
Coerces the argument {arg FILE} to a stream by the above rules.  If {arg ACCESS} is {lisp INPUT}, {lisp OUTPUT}, or {lisp BOTH}, produces the stream designated by {arg FILE} that is open for {arg ACCESS}.  If {arg ACCESS}={lisp NIL}, returns a stream for {arg FILE} open for any kind of input/output (see the list above for the ambiguous cases).  If {arg FILE} does not designate a stream open in the specified mode, causes an error, {lisp FILE NOT OPEN}.{index FILE NOT OPEN Error}

{note GETSTREAM currently returns a string stream if FILE is a string, but this will undoubtedly be changed soon, right??}
}}


{FnDef {Name STREAMP} {Args X}
{Text
Returns {arg X} if {arg X} is a {lisp STREAM}, otherwise {lisp NIL}.
}}


}{End SubSec Specifying Streams for Input/Output Functions}


{Include InputFns}

{Include OutputFns}

{Include RandomIO}

{Include Printout}

{Include READFILE}

{Include ReadTables}

}{End Chapter Input/Output Functions}