← 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: INTEGER — PID of child in parent, 0 in child, -1 on error

(Sys getpid)

Return the current process ID.

Returns: INTEGER — Process ID

Examples:

(< 0 (Sys getpid)) => #t

(Sys setsid)

Start a new session with this process as its leader, as a daemon does after its fork: setsid(2), through libc since Darwin’s syscall table has no number for it.

Returns: INTEGER — The new session id; negative when this process already leads a process group

(Sys exit status)

Terminate the process with the given exit status.

Parameters:

• status : INTEGER — Exit status code

(Sys args . which)

The process’s arguments as the engine was given them: the engine’s path, then everything after it. With ‘program, the launcher’s own options are left out: the engine’s path, then what follows the first “–”, which a launcher writes between its options and the program’s arguments. An engine started with no “–” has nothing left out.

Parameters:

• which : LIST — ‘program: leave out the launcher’s options

Returns: LIST — Argument strings

(Sys %program-args)

(Sys %launch-options)

(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).

A caught signal – the engine’s SIGINT, any catch-signal – interrupts waitpid, which then waits again; any other failure, such as a pid that is no child of this process, raises the io Err.

Parameters:

• pid : INTEGER — Process ID to wait for

Returns: INTEGER — 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)

Static field: data held by Sys itself, not by its instances.

sigkill

SIGKILL: uncatchable, unignorable kill

Static field: data held by Sys itself, not by its instances.

sigterm

SIGTERM: polite termination request

Static field: data held by Sys itself, not by its instances.

sig-dfl

signal(2) disposition: restore the default action

Static field: data held by Sys itself, not by its instances.

sig-ign

signal(2) disposition: ignore the signal

Static field: data held by Sys itself, not by its instances.

(Sys kill pid sig)

Send a signal to a process.

Parameters:

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

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

Examples:

(Sys kill (Sys getpid) 0) => 0

(Sys signal sig disposition)

Set a signal’s disposition to ignore or default.

Parameters:

