Library / System / Runtime / File
Full file-interaction class over the POSIX byte-I/O surface.
Fields 3
String pathint32 fdLock gateConstructors 1
INIT(REFERENCE String path)
Methods 32
MODIFY METHOD openRead() RETURNS STATUSmodifies
Open read-only (O_RDONLY).
MODIFY METHOD openWrite() RETURNS STATUSmodifies
Open for writing, creating + truncating (O_WRONLY|O_CREAT|O_TRUNC, 0644).
MODIFY METHOD openAppend() RETURNS STATUSmodifies
Open for appending, creating if absent (O_WRONLY|O_CREAT|O_APPEND, 0644).
MODIFY METHOD openReadWrite() RETURNS STATUSmodifies
Open for reading + writing, creating if absent (O_RDWR|O_CREAT, 0644).
MODIFY METHOD openExclusive() RETURNS STATUSmodifies
Open exclusively — fails if the file exists (O_WRONLY|O_CREAT|O_EXCL).
METHOD isOpen() RETURNS booleanreads
TRUE while a persistent fd is open.
MODIFY METHOD close() RETURNS STATUSmodifies
Close the persistent fd (no-op if not open).
MODIFY METHOD read() RETURNS | binary[]modifies
Read the entire file's bytes (Readable). Adaptive: persistent fd (gate-guarded) if open, else opens O_RDONLY, drains, closes.
MODIFY METHOD write(REFERENCE binary[] content) RETURNS | int64modifies
Write every byte of content, replacing contents (Writable). Adaptive.
The extent is content.length — see the Writable contract.
MODIFY METHOD appendBytes(REFERENCE binary[] content) RETURNS | int64modifies
Append length bytes to the end (creating if absent). Adaptive.
METHOD readAt(int64 offset, int32 max) RETURNS | binary[]reads
Read up to max bytes at absolute offset (pread). Persistent fd.
MODIFY METHOD writeAt(int64 offset, REFERENCE binary[] content) RETURNS | int64modifies
Write length bytes at absolute offset (pwrite). Persistent fd.
MODIFY METHOD readText() RETURNS | Stringmodifies
Read the whole file as UTF-8 text. Invalid UTF-8 → FAILURE.
MODIFY METHOD writeText(REFERENCE String content) RETURNS STATUSmodifies
Write content as UTF-8 text, replacing the file's contents.
MODIFY METHOD appendText(REFERENCE String content) RETURNS STATUSmodifies
Append content as UTF-8 text to the end of the file.
MODIFY METHOD seekFromStart(int64 offset) RETURNS | int64modifies
Move the cursor to offset bytes from the START of the file.
Returns the resulting absolute position.
MODIFY METHOD seekFromCurrent(int64 offset) RETURNS | int64modifies
Move the cursor offset bytes from where it currently sits — negative
moves backward. Returns the resulting absolute position.
MODIFY METHOD seekFromEnd(int64 offset) RETURNS | int64modifies
Move the cursor offset bytes from the END of the file — 0 is the end
itself and negative moves back into the content. Returns the resulting
absolute position. (A POSITIVE offset here is legal and seeks PAST the
end; writing there creates a hole. That is lseek's behaviour and this
wrapper does not change it.)
MODIFY METHOD tell() RETURNS | int64modifies
Current cursor position (lseek SEEK_CUR, no move).
MODIFY METHOD size() RETURNS | int64modifies
File size in bytes — seek to end then restore the cursor (no stat). Nested so no top-level statement follows a pipe consume.
MODIFY METHOD truncateTo(int64 length) RETURNS STATUSmodifies
Truncate (or extend) the file to length bytes (ftruncate).
MODIFY METHOD flush() RETURNS STATUSmodifies
Flush buffered writes to disk (fsync).
MODIFY METHOD lockExclusive(boolean blocking) RETURNS STATUSmodifies
Acquire an exclusive advisory lock. blocking FALSE → non-blocking.
MODIFY METHOD unlockFile() RETURNS STATUSmodifies
Release any advisory lock held on the file (LOCK_UN).
METHOD exists() RETURNS booleanreads
TRUE if the path exists (access F_OK).
METHOD isReadable() RETURNS booleanreads
TRUE if readable by the caller (access R_OK).
METHOD isWritable() RETURNS booleanreads
TRUE if writable by the caller (access W_OK).
METHOD isExecutable() RETURNS booleanreads
TRUE if executable by the caller (access X_OK).
MODIFY METHOD deleteFile() RETURNS STATUSmodifies
Delete the file (unlink). Named deleteFile — delete is a C++ keyword.
MODIFY METHOD renameTo(REFERENCE String dest) RETURNS STATUSmodifies
Rename / move the file to dest (rename).
MODIFY METHOD setPermissions(int32 mode) RETURNS STATUSmodifies
Change the file's permission bits (chmod); mode is an octal value.