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
ErrorContextThis 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