envzn
0.8 · beta · not released

Library / System / Runtime / File

CLASSIMPLEMENTS Readable, Writable

File

Full file-interaction class over the POSIX byte-I/O surface.

Fields 3

String path
int32 fd
Lock gate

Constructors 1

INIT(REFERENCE String path)

Methods 32

MODIFY METHOD openRead() RETURNS STATUS
modifies

Open read-only (O_RDONLY).

MODIFY METHOD openWrite() RETURNS STATUS
modifies

Open for writing, creating + truncating (O_WRONLY|O_CREAT|O_TRUNC, 0644).

MODIFY METHOD openAppend() RETURNS STATUS
modifies

Open for appending, creating if absent (O_WRONLY|O_CREAT|O_APPEND, 0644).

MODIFY METHOD openReadWrite() RETURNS STATUS
modifies

Open for reading + writing, creating if absent (O_RDWR|O_CREAT, 0644).

MODIFY METHOD openExclusive() RETURNS STATUS
modifies

Open exclusively — fails if the file exists (O_WRONLY|O_CREAT|O_EXCL).

METHOD isOpen() RETURNS boolean
reads

TRUE while a persistent fd is open.

MODIFY METHOD close() RETURNS STATUS
modifies

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 | int64
modifies

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 | int64
modifies

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 | int64
modifies

Write length bytes at absolute offset (pwrite). Persistent fd.

MODIFY METHOD readText() RETURNS | String
modifies

Read the whole file as UTF-8 text. Invalid UTF-8 → FAILURE.

MODIFY METHOD writeText(REFERENCE String content) RETURNS STATUS
modifies

Write content as UTF-8 text, replacing the file's contents.

MODIFY METHOD appendText(REFERENCE String content) RETURNS STATUS
modifies

Append content as UTF-8 text to the end of the file.

MODIFY METHOD seekFromStart(int64 offset) RETURNS | int64
modifies

Move the cursor to offset bytes from the START of the file. Returns the resulting absolute position.

MODIFY METHOD seekFromCurrent(int64 offset) RETURNS | int64
modifies

Move the cursor offset bytes from where it currently sits — negative moves backward. Returns the resulting absolute position.

MODIFY METHOD seekFromEnd(int64 offset) RETURNS | int64
modifies

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 | int64
modifies

Current cursor position (lseek SEEK_CUR, no move).

MODIFY METHOD size() RETURNS | int64
modifies

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 STATUS
modifies

Truncate (or extend) the file to length bytes (ftruncate).

MODIFY METHOD flush() RETURNS STATUS
modifies

Flush buffered writes to disk (fsync).

MODIFY METHOD lockExclusive(boolean blocking) RETURNS STATUS
modifies

Acquire an exclusive advisory lock. blocking FALSE → non-blocking.

MODIFY METHOD lockShared(boolean blocking) RETURNS STATUS
modifies

Acquire a shared advisory lock.

MODIFY METHOD unlockFile() RETURNS STATUS
modifies

Release any advisory lock held on the file (LOCK_UN).

METHOD exists() RETURNS boolean
reads

TRUE if the path exists (access F_OK).

METHOD isReadable() RETURNS boolean
reads

TRUE if readable by the caller (access R_OK).

METHOD isWritable() RETURNS boolean
reads

TRUE if writable by the caller (access W_OK).

METHOD isExecutable() RETURNS boolean
reads

TRUE if executable by the caller (access X_OK).

MODIFY METHOD deleteFile() RETURNS STATUS
modifies

Delete the file (unlink). Named deleteFile — delete is a C++ keyword.

MODIFY METHOD renameTo(REFERENCE String dest) RETURNS STATUS
modifies

Rename / move the file to dest (rename).

MODIFY METHOD setPermissions(int32 mode) RETURNS STATUS
modifies

Change the file's permission bits (chmod); mode is an octal value.