# Files

Note 1: This documentation describes only the additional features of files beyond the standard channels. Please refer to Channel for the semantics of all items that are inherited from Channel without modifications.

Note 2: Most Unix systems only allow a fixed number of files (and sockets) to be open simultaneously. If this limit is reached, no new file can be opened or socket be created until an old file/socket is closed. For any POSIX compliant system at least 16 open files are supported, most implementations provide a much larger number.

### Import List

        Channel
        Msg
        PosixFileDescr
        Time

Class List
ErrorContext | This record is exported, so that extensions of File can access the error descriptions by extending ErrorContextDesc.
File |
Reader |
Writer |

Class Summary: ErrorContext [Detail]

      +---Msg.Context
           |
           +---Channel.ErrorContext
                |
                +---PosixFileDescr.ErrorContext
                     |
                     +--Files.ErrorContext

This record is exported, so that extensions of File can access the error descriptions by extending ErrorContextDesc.

Inherited Fields
From Msg.Context: id
Method Summary
GetTemplate(Msg, VAR LString) Translates this module's error codes into strings.
Inherited Methods
From PosixFileDescr.ErrorContext: GetTemplate

Class Summary: File [Detail]

      +---Channel.Channel
           |
           +---PosixFileDescr.Channel
                |
                +--Files.File

Inherited Fields
From Channel.Channel: open, readable, res, writable From PosixFileDescr.Channel: fd
Constructor Summary
New(ARRAY OF CHAR, SET, VAR Result): File Creates a new file under the given name.
Old(ARRAY OF CHAR, SET, VAR Result): File Opens an existing file.
Tmp(ARRAY OF CHAR, SET, VAR Result): File Creates a temporary file that can be registered later on.
Method Summary
Close() Flushes all buffers associated with f, closes the file, and frees all system resources allocated to it.
NewReader(): Reader Attaches a new reader to the file f.
NewWriter(): Writer Attaches a new writer to the file f.
Register() Registers the file f in the directory structure if it has been created with the Tmp procedure below.
Inherited Methods
From Channel.Channel: ClearError From PosixFileDescr.Channel: Close, Flush, GetModTime, Length, NewReader, NewWriter

Class Summary: Reader [Detail]

      +---Channel.Reader
           |
           +---PosixFileDescr.Reader
                |
                +--Files.Reader

Inherited Fields
From Channel.Reader: base, bytesRead, positionable, res
Inherited Methods
From Channel.Reader: ClearError From PosixFileDescr.Reader: Available, Pos, ReadByte, ReadBytes, SetPos

Class Summary: Writer [Detail]

      +---Channel.Writer
           |
           +---PosixFileDescr.Writer
                |
                +--Files.Writer

Inherited Fields
From Channel.Writer: base, bytesWritten, positionable, res
Method Summary
Truncate(LONGINT) Causes the file associated with w to have the specified length.
Inherited Methods
From Channel.Writer: ClearError From PosixFileDescr.Writer: Pos, SetPos, WriteByte, WriteBytes

Type Summary
Result = Result

Procedure Summary
Exists(ARRAY OF CHAR): BOOLEAN Returns TRUE if a file file exists, and FALSE otherwise.
GetModTime(ARRAY OF CHAR, VAR TimeStamp, VAR Result) Gets the modification time of the given file to mtime.
SetModTime(ARRAY OF CHAR, TimeStamp, VAR Result) Sets the modification time of the given file to mtime.

Constant Summary
accessDenied Access to the channel was denied.
anonymousFile A file can only be registered if a file name was passed to the initial call to Tmp.
channelClosed
closeError
dirWriteDenied You need to have write permission for the directory you want to add a new file to.
directoryFull The directory or the file system that would contain the new file cannot be extended, either because there is no space left or the directory has a fixed upper limit.
done
fileError Unspecified error when opening/creating a file.
invalidChannel
invalidFormat
invalidTime The time passed to procedure SetModTime is no valid time stamp.
isDirectory The ``flags`' argument specified write access, and the file is a directory.
linkLoop Too many symbolic links were resolved while trying to look up the file name.
nameTooLong Either the total length of the file name or of an individual file name component is too large.
noLength
noModTime
noPosition
noReadAccess
noRoom
noSuchFile The named file in a call to Old does not exist.
noTmpName
noWriteAccess
notDirectory A file that is referenced as a directory component of the file name exists, but is not a directory.
notOwner Only the owner of a file can change its modification time.
outOfRange
read If the file cannot be opened for reading access, then it isn't opened at all.
readAfterEnd
readError
readOnlyFileSystem The file resides on a read-only file system and it is attempted to create a new file, or to gain write access for an existing one.
tooManyFiles The process or the entire system has too many files open.
tryRead Try to open this file for reading access.
tryWrite Try to open this file for writing access.
write If the file cannot be opened for writing access, then it isn't opened at all.
writeError

Class Detail: ErrorContext

Method Detail

### GetTemplate

    PROCEDURE (context: ErrorContext) GetTemplate(msg: Msg;
                          VAR templ: LString)

> Translates this module's error codes into strings. The string usually contains a short error description, possibly followed by some attributes to provide additional information for the problem.

> The method should not be called directly by the user. It is invoked by ``res.GetText()`' or ``res.GetLText`'.

