Module Interface StdChannels

SUMMARY: MODULE | CLASS | TYPE | PROC | VAR | CONST | DETAIL: TYPE | PROC | VAR | CONST

# StdChannels

Standard channels corresponding to the the standard file descriptors ``stdin`', ``stdout`', ``stderr`', and the pseudo channel ``/dev/null`'.

Standard channels do not have to be opened by a client program since they are already open and ready for use. Under some operating system they may be connected to sources and destinations specified before the program is run, while on a stand-alone system they may be connected to a console terminal.

The standard channels (stdin, stdout, stderr) should never be closed and the values used to identify standard channels should be constant throughout the execution of the program.

### Import List

        Channel
        Time

Class List
NullChannel |
Writer |

Class Summary: NullChannel [Detail]
      +---Channel.Channel
           |
           +--StdChannels.NullChannel
Inherited Fields
From Channel.Channel: open, readable, res, writable
Method Summary
Close() Flushes all buffers associated with ch, closes the channel, and frees all system resources allocated to it.
Flush() Flushes all buffers related to this channel.
GetModTime(VAR TimeStamp) Retrieves the modification time of the data accessed by the given channel.
Length(): LONGINT Result is the number of bytes of data that this channel refers to.
NewReader(): Reader Attaches a new reader to the channel ch.
NewWriter(): Writer Attaches a new writer to the channel ch.
Inherited Methods
From Channel.Channel: ClearError, Close, Flush, GetModTime, Length, NewReader, NewWriter

Class Summary: Writer [Detail]
      +---Channel.Writer
           |
           +--StdChannels.Writer
Inherited Fields
From Channel.Writer: base, bytesWritten, positionable, res
Method Summary
Pos(): LONGINT Returns the current writing position associated with the writer w in channel w.base, i.e.
SetPos(LONGINT) Sets the writing position to newPos.
WriteByte(BYTE) Writes a single byte x to the channel w.base at the writing position associated with w.
WriteBytes(ARRAY OF BYTE, LONGINT, LONGINT) Writes n bytes from x, starting at position start, to the channel w.base at the writing position associated with w.
Inherited Methods
From Channel.Writer: ClearError, Pos, SetPos, WriteByte, WriteBytes

Variable Summary
null-: NullChannel Null channel.
stderr-: Channel Standard error output.
stdin-: Channel Standard input.
stdout-: Channel Standard output.

Class Detail: NullChannel

Method Detail

### Close

    PROCEDURE (ch: NullChannel) Close()

> Flushes all buffers associated with ch, closes the channel, and frees all system resources allocated to it. This invalidates all riders attached to ch, and they can't be used further. On success, i.e. if all read and write operations (including flush) completed successfully, ch.res is set to done. An opened channel can only be closed once, successive calls of Channel.Close are undefined. Note that unlike the Oberon System all opened channels have to be closed explicitly. Otherwise resources allocated to them will remain blocked.

> [Description inherited from Close]

> Redefines: Close

### Flush

    PROCEDURE (ch: NullChannel) Flush()

> Flushes all buffers related to this channel. Any pending write operations are passed to the underlying OS and all buffers are marked as invalid. The next read operation will get its data directly from the channel instead of the buffer. If a writing error occurs during flushing, the field ch.res will be changed to writeError, otherwise it's assigned done. Note that you have to check the channel's Channel.res flag after an explicit flush yourself, since none of the attached writers will notice any write error in this case.

> [Description inherited from Flush]

> Redefines: Flush

### GetModTime

    PROCEDURE (ch: NullChannel) GetModTime(VAR mtime: TimeStamp)

> Retrieves the modification time of the data accessed by the given channel. If no such information is avaiblable, ch.res is set to noModTime, otherwise to done.

> [Description inherited from GetModTime]

> Redefines: GetModTime

### Length

    PROCEDURE (ch: NullChannel) Length(): LONGINT

> Result is the number of bytes of data that this channel refers to. If ch represents a file, then this value is the file's size. If ch has no fixed length (e.g. because it's interactive), the result is noLength.

> [Description inherited from Length]

> Redefines: Length

### NewReader

    PROCEDURE (ch: NullChannel) NewReader(): Reader

> Attaches a new reader to the channel ch. It is placed at the very start of the channel, and its Reader.res field is initialized to done. ch.res is set to done on success and the new reader is returned. Otherwise result is NIL and ch.res is changed to indicate the error cause. Note that always the same reader is returned if the channel does not support multiple reading positions.

> [Description inherited from NewReader]

> Redefines: NewReader

### NewWriter

    PROCEDURE (ch: NullChannel) NewWriter(): Writer

> Attaches a new writer to the channel ch. It is placed at the very start of the channel, and its Writer.res field is initialized to done. ch.res is set to done on success and the new writer is returned. Otherwise result is NIL and ch.res is changed to indicate the error cause. Note that always the same reader is returned if the channel does not support multiple writing positions.

> [Description inherited from NewWriter]

> Redefines: NewWriter

Class Detail: Writer

Method Detail

### Pos

    PROCEDURE (w: Writer) Pos(): LONGINT

> Returns the current writing position associated with the writer w in channel w.base, i.e. the index of the first byte that is written by the next call to Writer.WriteByte or Writer.WriteBytes. This procedure will return noPosition if the writer has no concept of a writing position (e.g. if it corresponds to output to terminal), otherwise the result is not negative.

> [Description inherited from Pos]

> Redefines: Pos

### SetPos

    PROCEDURE (w: Writer) SetPos(newPos: LONGINT)

> Sets the writing position to newPos. A negative value of newPos or calling this procedure for a writer that doesn't allow positioning will set `w.res' to outOfRange. A value larger than the channel's length is legal, the following write operation will fill the gap between the end of the channel and this position with zero bytes. Calls to this procedure while ``w.res # done`' will be ignored.

> [Description inherited from SetPos]

> Redefines: SetPos

### WriteByte

    PROCEDURE (w: Writer) WriteByte(x: BYTE)

> Writes a single byte x to the channel w.base at the writing position associated with w. The writing position is moved forward by one byte on success, otherwise w.res is changed to indicate the error cause. w.bytesWritten will be ``1`' on success and ``0`' on failure. Calls to this procedure while ``w.res # done`' will be ignored.

> [Description inherited from WriteByte]

> Redefines: WriteByte

### WriteBytes

    PROCEDURE (w: Writer) WriteBytes(x: ARRAY OF BYTE;
                         start: LONGINT;
                         n: LONGINT)

> Writes n bytes from x, starting at position start, to the channel w.base at the writing position associated with w. The writing position is moved forward by n bytes on success, otherwise w.res is changed to indicate the error cause. w.bytesWritten will hold the number of bytes that were actually written (being equal to n on success). Calls to this procedure while ``w.res # done`' will be ignored.

> Pre-condition: ``(n >= 0) & (0 <= start) & (start+n <= LEN (x))`'

> [Description inherited from WriteBytes]

> Redefines: WriteBytes

Variable Detail

### null

    VAR null-: NullChannel

> Null channel. Write only, accepts arbitrary input.

### stderr

    VAR stderr-: Channel

> Standard error output.

### stdin

    VAR stdin-: Channel

> Standard input.

### stdout

    VAR stdout-: Channel

> Standard output.