The REXX I/O Model

Standard REXX allows files to be accessed using the seven functions
charin, charout, chars, linein, lineout, lines, stream.  This REXX
version has fourteen I/O functions in total; the others remain for
backward compatibility but may be removed in future because their
functionality is covered by the stream() function.

Each I/O function may accept a stream name as a parameter.  Usually,
the stream name is the path name of a file which will be accessed -
though other meanings may be given to streams by the "open", "popen"
and "stream" functions.

Associated with each currently accessed stream is a read pointer and a
write pointer.  Characters or lines can be read from the file at the
position indicated by the read pointer, or they may be written to the
file at the position indicated by the write pointer.  In each case the
pointer is updated to indicate the new file position after the read or
write.  The file pointers may be also moved explicitly by various
functions.  Note that the read and write pointers will in general be
different, in contrast to the usual Unix file pointer.

Each file is opened by REXX when it is first accessed, and closed when
REXX exits.  Therefore files need not be opened and closed explicitly,
though in this version functions are provided for that purpose.  If
many files are to be accessed, it is advisable to close files which are
no longer needed because otherwise the Unix error "Too many open files"
may result.

Two kinds of stream exist: persistent and transient.  A persistent
stream is one which refers to a regular file, whereas a transient
stream is any other kind.  In particular, ttys and pipes are transient
streams.  The main difference between the two is that the read and write
pointers of a permanent stream may be repositioned, whereas those of a
transient stream may not.

If a function encounters an I/O error and is unable to perform its
function, then it will raise the NOTREADY condition.  This condition
will be ignored unless it is trapped by SIGNAL ON or CALL ON.  However,
in all cases it is possible to examine the most recent I/O error using
the STREAM() function.

The three streams "stdin", "stdout" and "stderr" are already open when
REXX starts up.  They may be used just as any other files, but they are
also accessed by instructions such as "say" and "pull", and by Unix
commands.  Because of this, REXX/imc only guarantees to be well-behaved
if stdin is never written to, and stdout and stderr are never read from.

The standard I/O functions CHARIN, CHAROUT, CHARS, LINEIN, LINEOUT,
LINES and STREAM all accept the empty string as a stream name.  This is
interpreted identically to the word "stdin", except in the cases of
CHAROUT and LINEOUT, in which it means "stdout".  However, the empty
string may not be used in the STREAM function in conjunction with the
the stream commands open, fdopen, popen or flush.

The I/O functions, and their descriptions, follow.  Note that no
"stream" or "file" name may contain a NUL character (i.e. "00"x).