> [Description inherited from GetTemplate]

> Redefines: GetTemplate, GetTemplate, GetTemplate

Class Detail: File

Constructor Detail

### New

    PROCEDURE New(file: ARRAY OF CHAR;
                  flags: SET;
                  VAR res: Result): File

> Creates a new file under the given name. On success the new file handle is returned and res is set to done. Otherwise result is NIL and res and will indicate the problem.

> Note that in terms of the Oberon System this procedure combines the procedures ``New`' and ``Register`'.

### Old

    PROCEDURE Old(file: ARRAY OF CHAR;
                  flags: SET;
                  VAR res: Result): File

> Opens an existing file. On success the new file handle is returned and res is set to done. Otherwise result is NIL and res will indicate the problem.

### Tmp

    PROCEDURE Tmp(file: ARRAY OF CHAR;
                  flags: SET;
                  VAR res: Result): File

> Creates a temporary file that can be registered later on. On success the new file handle is returned and res is set to done. Otherwise result is NIL and res will indicate the problem.

> Temporary files are created with an empty permission list, the permissions are extended upon registration. The files are deleted if they haven't been registered and are closed or the program terminates.

> An unique temporary file name is created if the given file name is the empty string. Such a file can't be registered later. Note that some systems are said to have a very low limit for the number of temporary file names. The limit is never less than 25. To be on the safe side you should never have more than 25 anonymous temporary files open simultaneously, or check that the ``TMP_MAX`' macro in ``/usr/include/stdio.h`' is large enough for your purposes.

> With oo2c if file isn't empty, the new name is derived from the old one by appending "^", "^1", "^2", etc. in turn, until a file name is found that doesn't exist already. If such call to Tmp returns nameTooLong, then this refers to the constructed temporary name, not the one in file. This function corresponds to Oberon System's ``New`'.

Method Detail

### Close

    PROCEDURE (f: File) Close()

> Flushes all buffers associated with f, closes the file, and frees all system resources allocated to it. This invalidates all riders attached to f, they can't be used further. On success, that is, if all read and write operations (including flush) completed successfully, f.res is set to done.

> An opened file can only be closed once, successive calls of File.Close are undefined. Note that unlike the Oberon System all opened files have to be closed explicitly. Otherwise resources allocated to them will remain blocked.

> Redefines: Close, Close

### NewReader

    PROCEDURE (f: File) NewReader(): Reader

> Attaches a new reader to the file f. It is placed at the very start of the file, and its Reader.res field is initialized to done. f.res is set to done on success and the new reader is returned. Otherwise result is NIL and f.res is changed to indicate the error cause.

> Redefines: NewReader, NewReader

### NewWriter

    PROCEDURE (f: File) NewWriter(): Writer

> Attaches a new writer to the file f. It is placed at the very start of the file, and its Writer.res field is initialized to done. f.res is set to done on success and the new writer is returned. Otherwise result is NIL and f.res is changed to indicate the error cause.

> Redefines: NewWriter, NewWriter

### Register

    PROCEDURE (f: File) Register()

> Registers the file f in the directory structure if it has been created with the Tmp procedure below. Registration happens atomically. That is, it is guaranteed that any previously existing file is replaced by the newly registered one without any "in between" state. If the operation is interrupted, then either the old file still exists on the file system, or it has been replaced completely by the new one.

> Calling Tmp and File.Register successively has the same effect as calling New. Calling this procedure has no effect if the file f has been created with New or has been registered previously. Registration fails with an anonymousFile error if it was created by calling Tmp with an empty file name, and with a channelClosed error if f is closed.

Class Detail: Reader

Class Detail: Writer

Method Detail

### Truncate

    PROCEDURE (w: Writer) Truncate(newLength: LONGINT)

