← Index

x/sys/posix

POSIX system call wrappers, homed on the Sys class.

POSIX via the Sys class: (Sys fork), (Sys exec name args), (Sys pipe),

(Sys open-read path), (Sys getenv name), (Sys isatty fd), …

Class Sys

(Sys %sign-fold r)

(Sys fork)

Fork the current process.

Returns: INT — PID of child in parent, 0 in child, -1 on error

(Sys getpid)

Return the current process ID.

Returns: INT — Process ID

(Sys exit status)

Terminate the process with the given exit status.

Parameters:

• status : INT — Exit status code

(Sys wait pid)

Wait for a child and return how it ended.

The old contract returned WEXITSTATUS unconditionally, so a signal-killed child reported 0 – success (#226).

Parameters:

• pid : INT — Process ID to wait for

Returns: INT — Exit status 0-255 for a normal exit; 128+N when signal N killed the child (the shell convention)

(Sys exec name args)

Replace the current process with the named program. Does not return on success.

Parameters:

• name : STRING — Program name
• args : LIST — List of argument strings

sigint

SIGINT: terminal interrupt (ctrl-c)

Member: data carried by a Sys instance.

sigkill

SIGKILL: uncatchable, unignorable kill

Member: data carried by a Sys instance.

sigterm

SIGTERM: polite termination request

Member: data carried by a Sys instance.

sig-dfl

signal(2) disposition: restore the default action

Member: data carried by a Sys instance.

sig-ign

signal(2) disposition: ignore the signal

Member: data carried by a Sys instance.

(Sys kill pid sig)

Send a signal to a process.

Parameters:

• pid : INT — Process ID
• sig : INT — Signal number, e.g. (Sys sigterm)

Returns: INT — 0 on success, -1 on error

(Sys signal sig disposition)

Set a signal’s disposition to ignore or default.

Parameters:

• sig : INT — Signal number
• disposition : INT — (Sys sig-ign) or (Sys sig-dfl) ONLY – an x-lang closure cannot be a C signal handler

Returns: ANY — The previous disposition; meaningful only when it was one of the two constants

(Sys close fd)

Close a file descriptor.

Parameters:

• fd : INT — File descriptor to close

Returns: INT — 0 on success, -1 on error

(Sys dup2 old new)

Duplicate a file descriptor onto another.

Parameters:

• old : INT — Source file descriptor
• new : INT — Target file descriptor

Returns: INT — New file descriptor, or -1 on error

(Sys pipe)

Create a pipe and return a pair of file descriptors.

Returns: PAIR — Pair of (read-fd . write-fd)

(Sys open-read path)

Open a file for reading.

Parameters:

• path : STRING — File path to open

Returns: INT — File descriptor, or -1 on error

(Sys open-write path)

Open a file for writing, creating or truncating it.

Parameters:

• path : STRING — File path to open

Returns: INT — File descriptor, or -1 on error

(Sys open-append path)

Open a file for appending, creating it if necessary.

Parameters:

• path : STRING — File path to open

Returns: INT — File descriptor, or -1 on error

(Sys fd-write fd s)

Write a string to a file descriptor.

Parameters:

• fd : NUMBER — File descriptor
• s : STRING — String to write

Returns: NUMBER — Bytes written

(Sys fd-read fd n)

Read up to n bytes from a file descriptor (libc read via FFI).

Parameters:

• fd : NUMBER — File descriptor to read from
• n : NUMBER — Maximum number of bytes to read

Returns: LIST — Byte values (0-255) in read order; () at EOF or on error

(Sys file-exists? path)

Check if a file exists (via access with F_OK=0).

Deliberately duplicated across tiers with (File exists?) (#361): boot/module.x resolves imports through THIS door before sys/file (stat + Err, the ergonomic sibling) can load. Post-boot callers doing file work generally want the File class.

Parameters:

• path : STRING — File path to check

Returns: BOOL — True if file exists

(Sys chdir path)

Change the current working directory – (Sys getcwd) reads it back.

Parameters:

• path : STRING — Directory path

Returns: INT — 0 on success, -1 on error

(Sys getcwd)

The current working directory (getcwd) – the symmetric half of (Sys chdir) (#361).

Returns: STRING — Absolute path, or nil on failure

(Sys setenv name val)

Set an environment variable, overwriting any existing value – (Sys unsetenv) removes it.

Parameters:

• name : STRING — Variable name
• val : STRING — Variable value

Returns: INT — 0 on success, -1 on error

(Sys getenv name)

Get the value of an environment variable.

Parameters:

• name : STRING — Variable name

Returns: STRING — Variable value, or nil if not set

(Sys unsetenv name)

Remove an environment variable – the symmetric half of (Sys setenv) (#361). Removing an absent name succeeds.

Parameters:

• name : STRING — Variable name

Returns: INT — 0 on success, -1 on error

(Sys environ)

The whole environment as a list of “NAME=VALUE” strings, in table order (#361). Split an entry at its FIRST ‘=’ only – values may themselves contain ‘=’.

Returns: LIST — “NAME=VALUE” strings

(Sys getuid)

The process’s REAL user id – who invoked it, before any setuid.

Returns: INT — User id

(Sys geteuid)

The process’s EFFECTIVE user id – who it acts as, which is what a permission check reads.

Returns: INT — User id

(Sys getgid)

The process’s real group id.

Returns: INT — Group id

(Sys getegid)

The process’s effective group id.

Returns: INT — Group id

(Sys getgroups)

The process’s supplementary group ids, as a list. getgroups is asked its own count first, so the buffer is never guessed.

Returns: LIST — Group ids

(Sys uname)

The running system, as an alist: ((sysname . S) (nodename . S) (release . S) (version . S) (machine . S)). sysname is “Darwin” or “Linux”; machine is the architecture uname -m prints.

Returns: ALIST — ((sysname . S) (nodename . S) (release . S) (version . S) (machine . S))

(Sys cpu-count)

How many processors are online (sysconf _SC_NPROCESSORS_ONLN) – what nproc(1) reports. Answers 1 when the query fails, never 0.

Returns: INT — Processor count, at least 1

(Sys sync)

Flush the filesystem write buffers (sync). Returns nil; there is nothing to fail.

Returns: ANY — nil

(Sys fsync fd)

Flush ONE open file’s buffers to disk (fsync), rather than the whole system.

Parameters:

• fd : INT — File descriptor to flush

Returns: INT — 0 on success, -1 on error

(Sys nice increment)

Raise the process’s nice value – a HIGHER number means a LOWER priority, and only a privileged process may lower it.

Parameters:

• increment : INT — Amount to add to the scheduling priority

Returns: INT — The new nice value, or -1 on error

(Sys chroot path)

Change the process’s filesystem root. Privileged: an unprivileged caller gets -1 with EPERM.

Parameters:

• path : STRING — New filesystem root

Returns: INT — 0 on success, -1 on error

(Sys sleep seconds)

Block for the given number of seconds (libc sleep). A signal can wake it early; sub-second waits are (Sys usleep).

Parameters:

• seconds : INT — Whole seconds to block

Returns: INT — 0 after the full interval; the seconds left unslept when a signal woke it early

(Sys usleep micros)

Block for the given number of microseconds (libc usleep) – the sub-second door; whole seconds read better through (Sys sleep).

Parameters:

• micros : INT — Microseconds to block

Returns: INT — 0 on success, -1 on error

(Sys isatty fd)

Test whether a file descriptor refers to a terminal (TTY).

Parameters:

• fd : NUMBER — File descriptor to test

Returns: BOOL — True if fd refers to a terminal

(Sys clock)

Current process CPU time in microseconds (the (Sys time) profiler reads this). WALL-clock time is (Sys now) / (Sys time-of-day).

Returns: INT — Microseconds of CPU time consumed

(Sys time thunk)

Run THUNK and return its elapsed CPU time in microseconds. The thunk’s result is discarded – capture it via the closure when needed.

Parameters:

• thunk : CALLABLE — Zero-argument fn to run and time

Returns: INT — Elapsed CPU microseconds

Examples:

(number? (Sys time (fn () (List fold + 0 (List range 0 100))))) => #t

(Sys time-of-day)

Wall-clock time from gettimeofday: (unix-seconds . microseconds).

Returns: PAIR — (seconds . microseconds)

(Sys now)

Wall-clock time as unix seconds (UTC) – the noun reading; (Sys time thunk) is the verb. CPU time is (Sys clock); civil dates are the Date class (x/sys/date).

Returns: INT — Seconds since the unix epoch