SUMMARY: MODULE | CLASS | TYPE | PROC | VAR | CONST | DETAIL: TYPE | PROC | VAR | CONST |
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.
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: | |
Method Summary | |
GetTemplate(Msg, VAR LString) Translates this module's error codes into strings. | |
Inherited Methods | |
Class Summary: File [Detail] | |
+---Channel.Channel | +---PosixFileDescr.Channel | +--Files.File | |
Inherited Fields | |
From Channel.Channel: From PosixFileDescr.Channel: | |
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: From PosixFileDescr.Channel: |
Class Summary: Reader [Detail] | |
+---Channel.Reader | +---PosixFileDescr.Reader | +--Files.Reader | |
Inherited Fields | |
From Channel.Reader: | |
Inherited Methods | |
From Channel.Reader: From PosixFileDescr.Reader: |
Class Summary: Writer [Detail] | |
+---Channel.Writer | +---PosixFileDescr.Writer | +--Files.Writer | |
Inherited Fields | |
From Channel.Writer: | |
Method Summary | |
Truncate(LONGINT) Causes the file associated with w to have the specified length. | |
Inherited Methods | |
From Channel.Writer: From PosixFileDescr.Writer: |
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 |
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 |
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'.
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.
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 |
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.
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.
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.
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 |
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 |
TYPE Result = Result
Procedure Detail |
PROCEDURE Exists(file: ARRAY OF CHAR): BOOLEAN
Returns TRUE if a file file exists, and FALSE otherwise.
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.
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 |
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.
CONST anonymousFile
A file can only be registered if a file name was passed to the initial call to Tmp.
CONST channelClosed
CONST closeError
CONST dirWriteDenied
You need to have write permission for the directory you want to add a new file to.
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.
CONST done
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.
CONST invalidChannel
CONST invalidFormat
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.
CONST isDirectory
The `flags' argument specified write access, and the file is a directory.
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.
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.
CONST noLength
CONST noModTime
CONST noPosition
CONST noReadAccess
CONST noRoom
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.
CONST noTmpName
CONST noWriteAccess
CONST notDirectory
A file that is referenced as a directory component of the file name exists, but is not a directory.
CONST notOwner
Only the owner of a file can change its modification time.
CONST outOfRange
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.
CONST readAfterEnd
CONST readError
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.
CONST tooManyFiles
The process or the entire system has too many files open.
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.
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.
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.
CONST writeError