← Index

x/sys/file

File I/O via POSIX syscalls, homed on the File class.

Imports x/platform/syscall for syscall-door; read buffers come from the (str make) core primitive, so File runs under plain x-core. Call (File file-modes) / (File stat-flags) for the symbolic flag tables.

Class File

Blocking file I/O over raw POSIX syscalls (open/close/read/write/seek).

Lifecycle: (File open path mode) -> a file descriptor; thread it through (File read)/(File write)/(File getc)/(File seek); (File close fd) when done.

Return values are the raw syscall results: a negative number is an error (-errno). (File read) returns the byte count, 0 at EOF; (File getc) returns -1 at EOF.

read/write/getc operate on a caller-allocated string buffer – allocate one with (str make N), fetched via (prim-ref ‘str ‘make): read fills it and returns how many bytes landed; write sends size bytes out of it.

(File open)’s mode is flexible: a number passes straight through; a single symbol (rdonly, wronly, …) resolves via (File file-modes); a list of symbols is OR’d together – (list ‘wronly ‘creat ‘trunc) is 577. Call (File file-modes) for the full table, or (File stat-flags) for the stat S_* flags.

syscall-door is pulled in automatically (imports x/platform/syscall); syscall and (str make) are core primitives, so File runs under plain x-core.

(File file-modes)

The file open-mode table: an alist mapping each symbolic O_* flag name to its numeric Linux value. Use a key as (File open)’s mode argument; OR numeric values together for combined flags.

Returns: LIST — Alist of (symbol value) for: accmode rdonly wronly rdwr creat excl noctty trunc append nonblock dsync fasync direct largefile directory nofollow noatime cloexec sync path

(File stat-flags)

The stat mode-flag table: an alist mapping each symbolic S_* name to its numeric Linux value, for decoding a stat result’s st_mode (the ifmt bits select the file type; the rest are permission and set-id/sticky bits).

Returns: LIST — Alist of (symbol value) for: ifmt ifdir ifchr ifblk ifreg ififo iflnk ifsock isuid isgid isvtx iread iwrite iexec

(File open pathname mode . perm)

Open a file, returning a file descriptor.

Parameters:

• pathname : STRING — File path to open
• mode : ANY — Open mode – a number (e.g. 577), one symbol from (File file-modes) (e.g. ‘rdonly), or a list of symbols OR’d together (e.g. (list ‘wronly ‘creat ‘trunc))
• perm : ANY — Permission bits for a newly created file when the mode includes creat; default 0644. Ignored when the file is not created.

Returns: INTEGER — File descriptor, or negative on error

(File close fd)

Close a file descriptor.

Parameters:

• fd : INTEGER — File descriptor to close

Returns: INTEGER — 0 on success, negative on error

(File read fd buffer size)

Read bytes from a file descriptor into a buffer.

Parameters:

• fd : INTEGER — File descriptor to read from
• buffer : STRING — Buffer to read into
• size : INTEGER — Maximum bytes to read

Returns: INTEGER — Bytes read, 0 at EOF, negative on error

(File write fd buffer size)

Write bytes from a buffer to a file descriptor.

Parameters:

• fd : INTEGER — File descriptor to write to
• buffer : STRING — Data to write
• size : INTEGER — Number of bytes to write

Returns: INTEGER — Bytes written, or negative on error

(File getc fd)

Read a single character from a file descriptor.

Parameters:

• fd : INTEGER — File descriptor to read from

Returns: CHARACTER — Character read, or -1 at EOF

(File %whence whence)

Resolve a seek origin to its POSIX SEEK_* value (identical across Linux/macOS): ‘set -> 0, ‘cur -> 1, ‘end -> 2; a number passes through. Raises a label ‘type Err on anything else – an unknown origin must not reach the kernel.

Parameters:

• whence : ANY — Seek origin – symbol or number

Returns: INTEGER — 0, 1, 2, or the number given

(File seek fd offset . whence)

Reposition a file descriptor’s read/write offset (lseek). Seeking past end of file is allowed; a later write there leaves a hole that reads back as zero bytes.

Parameters:

• fd : INTEGER — File descriptor
• offset : INTEGER — Byte offset, interpreted per whence
• whence : ANY — Origin – ‘set (absolute, the default), ‘cur (relative to the current offset), ‘end (relative to end of file); or the numeric 0/1/2

Returns: INTEGER — The new offset from the start of the file, or negative on error

(File tell fd)

