The Standard ML Basis Library


The IO structure

The IO structure contains exception constructors common to all the input/output structures and functors.


Synopsis

signature IO
structure IO : IO

Interface

exception Io of {name : string, function : string, cause : exn}
exception BlockingNotSupported
exception NonblockingNotSupported
exception RandomAccessNotSupported
exception TerminatedStream
exception ClosedStream
datatype buffer_mode = NO_BUF | LINE_BUF | BLOCK_BUF

Description

exception Io
is the principal exception raised when an error occurs in the I/O subsystem. The components of Io are:
name
The name component of the reader or writer.
function
The name of the STREAM_IO function raising the exception
cause
The underlying exception raised by the reader or writer, or detected at the stream I/O level.

Some of the standard causes are:

The cause field of Io is not limited to these particular exceptions. Users who create their own readers or writers may raise any exception they like, which will be reported as the cause field of the resulting Io exception.

exception BlockingNotSupported
used in the output, outputSubstr, output1 and flushOut I/O operations if the underlying writer does not support blocking writes; or in the input, inputN and input1 I/O operations if the underlying reader does not support blocking reads. It should never be raised within the I/O system; it should only be used in the cause field of an Io exception.

exception NonblockingNotSupported
used by the canInput I/O operation if the underlying stream does not support non-blocking input. It should never be raised within the I/O system; it should only be used in the cause field of an Io exception.

exception RandomAccessNotSupported
used by the STREAM_IO position operations to indicate that random access operations are not supported by the underlying device.

exception TerminatedStream
used by the setPosIn I/O operation if the underlying stream is terminated. It should never be raised within the I/O system; it should only be used in the cause field of an Io exception.

exception ClosedStream
used by the output I/O operations if the underlying stream is closed. This exception is actually raised by the reader or writer. It should never be raised within the I/O system; it should only be used in the cause field of an Io exception.

datatype buffer_mode
specify the type of buffering used on output streams.


Discussion

Lower-level imperative, stream and primitive I/O modules will never raise a bare TerminatedStream, BlockingNotSupported, NonblockingNotSupported or ClosedStream exception; these exceptions are only used in the cause field of the Io exception. However, any module may raise Subscript directly if given ill-formed arguments, or may raise Io with Subscript as the cause.

It is possible that multiple error conditions hold when an IO function is called. For example, a random access call may be made on a closed stream corresponding to a device that does not support random access. The cause reported in the generated Io exception is system-dependent.

See Also

TextIO, BinIO, IMPERATIVE_IO, STREAM_IO, PRIM_IO

[ INDEX | TOP | Parent | Root ]

Last Modified January 21, 1997
Comments to John Reppy.
Copyright © 1997 Bell Labs, Lucent Technologies