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

Ulm's Oberon Library:
UnixMappedFiles

NAME

UnixMappedFiles - mapping of files into virtual memory

SYNOPSIS

CONST read = UnixFiles.read;
CONST write = UnixFiles.write;
CONST rdwr = UnixFiles.rdwr;
TYPE Mode = SHORTINT; (* read..rdwr *)



CONST illegalMode = 0;
CONST posOutOfRange = 1;
CONST beyondEndOfStream = 2;
CONST invalidRange = 3;
CONST errors = 4;
TYPE ErrorCode = SHORTINT; (* illegalMode..beyondEndOfStream *)
TYPE ErrorEvent = POINTER TO ErrorEventRec;
TYPE ErrorEventRec =
   RECORD
      (Events.EventRec)
      errorcode: ErrorCode;
   END;
VAR error: Events.EventType;
VAR errormsg: ARRAY errors OF Events.Message;



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

DESCRIPTION

UnixMappedFiles allows to map a file or a memory object (in the sense of mmap(2)) into virtual memory for faster access than traditional i/o operations. Note, however, that speed improvements are achieved for larger files only because of the greater overhead at opening time. Unlike the streams of UnixFiles, streams of UnixMappedFiles can neither shrink (i.e. Streams.Trunc is not supported), nor be extended. UnixMappedFiles supports SubStreams by a specific implementation.

Open maps the given filename into virtual memory and returns a stream for it. OpenFd takes the given file descriptor fd as memory object (must be valid for mmap(2)) and maps the subrange [offset, offset+length) into memory. Independent from offset, valid positions of the stream returned range from 0 to length.

DIAGNOSTICS

Many errors may be returned by the underlying modules Memory, SysMemory, and SysIO. Following error events may be generated by UnixMappedFiles:

illegalMode: An invalid mode (neither read, write, nor rdwr) was given to Open or OpenFd.
posOutOfRange: Seek operations outside the valid range from 0 to length are not valid.
beyondEndOfStream: A write operation was attempted beyond the stream length. In this case, even a partial write will not be done, and 0 or FALSE will be returned instead.
invalidRange: This error will be returned on creation of substreams with a range which is not inside [0..length].

An assertion of OpenFd checks offset and length for being non-negative.

BUGS

Note that the address space occupied by the mapped file can be regained by Streams.Close only and never due to the garbage collector (see SysStorage).

Edited by: borchert, last change: 1996/12/06, revision: 1.1, converted to HTML: 1997/04/28