The file descriptor’s current offset – (File seek fd 0 ‘cur).

Parameters:

• fd : INTEGER — File descriptor

Returns: INTEGER — Current offset from the start of the file, or negative on error

(File truncate fd . size)

Truncate (or extend) the open file to size bytes (ftruncate). The offset does not move – seek explicitly if it now lies past the end.

Parameters:

• fd : INTEGER — File descriptor, opened writable
• size : INTEGER — New size in bytes; default the current offset

Returns: INTEGER — 0 on success, negative on error

(File stat path)

File metadata as an alist: ((size . BYTES) (mode . RAW) (file-type . SYM) (mtime . UNIX-SECONDS) (atime . UNIX-SECONDS) (uid . N) (gid . N) (nlink . N)). file-type is one of ‘file ‘dir ‘link ‘char ‘block ‘fifo ‘socket (from the S_IFMT bits). Raises a label ‘io Err on failure.

Parameters:

• path : STRING — Path to stat

Returns: ALIST — ((size . N) (mode . M) (file-type . K) (mtime . T) (atime . T) (uid . U) (gid . G) (nlink . L))

(File exists? path)

Does path name an existing filesystem entry? (Any file type – file, directory, link target…)

Deliberately duplicated across layers with (Sys file-exists?) (#361): that access(2) door is what boot/module.x can reach before this module loads. Post-boot file work belongs here.

Parameters:

• path : STRING — Path to test

Returns: BOOL — True when stat succeeds

(File type path)

The file type of what path names: ‘file ‘dir ‘link ‘char ‘block ‘fifo ‘socket, as (File stat) gives it under file-type – or nil when nothing is there or path is not a string. Never raises.

(File stat) decodes the whole record and raises a label ‘io Err for a path that is not there; this reads the mode alone and answers nil, for the callers that ask only what kind of thing a path is – a shell’s test -e, -f and -d.

Parameters:

• path : ANY — Path to look at, symlinks followed

Returns: ANY — A file-type symbol, or nil

(File ltype path)

The file type of path itself, as (File type) answers it, but a symbolic link reports ‘link instead of its target’s type – nil when nothing is there or path is not a string. Never raises.

(File type) is to (File stat) what this is to (File lstat): a shell’s test -L and -h.

Parameters:

• path : ANY — Path to look at, symlinks NOT followed

Returns: ANY — A file-type symbol, or nil

(File read-all path)

The whole file as one string (stat for the size, one read). Raises a label ‘io Err on open/read failure.

Parameters:

• path : STRING — File to read

Returns: STRING — The file’s bytes

(File write-all path s)

Write s as the entire contents of path (create or truncate, mode 0644). Raises a label ‘io Err on failure; returns the byte count written.

Parameters:

• path : STRING — File to write (created/truncated)
• s : STRING — Contents

Returns: INTEGER — Bytes written

(File read-lines path)

The file as a list of lines (split on newline; a trailing final newline yields no empty last line).

Parameters:

• path : STRING — File to read

Returns: LIST — List of line strings

(File list-dir path)

The directory’s entry names as a list of strings, ‘.’ and ‘..’ excluded. Per-OS dirent decoding over getdents64 (Linux) / getdirentries64 (Darwin). Raises a label ‘io Err on failure.

Parameters:

• path : STRING — Directory to list

Returns: LIST — Entry-name strings

(File mkdir path . perm)

Create a directory (default mode 0755). Raises a label ‘io Err on failure; returns nil.

Parameters:

• path : STRING — Directory to create
• perm : INTEGER — Permission bits; default 0755

Returns: ANY — nil

(File unlink path)

Remove a file (not a directory – see rmdir). Raises a label ‘io Err on failure; returns nil.

Parameters:

• path : STRING — File to remove

Returns: ANY — nil

(File rmdir path)

Remove an empty directory. Raises a label ‘io Err on failure; returns nil.

Parameters:

• path : STRING — Empty directory to remove

Returns: ANY — nil

(File rename from to)

Rename/move a filesystem entry. Raises a label ‘io Err on failure; returns nil.

Parameters:

• from : STRING — Existing path
• to : STRING — New path

Returns: ANY — nil

(File chmod path mode)

Set a path’s permission bits (chmod). Raises a label ‘io Err on failure; returns nil.

Parameters:

• path : STRING — Path whose mode to set
• mode : INTEGER — Permission bits, e.g. 420 for 0644

Returns: ANY — nil

(File chown path uid gid)

Set a path’s owning user and group (chown). Either id may be -1 to leave that half alone. Raises a label ‘io Err on failure; returns nil.

Parameters:

• path : STRING — Path whose owner to set
• uid : INTEGER — Owning user id, or -1 to leave it
• gid : INTEGER — Owning group id, or -1 to leave it

Returns: ANY — nil

(File link target path)

Create a hard link: a second directory entry for the SAME inode, so both names share the file’s bytes and it survives until the last one goes. Raises a label ‘io Err on failure; returns nil.

Parameters:

• target : STRING — Existing path
• path : STRING — New name for it

Returns: ANY — nil

(File symlink target path)

Create a symbolic link at path pointing at target. The target is stored as WRITTEN and is never resolved here, so it need not exist. Raises a label ‘io Err on failure; returns nil.

Parameters:

• target : STRING — What the link should point at
• path : STRING — The link to create

Returns: ANY — nil

(File readlink path)

The text a symbolic link holds, exactly as it was written – relative targets come back relative. Raises a label ‘io Err when the path is not a link.

Parameters:

• path : STRING — Symbolic link to read

Returns: STRING — The link’s target

(File utimes path)

Set a path’s access and modification times to the current clock (utimes with a null times pointer) – what touch(1) means for a file that already exists. Raises a label ‘io Err on failure; returns nil.

Given times are (File set-times path atime mtime).

Parameters:

• path : STRING — Path to stamp

Returns: ANY — nil

(File set-times path atime mtime)

Set a path’s access and modification times to given whole seconds (utimes with a pair of timevals) – what touch -d and cp -p mean. Raises a label ‘io Err on failure; returns nil.

Each time is a word of seconds then a zero word: a timeval’s microseconds, or a timespec’s nanoseconds where the platform stands utimensat in for utimes, which is why whole seconds are the door.

Parameters:

• path : STRING — Path to stamp
• atime : INTEGER — Access time, seconds since the epoch
• mtime : INTEGER — Modification time, seconds since the epoch

Returns: ANY — nil

(File mkfifo path . perm)

Create a named pipe (mknod with the S_IFIFO bit). Raises a label ‘io Err on failure; returns nil.

Parameters:

• path : STRING — FIFO to create
• perm : INTEGER — Permission bits; default 0644

Returns: ANY — nil

(File statfs path)

The filesystem holding path, as an alist: ((bsize . BYTES) (blocks . N) (bfree . N) (bavail . N) (files . N) (ffree . N)). Multiply a block count by bsize for bytes. Raises a label ‘io Err on failure.

Parameters:

• path : STRING — Any path on the filesystem to measure

Returns: ALIST — ((bsize . B) (blocks . N) (bfree . N) (bavail . N) (files . N) (ffree . N))

(File lstat path)

File metadata like (File stat), but a symbolic link reports itself (file-type ‘link) instead of its target – the door (File walk) uses to avoid following link cycles. Raises a label ‘io Err on failure.

Parameters:

• path : STRING — Path to stat, symlinks NOT followed

Returns: ALIST — ((size . N) (mode . M) (file-type . K) (mtime . T) (atime . T) (uid . U) (gid . G) (nlink . L))

(File copy from to)

Copy a file’s bytes, binary-safe: a 64KB fd-level read/write loop driven by the raw byte counts, never by string length (a string’s observable bytes end at the first NUL, so read-all->write-all corrupts binary). Raises a label ‘io Err on failure; returns the byte count copied.

Parameters:

• from : STRING — Source file
• to : STRING — Destination (created/truncated, mode 0644)

Returns: INTEGER — Bytes copied

(File temp . prefix)

Create a fresh temporary file that did not exist before the call: O_CREAT

O_EXCL

O_RDWR, mode 0600, name = prefix + random suffix (bytes from /dev/urandom), retrying on collision. Returns (fd . path); closing and unlinking are the caller’s.

Parameters:

• prefix : STRING — Path prefix for the new file; default “/tmp/x-“

Returns: PAIR — (open-fd . path)

(File walk path)

Every non-directory entry under path, recursively, as paths RELATIVE to path (files, links, sockets, fifos alike – filter on (File lstat) file-type for finer policy). Recursion decisions ride lstat, so a symlinked directory is REPORTED as its link, never followed (no cycle risk). Order follows the directory tables; treat it as unspecified. Raises a label ‘io Err on failure.

Parameters:

• path : STRING — Directory to walk

Returns: LIST — Relative path strings