Base System Library¶

The system library provides the necessary primitives for Cozenage programs to inspect and interact with the host operating system. It offers a comprehensive suite of tools for process management, user authentication, and system telemetry. By exposing low-level POSIX functionality—such as process IDs, environment variables, and user/group identities—the library allows developers to write “system-aware” scripts that can adapt to their environment, manage permissions, and execute external shell commands.

Whether you are auditing system resources with cpu-count and uptime, navigating the directory tree with chdir, or verifying security contexts with is-root?, this module serves as the primary bridge between the Cozenage REPL and the underlying Unix-like kernel.

Process Information¶

get-pid¶

(get-pid)

Returns the process ID (PID) of the calling process.

Returns:: The process ID.
Return type:: integer

Example

--> (get-pid)
12345

get-ppid¶

(get-ppid)

Returns the process ID of the parent of the calling process.

Returns:: The parent process ID.
Return type:: integer

Environment Variables¶

get-env-var¶

(get-env-var string)

Returns the value of the environment variable string. If the variable is unset, returns #false.

Parameters:: string (string) – The name of the environment variable.
Returns:: The value of the variable or #false.
Return type:: string or boolean

Example

--> (get-env-var "SHELL")
"/bin/bash"
--> (get-env-var "NON_EXISTENT")
#false

get-env-vars¶

(get-env-vars)

Returns an association list of all environment variables in the running process. Each element is a pair of (variable . value).

Returns:: An alist of environment variables.
Return type:: list

get-home¶

(get-home)

Returns the path to the current user’s home directory.

Returns:: The home directory path.
Return type:: string

get-path¶

(get-path)

Returns a list of directories in the current user’s PATH environment variable, ordered according to the shell’s search priority.

Returns:: A list of directory paths.
Return type:: list

User and Group IDs¶

get-uid¶

(get-uid)

Returns the real user ID of the calling process.

Returns:: The user ID.
Return type:: integer

get-gid¶

(get-gid)

Returns the real group ID of the calling process.

Returns:: The group ID.
Return type:: integer

get-euid¶

(get-euid)

Returns the effective user ID of the calling process.

Returns:: The effective user ID.
Return type:: integer

get-egid¶

(get-egid)

Returns the effective group ID of the calling process.

Returns:: The effective group ID.
Return type:: integer

set-uid!¶

(set-uid! n)

Sets the real user ID of the currently running process to n.

Parameters:: n (integer) – The new user ID.
Returns:: #true on success, otherwise returns an OS error.
Return type:: boolean

set-gid!¶

(set-gid! n)

Sets the real group ID of the currently running process to n.

Parameters:: n (integer) – The new group ID.
Returns:: #true on success, otherwise returns an OS error.
Return type:: boolean

User and Group Information¶

get-username¶

(get-username)

Returns the username associated with the effective UID of the running process.

Returns:: The username string, or #false if it cannot be determined.
Return type:: string or boolean

get-groups¶

(get-groups)

Returns an association list of all groups associated with the current process’s effective UID. Each element is a pair of (gid . “groupname”).

Returns:: An alist of group IDs and names.
Return type:: list

is-root?¶

(is-root?)

Returns #true if the process is running with root privileges (UID 0).

Returns:: #true or #false.
Return type:: boolean

Working Directory and Permissions¶

get-cwd¶

(get-cwd)

Returns the current working directory of the process.

Returns:: The absolute path of the current directory.
Return type:: string

chdir¶

(chdir path)

Changes the current working directory to path.

Parameters:: path (string) – The target directory path.
Returns:: #true on success, or an OS error.
Return type:: boolean

chmod¶

(chmod path mode)

Changes the permission bits of the file at path.

Parameters:

path (string) – The path to the file.
mode (integer) – The bitmask for the new permissions (typically provided as an octal integer).

Returns:

#true on success.

Return type:

boolean

Example

--> (chmod "script.sh" #o755)
  #true

System Metadata and Telemetry¶

uname¶

(uname)

Returns a 5-tuple (list) containing system and hardware platform information. The fields are: (sysname nodename release version machine).

Returns:: A list of 5 strings.
Return type:: list

uptime¶

(uptime)

Returns system uptime and load average statistics. Return value is a list which contains:

Total uptime in seconds (integer).
A human-readable uptime string.
A list of three floats representing the 1, 5, and 15-minute load averages.

Returns:: The results list.
Return type:: list

Example

--> (uptime)
  (2738231 "up 31 days 16:37" (0.15 0.10 0.05))

cpu-count¶

(cpu-count)

Returns the number of logical processors currently configured on the system.

Returns:: The number of CPUs.
Return type:: integer

get-hostname¶

(get-hostname)

Returns the system’s network hostname.

Returns:: The hostname string.
Return type:: string

Process Control¶

system¶

(system command)

Forks a new process and executes command using /bin/sh. This procedure blocks until the command completes.

Parameters:: command (string) – The shell command to execute.
Returns:: The exit status of the command.
Return type:: integer

sleep¶

(sleep n)

Suspends the execution of the calling process for n seconds.

Parameters:: n (integer) – The number of seconds to sleep.
Returns:: Unspecified.
Return type:: void