• sig : INTEGER — Signal number
• disposition : INTEGER — (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

sigwinch

SIGWINCH: the terminal’s window changed size (28 on Darwin and Linux)

Static field: data held by Sys itself, not by its instances.

sigttou

SIGTTOU: a background process set or wrote to its terminal (22 on Darwin and Linux)

Static field: data held by Sys itself, not by its instances.

(Sys sigtstp)

SIGTSTP, the terminal’s stop key (^Z): 18 on Darwin, 20 on Linux.

Returns: INTEGER — The signal number

Examples:

(List includes? (Sys sigtstp) (list 18 20)) => #t

(Sys sigstop)

SIGSTOP, the stop no handler can catch: 17 on Darwin, 19 on Linux.

Returns: INTEGER — The signal number

Examples:

(List includes? (Sys sigstop) (list 17 19)) => #t

(Sys signals)

This kernel’s signals 1 to 31, each (NAME . NUMBER) in number order, NAME without its SIG – what kill -l and pkill -l list and a -SIGNAL names.

Returns: LIST — ((“HUP” . 1) (“INT” . 2) …)

(Sys catch-signal sig)

Catch a signal: from now on its arrival is recorded for take-signal, and nothing else happens – what it means is the caller’s to decide. A read or poll waiting when it arrives is interrupted.

Parameters:

• sig : INTEGER — Signal number

Returns: INTEGER — 0, or -1 when sig cannot be caught or this engine records no signals

(Sys take-signal sig)

Whether a caught signal arrived since the last take, clearing the record; two arrivals between takes are one.

Parameters:

• sig : INTEGER — Signal number

Returns: BOOL — True when it arrived

(Sys close fd)

Close a file descriptor.

Parameters:

• fd : INTEGER — File descriptor to close

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

Examples:

(Sys close -1) => -1

(Sys dup2 old new)

Duplicate a file descriptor onto another.

Parameters:

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

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

Examples:

(Sys dup2 -1 -1) => -1

(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: INTEGER — File descriptor, or -1 on error

Examples:

(Sys open-read "/nonexistent/file") => -1

(Sys open-write path)

Open a file for writing, creating or truncating it.

Parameters:

• path : STRING — File path to open

Returns: INTEGER — 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: INTEGER — 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

Examples:

(Sys fd-write -1 "hi") => -1

(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 profiles 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

Examples:

(Sys file-exists? "/") => #t
(Sys file-exists? "/nonexistent/file") => #f

(Sys chdir path)

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

Parameters:

• path : STRING — Directory path

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

Examples:

(Sys chdir "/nonexistent/dir") => -1

(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: INTEGER — 0 on success, -1 on error

Examples:

(Sys setenv "X_HELP_SETENV" "on") => 0
((fn (_ r) (Sys getenv "X_HELP_SETENV")) (Sys setenv "X_HELP_SETENV" "on")) => "on"

(Sys getenv name)

Get the value of an environment variable.

Parameters:

• name : STRING — Variable name

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

Examples:

(null? (Sys getenv "X_HELP_NO_SUCH_NAME")) => #t

(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: INTEGER — 0 on success, -1 on error

Examples:

(Sys unsetenv "X_HELP_NO_SUCH_NAME") => 0

(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: INTEGER — User id

(Sys geteuid)

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

Returns: INTEGER — User id

Examples:

(<= 0 (Sys geteuid)) => #t

(Sys getgid)

The process’s real group id.

Returns: INTEGER — Group id

Examples:

(<= 0 (Sys getgid)) => #t

(Sys getegid)

The process’s effective group id.

Returns: INTEGER — Group id

Examples:

(<= 0 (Sys getegid)) => #t

(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: INTEGER — 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 : INTEGER — File descriptor to flush

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

Examples:

(Sys fsync -1) => -1

(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 : INTEGER — Amount to add to the scheduling priority

Returns: INTEGER — 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: INTEGER — 0 on success, -1 on error

Examples:

(Sys chroot "/nonexistent/dir") => -1

(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 : INTEGER — Whole seconds to block

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

Examples:

(Sys sleep 0) => 0

(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 : INTEGER — Microseconds to block

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

Examples:

(Sys usleep 1000) => 0

(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 poll fds timeout)

Wait until a descriptor is ready, through poll(2). Answers each one that is, with what it is ready for – among in, out, hup (the other end closed), err and nval (not an open descriptor) – or nil when the timeout passes first. A signal that interrupts the wait answers nil as well, so a caller’s loop asks again; any other failure raises an io Err.

Parameters:

• fds : LIST — ((FD . EVENTS) …): each descriptor and what to wait for, a list of in and out
• timeout : INTEGER — Milliseconds to wait: -1 waits without end, 0 does not wait

Returns: LIST — ((FD . EVENTS) …) for the ready descriptors, or nil

(Sys %poll-bits events)

The pollfd events bits for a list of in and out.

Parameters:

• events : LIST — Symbols: in, out

Returns: INTEGER — POLLIN

POLLOUT as asked

Examples:

(Sys %poll-bits (list 'in)) => 1
(Sys %poll-bits (list 'in 'out)) => 5

(Sys %poll-events rev)

The symbols for a revents word: in (POLLIN or POLLPRI), out, err, hup, nval.

Parameters:

• rev : INTEGER — A pollfd’s revents

Returns: LIST — The events, in that order

Examples:

(Sys %poll-events 1) => ('in)
(Sys %poll-events 17) => ('in 'hup)

(Sys nonblock! fd . on)

Make reads and writes on fd answer at once rather than wait – O_NONBLOCK through fcntl(2) – or, given #f, wait again. A read with nothing to read then fails with EAGAIN, and a connect that cannot finish at once with EINPROGRESS, for poll to wait on. Raises an io Err when fcntl fails.

Reached as a SYSCALL, as Term’s ioctl is: fcntl is variadic, and on Apple arm64 a variadic argument goes on the stack, where the fixed-signature ffi door never puts it.

Parameters:

• fd : INTEGER — Descriptor
• on : BOOL — #f makes it wait again; the default is #t

Returns: BOOL — #t

(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: INTEGER — Microseconds of CPU time consumed

Examples:

(< 0 (Sys clock)) => #t

(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: INTEGER — 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: INTEGER — Seconds since the unix epoch

(Sys zone secs)

The local time zone in force at unix second secs, from the C library’s localtime_r: its offset from UTC in seconds east, its abbreviation, and whether it is daylight time. TZ in the environment chooses the zone, as it does for every C program; with none set, the system’s.

Civil fields in local time are (Date local secs).

Parameters:

• secs : INTEGER — Unix seconds: the instant whose zone to read

Returns: ALIST — ((offset . SECONDS-EAST) (name . STRING) (dst . BOOL))

(Sys local->unix year month day hour minute second)

Unix seconds for a civil time in the local zone, from the C library’s mktime: the zone TZ chooses, daylight time decided by the C library. Fields past their range carry into the next, as mktime’s do.

The inverse of the clock fields (Date local) reads; (Date local->unix date) takes a date alist.

Parameters:

• year : INTEGER — Year
• month : INTEGER — Month, 1-12
• day : INTEGER — Day of the month
• hour : INTEGER — Hour, 0-23
• minute : INTEGER — Minute
• second : INTEGER — Second

Returns: INTEGER — Seconds since the unix epoch