Module Interface PosixFileDescr

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

# PosixFileDescr

### Import List

        C
        Channel
        Msg
        Time

Class List
Channel |
ErrorContext |
Reader |
Writer |

Class Summary: Channel [Detail]
      +---Channel.Channel
           |
           +--PosixFileDescr.Channel
Field Summary
fd-: int
Inherited Fields
From Channel.Channel: open, readable, res, writable
Constructor Summary
Init(Channel, FileDescriptor, SHORTINT) Attach channel ch to file descriptor fd.
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: ErrorContext [Detail]
      +---Msg.Context
           |
           +---Channel.ErrorContext
                |
                +--PosixFileDescr.ErrorContext
Inherited Fields
From Msg.Context: id
Method Summary
GetTemplate(Msg, VAR LString) Translates this module's error codes into strings.
Inherited Methods
From Channel.ErrorContext: GetTemplate

Class Summary: Reader [Detail]
      +---Channel.Reader
           |
           +--PosixFileDescr.Reader
Inherited Fields
From Channel.Reader: base, bytesRead, positionable, res
Constructor Summary
InitReader(Reader, Channel)
Method Summary
Available(): LONGINT Returns the number of bytes available for the next reading operation.
Pos(): LONGINT Returns the current reading position associated with the reader r in channel r.base, i.e.
ReadByte(VAR BYTE) Reads a single byte from the channel r.base at the reading position associated with r and places it in x.
ReadBytes(VAR ARRAY OF BYTE, LONGINT, LONGINT) Reads n bytes from the channel r.base at the reading position associated with r and places them in x, starting at index start.
SetPos(LONGINT) Sets the reading position to newPos.
Inherited Methods
From Channel.Reader: Available, ClearError, Pos, ReadByte, ReadBytes, SetPos

Class Summary: Writer [Detail]
      +---Channel.Writer
           |
           +--PosixFileDescr.Writer
Inherited Fields
From Channel.Writer: base, bytesWritten, positionable, res
Constructor Summary
InitWriter(Writer, Channel)
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

Type Summary
[FileDescriptor] = int
Result = Result

Procedure Summary
Truncate(Writer, LONGINT) Causes the file associated with w to have the specified length.

Constant Summary
blockBuffer
channelClosed
closeError
done
freeErrorCode
invalidChannel
invalidFormat
lineBuffer
noBuffer
noLength
noModTime
noPosition
noReadAccess
noRoom
noTmpName
noWriteAccess
outOfRange
readAfterEnd
readError
readOnly
readWrite
stderrFileno
stdinFileno
stdoutFileno
writeError
writeOnly

Class Detail: Channel

Field Detail

### fd

    FIELD fd-: int

Constructor Detail

### Init

    PROCEDURE Init(ch: Channel;
                   fd: FileDescriptor;
                   mode: SHORTINT)

> Attach channel ch to file descriptor fd. mode specifies whether the descriptor should be treated as read only, write only, or read/write. It's a bad idea to pass a duplicated file descriptor to fd, all kinds of unexpected things might happen.

Method Detail

### Close

    PROCEDURE (ch: Channel) 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: Channel) 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: Channel) 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: Channel) 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: Channel) 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: Channel) 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: ErrorContext

Method Detail

### GetTemplate

    PROCEDURE (context: ErrorContext) GetTemplate(msg: Msg;
                          VAR templ: LString)

> Translates this module's error codes into strings. The string usually contains a short error description, possibly followed by some attributes to provide additional information for the problem.

> The method should not be called directly by the user. It is invoked by ``res.GetText()`' or ``res.GetLText`'.

> [Description inherited from GetTemplate]

> Redefines: GetTemplate, GetTemplate

Class Detail: Reader

Constructor Detail

### InitReader

    PROCEDURE InitReader(r: Reader;
                         ch: Channel)

Method Detail

### Available

    PROCEDURE (r: Reader) Available(): LONGINT

> Returns the number of bytes available for the next reading operation. For a file this is the length of the channel r.base minus the current reading position, for an sequential channel (or a channel designed to handle slow transfer rates) this is the number of bytes that can be accessed without additional waiting. The result is ``-1`' if Channel.Close was called for the channel, or no more byte are available and the remote end of the channel has been closed. Note that the number of bytes returned is always a lower approximation of the number that could be read at once; for some channels or systems it might be as low as ``1`' even if tons of bytes are waiting to be processed.

