Oberon || Library || Module Index || Search Engine || Definition || Module

Ulm's Oberon Library:
UnixFiles

NAME

UnixFiles - stream implementation for UNIX files

SYNOPSIS

CONST illegalMode = 0; (* mode doesn't equal one of legal modes given below *)
CONST invalidFd = 1; (* invalid file descriptor given to OpenFd *)
CONST errorcodes = 2;
TYPE ErrorCode = SHORTINT;
TYPE ErrorEvent = POINTER TO ErrorEventRec;
TYPE ErrorEventRec =
   RECORD
      (Events.EventRec)
      errorcode: ErrorCode;
   END;
VAR error: Events.EventType;
VAR errormsg: ARRAY errorcodes OF Events.Message;



CONST read = 0; write = 1; rdwr = 2; create = 4; condcreate = 8;
TYPE Mode = SHORTINT; (* read, write, rdwr,
                         read+create, write+create, rdwr+create,
                         read+condcreate, write+condcreate, rdwr+condcreate
                      *)
TYPE Stream = POINTER TO StreamRec;
TYPE StreamRec =
   RECORD
      (Streams.StreamRec)
      file: SysTypes.File; (* readonly *)
      interrupted: BOOLEAN; (* EINTR for last operation? *)
      retry: BOOLEAN; (* retry on interrupts? *)
   END;



PROCEDURE Open(VAR s: Streams.Stream; filename: ARRAY OF CHAR;
               mode: Mode; bufmode: Streams.BufMode;
               errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE OpenFd(VAR s: Streams.Stream; fd: SysTypes.File;
                 mode: Mode; bufmode: Streams.BufMode;
                 errors: RelatedEvents.Object) : BOOLEAN;

DESCRIPTION

UnixFiles provides a stream interface to UNIX files and file descriptors. The stream implementation supports the messages of StreamConditions. Open opens the given 0X-terminated filename for access mode mode. Valid accessing modes are read (read-only access), write (write-only access) and rdwr (read and write access). create, if added to mode, causes filename to be created (or to be truncated if filename exists already). Alternatively, condcreate may be added to mode which only causes filename to be created when it doesn't exist.

The buffering mode bufmode should be one of Streams.onebuf (normal buffering), Streams.bufpool (buffer cache), Streams.nobuf (unbuffered and thus very inefficient), and Streams.linebuf (suitable for line oriented terminal input and output). OpenFd opens a stream for a given file descriptor. The mode of the stream must be compatible to the mode of fd. Streams returned by Open and OpenFd are of type UnixFiles.Stream.

UnixFiles connects the standard streams Streams.stdin, Streams.stdout, and Streams.stderr to the file descriptors 0, 1, and 2 during initialization. The buffering mode of Streams.stdin and Streams.stdout is Streams.linebuf in case of terminal devices and Streams.onebuf for all other files. Streams.stderr is unbuffered. The access mode is rdwr for Streams.stdin and Streams.stdout and write for Streams.stderr.

DIAGNOSTICS

Open and OpenFd pass the errors parameter together with an error event to RelatedEvents in case of errors. Further, they return FALSE on failure. Following errors are generated by UnixFiles itself:

illegalMode: An unknown mode was given to Open or OpenFd. Note that OpenFd doesn't accept the modifiers create or condcreate.
invalidFd: OpenFd checks the given file descriptor for validity by executing an stat(2) system call and returns this error on failure.

Errors during the access of the stream are converted into events of RelatedEvents. By default, these events are being queued.

UnixFiles uses some interruptible system calls. By default, operations are retried in case of interruptions. Optionally, the retry field may be set to FALSE. In this case interruptions may lead to error events. The interrupt field indicates whether the last operation was interrupted or not.

BUGS

Some UNIX versions offer an append mode: each write access is appended to the file independent of the current position. UnixFiles cannot support this access mode on base of Streams because implicit position changes would clash with the buffering system.

UnixFiles checks the opened file for being seekable. In case of special devices this cannot be examined in all cases without trying a seek operation. This, however, is not done to avoid unnecessary error events.

Edited by: borchert, last change: 2003/07/10, revision: 1.10, converted to HTML: 2003/07/10