> Causes the file associated with w to have the specified length. If the file was previously larger than newLength, then the extra data is lost. If it was previously shorter, bytes between the old and new lengths are read as zeros. The writer's position is not modified. Note: On systems that do not support shortening files directly it is implemented as a partial file copy.

Type Detail

### Result

    TYPE Result = Result

Procedure Detail

### Exists

    PROCEDURE Exists(file: ARRAY OF CHAR): BOOLEAN

> Returns TRUE if a file file exists, and FALSE otherwise.

### GetModTime

    PROCEDURE GetModTime(file: ARRAY OF CHAR;
                         VAR mtime: TimeStamp;
                         VAR res: Result)

> Gets the modification time of the given file to mtime. On success res will contain done, otherwise an error code indicating the problem.

### SetModTime

    PROCEDURE SetModTime(file: ARRAY OF CHAR;
                         mtime: TimeStamp;
                         VAR res: Result)

> Sets the modification time of the given file to mtime. On success res will contain done, otherwise an error code that indicates the problem. Note that under Unix this procedure will also change the access time to the value of mtime.

Constant Detail

### accessDenied

    CONST accessDenied

> Access to the channel was denied. For example, because a file's permissions don't permit the requested access method, or because the given URL isn't publically readable.

### anonymousFile

    CONST anonymousFile

> A file can only be registered if a file name was passed to the initial call to Tmp.

### channelClosed

    CONST channelClosed

### closeError

    CONST closeError

### dirWriteDenied

    CONST dirWriteDenied

> You need to have write permission for the directory you want to add a new file to.

### directoryFull

    CONST directoryFull

> The directory or the file system that would contain the new file cannot be extended, either because there is no space left or the directory has a fixed upper limit.

### done

    CONST done

### fileError

    CONST fileError

> Unspecified error when opening/creating a file. This usually means that this module doesn't know how to interpret the error code delivered by the OS.

### invalidChannel

    CONST invalidChannel

### invalidFormat

    CONST invalidFormat

### invalidTime

    CONST invalidTime

> The time passed to procedure SetModTime is no valid time stamp. Either the millisecond part isn't valid, or the time value is too large or too small to be mapped to the time value of the underlying OS.

### isDirectory

    CONST isDirectory

> The ``flags`' argument specified write access, and the file is a directory.

### linkLoop

    CONST linkLoop

> Too many symbolic links were resolved while trying to look up the file name. The operating system has an arbitrary limit on the number of symbolic links that may be resolved in looking up a single file name, as a primitive way to detect loops.

### nameTooLong

    CONST nameTooLong

> Either the total length of the file name or of an individual file name component is too large. The operating system can impose such limits (see PATH_MAX and NAME_MAX in ``/usr/include/limits.h`'), or the file system itself restricts the format of names on it.

### noLength

    CONST noLength

### noModTime

    CONST noModTime

### noPosition

    CONST noPosition

### noReadAccess

    CONST noReadAccess

### noRoom

    CONST noRoom

### noSuchFile

    CONST noSuchFile

> The named file in a call to Old does not exist. Or the directory part of a file name passed to New or Tmp does not exist.

### noTmpName

    CONST noTmpName

### noWriteAccess

    CONST noWriteAccess

### notDirectory

    CONST notDirectory

> A file that is referenced as a directory component of the file name exists, but is not a directory.

### notOwner

    CONST notOwner

> Only the owner of a file can change its modification time.

### outOfRange

    CONST outOfRange

### read

    CONST read

> If the file cannot be opened for reading access, then it isn't opened at all. In this case the error code is set to noReadAccess.

### readAfterEnd

    CONST readAfterEnd

### readError

    CONST readError

### readOnlyFileSystem

    CONST readOnlyFileSystem

> The file resides on a read-only file system and it is attempted to create a new file, or to gain write access for an existing one.

### tooManyFiles

    CONST tooManyFiles

> The process or the entire system has too many files open.

### tryRead

    CONST tryRead

> Try to open this file for reading access. If the file permissions don't permit reading the file is opened nevertheless, but the file descriptor's attribute File.readable is set to FALSE.

### tryWrite

    CONST tryWrite

> Try to open this file for writing access. If the file permissions don't permit writing the file is opened nevertheless, but the file descriptor's attribute File.writable is set to FALSE.

### write

    CONST write

> If the file cannot be opened for writing access, then it isn't opened at all. In this case the error code is set to noWriteAccess.

### writeError

    CONST writeError