Module Interface IO:FileChannel

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

# IO:FileChannel

### Import List

        IO
        IO:Buffer

Class List
Channel |

Class Summary: Channel [Detail]
      +---IO.Channel
           |
           +---IO.ByteChannel
                |
                +--IO:FileChannel.Channel
Inherited Fields
From IO.Channel: readyOps
Constructor Summary
OpenUnbuffered(STRING, SET): Channel
Method Summary
Close() Remove the file if the channel was opened with tmpFile.
CloseAndRegister() Like Channel.Close, but register the channel's target with its naming service once done.
FileDescriptor(): FileDescriptor Return the file descriptor of the channel.
Length(): LONGINT
Read(VAR ARRAY OF BYTE, LONGINT, LONGINT): LONGINT Read a sequence of bytes from the channel into the buffer.
SetBlocking(BOOLEAN) Change the channel's blocking mode.
SetPos(LONGINT) Change the channels position to pos.
Write(ARRAY OF BYTE, LONGINT, LONGINT): LONGINT Write a sequence of bytes to this channel from the buffer.
Inherited Methods
From IO.Channel: Close, CloseAndRegister, FileDescriptor, KeyForSelector, RegisterWithSelector, SetBlocking, SetPos From IO.ByteChannel: Flush, Read, TransferTo, Write

Procedure Summary
Open(STRING, SET): Channel

Constant Summary
append Open file in "append" mode.
create Create file if it does not exist.
exclusive If both create and exclusive are set, then Open fails if the specified file already exists.
read Open file for reading.
tmpFile A file opened with this flag is created with some unused file name, and is renamed to the file name passed to Open when Channel.CloseAndRegister is called.
truncate Truncate file to zero length if it exists.
write Open file for writing.

Class Detail: Channel

Constructor Detail

### OpenUnbuffered

    PROCEDURE OpenUnbuffered(file: STRING;
                             mode: SET): Channel
      RAISES Error;

Method Detail

### Close

    PROCEDURE (ch: Channel) Close()
      RAISES Error;

> Remove the file if the channel was opened with tmpFile.

> Redefines: Close, Close

### CloseAndRegister

    PROCEDURE (ch: Channel) CloseAndRegister()
      RAISES Error;

> Like Channel.Close, but register the channel's target with its naming service once done. Right now, only IO:FileChannel supports this feature; see IO:FileChannel.tmpFile for details. By default, this method simply calls Channel.Close.

> [Description inherited from CloseAndRegister]

> Redefines: CloseAndRegister, CloseAndRegister

### FileDescriptor

    PROCEDURE (ch: Channel) FileDescriptor(): FileDescriptor

> Return the file descriptor of the channel. This is the integer number that is used to identify the channel on the level of the C library. If the channel is not associated with a file descriptor, result is ``-1`'.

> [Description inherited from FileDescriptor]

> Redefines: FileDescriptor, FileDescriptor

### Length

    PROCEDURE (ch: Channel) Length(): LONGINT
      RAISES Error;

### Read

    PROCEDURE (ch: Channel) Read(VAR buffer: ARRAY OF BYTE;
                   start: LONGINT;
                   length: LONGINT): LONGINT
      RAISES Error;

> Read a sequence of bytes from the channel into the buffer.

> An attempt is made to read up to length bytes from the channel. The bytes are written to buffer, starting at position start. Result is the number of bytes actually read, or ``-1`' if the read position is at the end of the channel, and length is not zero.

> A read operation might not read length bytes, and in fact it might not read any bytes at all. Whether or not it does so depends upon the nature and state of the channel. A socket channel in non-blocking mode, for example, cannot read any more bytes than are immediately available from the socket's input buffer; similarly, a file channel cannot read any more bytes than remain in the file. It is guaranteed, however, that if a channel is in blocking mode and there is at least one byte remaining in the buffer then this method will block until at least one byte is read.

> Pre-condition: ``0 <= start <= start+length <= LEN(buffer)`' and ``length >= 0`'.

> [Description inherited from Read]

> Redefines: Read

### SetBlocking

    PROCEDURE (ch: Channel) SetBlocking(block: BOOLEAN)
      RAISES Error;

> Change the channel's blocking mode. Channels typically default to blocking mode on creation.

> If a channel does not support non-blocking operation, then any call to this method is ignored. Rider implementations from IO:BinaryRider and IO:TextRider only work with blocking channels.

> [Description inherited from SetBlocking]

> Redefines: SetBlocking, SetBlocking

### SetPos

    PROCEDURE (ch: Channel) SetPos(pos: LONGINT)
      RAISES Error;

> Change the channels position to pos.

> [Description inherited from SetPos]

> Redefines: SetPos, SetPos

### Write

    PROCEDURE (ch: Channel) Write(buffer: ARRAY OF BYTE;
                    start: LONGINT;
                    length: LONGINT): LONGINT
      RAISES Error;

> Write a sequence of bytes to this channel from the buffer.

> An attempt is made to write up to length bytes to the channel. The bytes are taken from buffer, beginning at position start.

> A write operation can return after writing less than length bytes. That is, some types of channels, depending upon their state, may write only some of the bytes or possibly none at all. A socket channel in non-blocking mode, for example, cannot write any more bytes than are free in the socket's output buffer. Result is the number of bytes actually written.

> Pre-condition: ``0 <= start <= start+length <= LEN(buffer)`' and ``length >= 0`'.

> [Description inherited from Write]

> Redefines: Write

Procedure Detail

### Open

    PROCEDURE Open(file: STRING;
                   mode: SET): Channel
      RAISES Error;

Constant Detail

### append

    CONST append

> Open file in "append" mode. All data written to this file is added to its end.

### create

    CONST create

> Create file if it does not exist.

### exclusive

    CONST exclusive

> If both create and exclusive are set, then Open fails if the specified file already exists. This flag has no effect if tmpFile is set.

### read

    CONST read

> Open file for reading.

### tmpFile

    CONST tmpFile

> A file opened with this flag is created with some unused file name, and is renamed to the file name passed to Open when Channel.CloseAndRegister is called. If it is closed with Channel.Close, then the temporary file is removed. If the program terminates, an attempt is made to close and remove all tmpFile files that are still open.

### truncate

    CONST truncate

> Truncate file to zero length if it exists. On some systems, for this to work write must be set as well.

### write

    CONST write

> Open file for writing.