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.
SEE ALSO
- Memory
-
address space management
- SubStreams
-
streams representing intervals of other streams
- Streams
-
general stream operations
- SysMemory
-
interface to mmap(2) and related calls
- UnixFiles
-
more general interface to UNIX files
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
Oberon ||
Library ||
Module Index ||
Search Engine ||
Definition ||
Module