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

Ulm's Oberon Library:
UnixArchives

NAME

UnixArchives - stream input from archives

SYNOPSIS

CONST arnamelength = 14;



TYPE MemberName = ARRAY arnamelength+1 OF CHAR;
TYPE ArchiveHeader =
   RECORD
      name: MemberName;      (* name of archive member *)
      date: SysTypes.Time;   (* in seconds since Jan 1, 1970 *)
      uid, gid: INTEGER;     (* user and group id *)
      mode: SET;             (* protection mode, see HREF="SysStat.html">SysStat *)
      size: SysTypes.Offset; (* size in bytes *)
   END;
TYPE Archive = POINTER TO ArchiveRec;
TYPE ArchiveRec =
   RECORD
      (Streams.StreamRec)
      (* readonly stat information of current archive member *)
      header: ArchiveHeader;
   END;



(* error codes *)
CONST notAnArchiveFile = 0;     (* magic header not found *)
CONST corruptedArchive = 1;     (* corrupted archive file *)
CONST memberNotFound = 2;       (* archive member file not found *)
CONST outOfRange = 3;           (* seek failure: position out of range *)
CONST readFailed = 4;           (* unexpected read failure *)
CONST seekFailed = 5;           (* unexpected seek failure *)
CONST tellFailed = 6;           (* unexpected tell failure *)
CONST errorcodes = 7;           (* number of error codes *)
TYPE ErrorCode = SHORTINT;      (* 0..errorcodes-1 *)
TYPE Event = POINTER TO EventRec;
TYPE EventRec =
   RECORD
      (Events.EventRec)
      stream: Archive;
      code: ErrorCode;
   END;
VAR errormsg: ARRAY errorcodes OF Events.Message;
VAR streamError: Events.EventType;



PROCEDURE Open(VAR archive: Streams.Stream;
               arname: ARRAY OF CHAR;
               membername: ARRAY OF CHAR;
               errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE Reopen(archive: Streams.Stream;
                 membername: ARRAY OF CHAR) : BOOLEAN;

DESCRIPTION

UnixArchives supports stream input from archives in common archive file format. This archive file format is supported by UNIX System V and BSD systems. The minor difference between UNIX System V and BSD systems (filenames are "/"-terminated in UNIX System V) is tolerated. Archives from UNIX Edition VII cannot be read.

Open opens arname(membername) for reading. If membername equals "", the first member of the archive will be opened for reading. Open fails if arname cannot be opened or if membername cannot be found (or if the archive is empty). Reopen may be called to read another archive member of an already opened archive stream. If membername equals "", the next member of the archive will be opened for reading. Reopen fails if membername cannot be found or at the end of the archive. It is important to note that Reopen does not close the stream in case of failures.

UnixArchives maintains an incremental internal member list of the archive which avoids rescanning of the archive in case of Reopen. The main goal of UnixArchives is to support reading of REF and SYM archive files. In this case it is very useful to maintain a list of archives which are opened with membername "" during initialization time. When an archive member is sought for, the list of archives can be examined until the first Reopen succeeds.

EXAMPLE

Print all archive member names of a given archive:

PROCEDURE ListArchive(archive: ARRAY OF CHAR);
   VAR
      ar: Streams.Stream;
BEGIN
   IF UnixArchives.Open(ar, archive, "", NIL) THEN
      REPEAT
         Write.Line(ar.header.name);
      UNTIL ~UnixArchives.Reopen(ar, "");
      Streams.Release(ar);
   END;
END ListArchive;

DIAGNOSTICS

Open passes the errors parameter together with an error event of type streamError to RelatedEvents in case of errors. Further, Open returns FALSE on failure.

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

Error events which are generated by UnixArchives contain one of the error codes following:

notAnArchiveFile: The magic string of archives at the beginning of the file has not been found.
corruptedArchive: An archive member header cannot be read or is corrupted.
memberNotFound: The given member name (# "") cannot be found in the given archive.
outOfRange: Seek position is negative or beyond the end of the archive member.
readFailed: A read operation failed unexpectantly.
seekFailed: A seek operation failed unexpectantly.
tellFailed: A tell operation failed unexpectantly.

BUGS

The BSD version of archive files uses trailing blanks as filename delimiter. Thus filenames with trailing blanks are extracted without trailing blanks.

Archive member names are restricted to 14 characters even on file systems which support longer names.

Edited by: borchert, last change: 2005/03/07, revision: 1.6, converted to HTML: 2005/03/07