> [Description inherited from Available]

> Redefines: Available

### Pos

    PROCEDURE (r: Reader) Pos(): LONGINT

> Returns the current reading position associated with the reader r in channel r.base, i.e. the index of the first byte that is read by the next call to Reader.ReadByte resp. Reader.ReadBytes. This procedure will return noPosition if the reader has no concept of a reading position (e.g. if it corresponds to input from keyboard), otherwise the result is not negative.

> [Description inherited from Pos]

> Redefines: Pos

### ReadByte

    PROCEDURE (r: Reader) ReadByte(VAR x: BYTE)

> Reads a single byte from the channel r.base at the reading position associated with r and places it in x. The reading position is moved forward by one byte on success, otherwise r.res is changed to indicate the error cause. Calling this procedure with the reader r placed at the end (or beyond the end) of the channel will set r.res to readAfterEnd. r.bytesRead will be ``1`' on success and ``0`' on failure. Calls to this procedure while ``r.res # done`' will be ignored.

> [Description inherited from ReadByte]

> Redefines: ReadByte

### ReadBytes

    PROCEDURE (r: Reader) ReadBytes(VAR x: ARRAY OF BYTE;
                        start: LONGINT;
                        n: LONGINT)

> Reads n bytes from the channel r.base at the reading position associated with r and places them in x, starting at index start. The reading position is moved forward by n bytes on success, otherwise r.res is changed to indicate the error cause. Calling this procedure with the reader r placed less than n bytes before the end of the channel will will set r.res to readAfterEnd. r.bytesRead will hold the number of bytes that were actually read (being equal to n on success). Calls to this procedure while ``r.res # done`' will be ignored.

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

> [Description inherited from ReadBytes]

> Redefines: ReadBytes

### SetPos

    PROCEDURE (r: Reader) SetPos(newPos: LONGINT)

> Sets the reading position to newPos. A negative value of newPos or calling this procedure for a reader that doesn't allow positioning will set r.res to outOfRange. A value larger than the channel's length is legal, but the following read operation will most likely fail with an readAfterEnd error unless the channel has grown beyond this position in the meantime. Calls to this procedure while ``r.res # done`' will be ignored, in particular a call with ``r.res.code = readAfterEnd`' error will not reset Reader.res to done.

> [Description inherited from SetPos]

> Redefines: SetPos

Class Detail: Writer

Constructor Detail

### InitWriter

    PROCEDURE InitWriter(w: Writer;
                         ch: Channel)

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

Type Detail

### FileDescriptor

    TYPE [FileDescriptor] = int

### Result

    TYPE Result = Result

Procedure Detail

### Truncate

    PROCEDURE Truncate(w: Writer;
                       newLength: LONGINT)

> Causes the file associated with w to have the specified length. If the file was previously larger than newLength, the extra data is lost. If it was previously shorter, bytes between the old and new lengths are read as zeros. The writer's position is not modified. Note: On systems that do not support shortening files directly it is implemented as a partial file copy. This procedure should always be called through Files.Writer.Truncate.

> Availability: Unix.

Constant Detail

### blockBuffer

    CONST blockBuffer

### channelClosed

    CONST channelClosed

### closeError

    CONST closeError

### done

    CONST done

### freeErrorCode

    CONST freeErrorCode

### invalidChannel

    CONST invalidChannel

### invalidFormat

    CONST invalidFormat

### lineBuffer

    CONST lineBuffer

### noBuffer

    CONST noBuffer

### noLength

    CONST noLength

### noModTime

    CONST noModTime

### noPosition

    CONST noPosition

### noReadAccess

    CONST noReadAccess

### noRoom

    CONST noRoom

### noTmpName

    CONST noTmpName

### noWriteAccess

    CONST noWriteAccess

### outOfRange

    CONST outOfRange

### readAfterEnd

    CONST readAfterEnd

### readError

    CONST readError

### readOnly

    CONST readOnly

### readWrite

    CONST readWrite

### stderrFileno

    CONST stderrFileno

### stdinFileno

    CONST stdinFileno

### stdoutFileno

    CONST stdoutFileno

### writeError

    CONST writeError

### writeOnly

    CONST writeOnly