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

Ulm's Oberon Library:
MemStreams

NAME

MemStreams - streams representing a memory area

SYNOPSIS

CONST read = 0; write = 1; rdwr = 2;
TYPE Mode = SHORTINT; (* read..rdwr *)



CONST beyondEndOfStream = 0;
CONST posOutOfRange = 1;
CONST invalidRange = 2;
CONST errors = 3;
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;
               addr: Types.Address; length: Types.Size;
               mode: Mode);



PROCEDURE OpenU(VAR s: Streams.Stream;
                addr: Types.UntracedAddress; length: Types.Size;
                mode: Mode);

DESCRIPTION

MemStreams allows to access a memory area by stream operations. Memory streams may be created for any allocated area of the virtual address space of the current process. Areas which are under the control of the garbage collector (see SysStorage) are to be passed to Open, otherwise OpenU is to be taken for untraced addresses.

MemStreams may be particularly useful for other stream implementations which keep their stream contents in-memory in a contiguous buffer as substream implementation (see SubStreams). MemStreams itself supports SubStreams as well.

It is in the responsibility of the stream creator to assure that the validity of the memory area is associated with the validity of the stream, i.e. if the memory area should become deallocated (no matter by which method), the stream should terminate (see Resources). Note that this link will be established automatically if MemStreams is used as a substream implementation (see SubStreams and Forwarders).

Besides the read and write operations, seek and tell, also trunc operations are permitted which allow to reduce the length of the stream.

DIAGNOSTICS

Following error events may be generated by MemStreams:
posOutOfRange
Seek operations outside the valid range from 0 to length are not valid. Trunc operations are not permitted which are outside the valid range or which exclude the current position.
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].

Note that passing an invalid mode to Open or OpenU will result in a runtime error.

SEE ALSO

Forwarders
filter objects
Resources
termination of objects and inter-object dependencies
Streams
general stream operations
SubStreams
general interface for substreams
Types
base types including address types
Edited by: borchert, last change: 2004/02/19, revision: 1.2, converted to HTML: 2004/02/19

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