# os

> Operating-system access — environment, process info, signals, permissions, syscall info, and args.

# os

The `os` module exposes the host environment, process information, signal trapping, file permissions, low-level system info, command-line arguments, and process exit. It is organized into submodules with flat top-level shortcuts for common needs. Import it with `import os`.

## os.env

| Function | Signature | Description |
| --- | --- | --- |
| `get` | `os.env.get(key: string) → string` | value of an environment variable (empty if unset) |
| `set` | `os.env.set(key: string, value: string) → bool` | set an environment variable |
| `unset` | `os.env.unset(key: string) → bool` | remove an environment variable |
| `has` | `os.env.has(key: string) → bool` | true if the variable is defined |
| `all` | `os.env.all() → string` | all variables as a JSON object string |

## os.process

| Function | Signature | Description |
| --- | --- | --- |
| `pid` | `os.process.pid() → int` | current process ID |
| `ppid` | `os.process.ppid() → int` | parent process ID |
| `uid` | `os.process.uid() → int` | user ID |
| `gid` | `os.process.gid() → int` | group ID |
| `exit` | `os.process.exit(code?: int) → void` | exit the process with `code` (default 0) |
| `args` | `os.process.args() → string[]` | command-line arguments |
| `cwd` | `os.process.cwd() → string` | current working directory |
| `chdir` | `os.process.chdir(dir: string) → bool` | change the working directory |

## os.signal

| Function | Signature | Description |
| --- | --- | --- |
| `notify` | `os.signal.notify() → void` | start trapping SIGINT/SIGTERM/SIGHUP |
| `trap` | `os.signal.trap() → string` | name of the last received signal (empty if none) |
| `reset` | `os.signal.reset() → void` | clear the recorded last signal |

## os.permission

| Function | Signature | Description |
| --- | --- | --- |
| `readable` | `os.permission.readable(path: string) → bool` | true if the path can be opened for reading |
| `writable` | `os.permission.writable(path: string) → bool` | true if the path can be opened for writing |
| `executable` | `os.permission.executable(path: string) → bool` | true if any execute bit is set |
| `chmod` | `os.permission.chmod(path: string, mode: int) → bool` | change file mode bits |

## os.syscall

| Function | Signature | Description |
| --- | --- | --- |
| `arch` | `os.syscall.arch() → string` | CPU architecture (e.g. "arm64") |
| `os` | `os.syscall.os() → string` | operating system (e.g. "darwin") |
| `hostname` | `os.syscall.hostname() → string` | machine hostname |
| `pagesize` | `os.syscall.pagesize() → int` | memory page size in bytes |
| `numCPU` | `os.syscall.numCPU() → int` | number of logical CPUs |

## os.args

| Function | Signature | Description |
| --- | --- | --- |
| `all` | `os.args.all() → string[]` | all command-line arguments |
| `get` | `os.args.get(idx: int) → string` | argument at `idx` (empty if out of range) |
| `len` | `os.args.len() → int` | number of arguments |

## os.exit

| Function | Signature | Description |
| --- | --- | --- |
| `code` | `os.exit.code(code?: int) → void` | exit with `code` (default 0) |
| `success` | `os.exit.success() → void` | exit with code 0 |
| `failure` | `os.exit.failure() → void` | exit with code 1 |

## Top-level shortcuts

| Function | Signature | Description |
| --- | --- | --- |
| `getenv` | `os.getenv(key: string) → string` | read an environment variable |
| `setenv` | `os.setenv(key: string, value: string) → bool` | set an environment variable |
| `hostname` | `os.hostname() → string` | machine hostname |
| `arch` | `os.arch() → string` | CPU architecture |
| `platform` | `os.platform() → string` | operating system |
| `exitCode` | `os.exitCode(code?: int) → void` | exit with `code` (default 0) |
| `pid` | `os.pid() → int` | current process ID |

## Example

```goost
import os

print(os.platform())                  // darwin
print(os.getenv("HOME"))

// trap shutdown signals in a long-running program
os.signal.notify()
if os.signal.trap() == "interrupt" {
    os.exit.success()
}
```