Modula-2 || Compiler & Tools || Library || Search Engine


Ulm's Modula-2 Library:
StdIO


NAME

StdIO - file i/o

SYNOPSIS

TYPE FILE;
TYPE MODE = (read, write, append);


VAR stdin, stdout, stderr: FILE;

PROCEDURE Fopen(VAR f: FILE; name: ARRAY OF CHAR; mode: MODE; buffered: BOOLEAN) : BOOLEAN; PROCEDURE Fdopen(VAR f: FILE; fd: CARDINAL; mode: MODE; buffered: BOOLEAN) : BOOLEAN; PROCEDURE Fclose(f: FILE) : BOOLEAN;

PROCEDURE Fread(ptr: ADDRESS; size: CARDINAL; VAR nitems: CARDINAL; f: FILE) : BOOLEAN; PROCEDURE Fwrite(ptr: ADDRESS; size: CARDINAL; VAR nitems: CARDINAL; f: FILE) : BOOLEAN;

PROCEDURE Fseek(f: FILE; offset: SystemTypes.OFF; whence: CARDINAL) : BOOLEAN; PROCEDURE Ftell(f: FILE; VAR pos: SystemTypes.OFF) : BOOLEAN;

PROCEDURE Feof(f: FILE) : BOOLEAN; PROCEDURE Ferror(f: FILE) : BOOLEAN;

PROCEDURE Fgetc(VAR ch: CHAR; f: FILE) : BOOLEAN; PROCEDURE Fputc(ch: CHAR; f: FILE) : BOOLEAN; PROCEDURE Fungetc(ch: CHAR; f: FILE) : BOOLEAN;

PROCEDURE CloseAll() : BOOLEAN; PROCEDURE Fflush(f: FILE) : BOOLEAN;

DESCRIPTION

StdIO provides a portable interface to input and output of files (much like stdio(3)). Files may be opened by Fopen or Fdopen and are later referenced by file pointers of type FILE. If the program terminates in a normal way, all open file pointers will be closed automatically (see SysExit).

StdIO offers an optional buffering mechanism to reduce the number of system calls. Buffered streams are flushed only if the buffer gets full, and by the operations Fflush and Fclose.

Three access modes are supported:
read read-only access
write write-only access.
append at opening time, a seek operation to the end of the stream is performed. Later, this mode behaves like write.

There are three normally open streams associated with the standard open files:

stdin standard input file
stdout standard output file
stderr standard error file

Fopen opens the file named by name and associates a stream with it; f identifies the stream in subsequent operations. If write is given as access mode, filename will be created if it does not exist already and truncated to zero length, otherwise. Alternatively, the access mode append may be used which does not truncate filename if it exists already.

Fdopen associates a stream with a file descriptor obtained from SysOpen, SysDup, SysCreat, or SysPipe. The mode of the stream must agree with the mode of the open file.

Fclose causes any buffers for the named stream to be emptied, and the file to be closed.

Fread reads, into a block beginning at ptr, nitems of data of the type of ptr with size size. Nitems gives back the number of items actually read.

Fwrite appends at most nitems of data of the type of ptr with size size beginning at ptr to the named output stream. Nitems gives back the number of items actually written.

Fseek sets the position of the next input or output operation on the stream. The new position is at the signed distance offset bytes from the beginning, the current position, or the end of the file, according as whence has the value 0, 1, or 2.

Ftell sets pos to the current position.

Feof returns TRUE when end of file is read on the named input stream, otherwise FALSE.

Ferror returns TRUE when an error has occurred reading or writing the named stream, otherwise FALSE. The error indication lasts until the stream is closed.

Fgetc sets ch to the next character of the input stream.

Fputc appends the character ch at the stream f.

Fungetc pushes ch back to the input stream f. Note that multiple invocations of Fungetc without intermediate read operations are not guaranteed to work.

CloseAll closes all open streams. This may be useful for child processes and is automatically called during process termination (see SysExit).

Fflush causes any buffered data for the named output stream to be written to that file. The stream remains open.

The streams stdin, stdout, stderr may be reopened:

IF NOT Fclose(stdin) OR
   NOT Fopen(stdin, file, mode, buffered) THEN
   (* error case *)
END;

SEE ALSO

InOut, FtdIO

DIAGNOSTICS

All routines return FALSE in error case.

BUGS

The access modes conform to the equally named modes of the stdio(3) of UNIX Edition VII which are quite different from newer variants:

StdIO assumes that there are no differences between text and binary files. We regard this as feature :-)


Edited by: borchert, last change: 1997/02/25, revision: 1.2, converted to HTML: 1999/01/26

Modula-2 || Compiler & Tools || Library || Search Engine