# bare-os



<mark style="{ backgroundColor: '#7dde9a', padding: '2px 8px', borderRadius: '4px', fontSize: '0.85em', fontWeight: 500 }">
  stable
</mark>

[`bare-os`](https://github.com/holepunchto/bare-os) exposes operating-system information and process utilities for [Bare](/bare/reference/bare/runtime), closely mirroring the Node.js `os` module so most Node code ports directly.

Mirrors the Node.js [`os`](https://nodejs.org/api/os.html) module.

```sh
npm i bare-os
```

## Usage [#usage]

```js
const os = require('bare-os')

console.log(os.platform()) // 'darwin', 'linux', 'win32', ...
console.log(os.arch()) // 'arm64', 'x64', ...
console.log(os.homedir())
console.log(os.tmpdir())
console.log(os.hostname())
console.log(os.networkInterfaces())
```

## API [#api]

### System and platform [#system-and-platform]

#### `platform(): 'android' | 'darwin' | 'ios' | 'linux' | 'win32'` [#platform-android--darwin--ios--linux--win32]

Returns the operating system platform as a string. Possible values include `'android'`, `'darwin'`, `'ios'`, `'linux'`, and `'win32'`.

#### `arch(): 'arm' | 'arm64' | 'ia32' | 'x64'` [#arch-arm--arm64--ia32--x64]

Returns the CPU architecture as a string. Possible values include `'arm'`, `'arm64'`, `'ia32'`, and `'x64'`.

#### `type(): string` [#type-string]

Returns the operating system name as returned by `uname(3)`.

#### `version(): string` [#version-string]

Returns the operating system version.

#### `release(): string` [#release-string]

Returns the operating system release.

#### `machine(): string` [#machine-string]

Returns the machine type as a string.

#### `endianness(): 'LE' | 'BE'` [#endianness-le--be]

Returns `'LE'` on little-endian systems and `'BE'` on big-endian systems.

#### `availableParallelism(): number` [#availableparallelism-number]

Returns the number of logical CPU cores available to the process.

### Process and scheduling [#process-and-scheduling]

#### `pid(): number` [#pid-number]

Returns the process ID.

#### `ppid(): number` [#ppid-number]

Returns the parent process ID.

#### `cwd(): string` [#cwd-string]

Returns the current working directory.

#### `chdir(dir: string): void` [#chdirdir-string-void]

Changes the current working directory to `dir`.

**Parameters**

| Parameter | Type     | Default | Description                                              |
| --------- | -------- | ------- | -------------------------------------------------------- |
| `dir`     | `string` | —       | Path of the directory to make the new working directory. |

**Throws**

* Thrown with the underlying system error code (for example `ENOENT`) when `dir` does not exist or cannot be entered.

#### `execPath(): string` [#execpath-string]

Returns the absolute path of the executable that started the process.

#### `kill(pid: number, signal?: string | number): void` [#killpid-number-signal-string--number-void]

Sends `signal` to the process identified by `pid`. `signal` can be a string or a number. Defaults to `'SIGTERM'`.

**Parameters**

| Parameter | Type                 | Default | Description                                                                                                           |
| --------- | -------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `pid`     | `number`             | —       | Process id to signal.                                                                                                 |
| `signal?` | `string` \| `number` | —       | Signal name or number to send (default `'SIGTERM'`); `0` probes for the process's existence without sending a signal. |

**Throws**

* `UNKNOWN_SIGNAL` — Thrown as an `OSError` when `signal` is a string that is not a recognized signal name.
* Thrown with the underlying system error code (for example `ESRCH`) when `pid` does not identify a running process.

#### `getProcessTitle(): string` [#getprocesstitle-string]

Returns the current process title.

#### `setProcessTitle(title: unknown): void` [#setprocesstitletitle-unknown-void]

Sets the process title. `title` is coerced to a string and must be shorter than 256 characters.

**Parameters**

| Parameter | Type      | Default | Description                                                |
| --------- | --------- | ------- | ---------------------------------------------------------- |
| `title`   | `unknown` | —       | New process title; coerced to a string if not already one. |

**Throws**

* `TITLE_OVERFLOW` — Thrown as an `OSError` when the process title is 256 characters or longer.

#### `getPriority(pid?: number): number` [#getprioritypid-number-number]

Returns the scheduling priority of the process specified by `pid`. Defaults to `0`, meaning the current process.

**Parameters**

| Parameter | Type     | Default | Description                                                 |
| --------- | -------- | ------- | ----------------------------------------------------------- |
| `pid?`    | `number` | —       | Process id to query; defaults to `0` (the current process). |

#### `setPriority(priority: number): void` [#setprioritypriority-number-void]

Sets the scheduling priority of the process specified by `pid`. If `pid` is omitted, the priority of the current process is set.

Overloads:

```ts
setPriority(priority: number): void
setPriority(pid: number, priority: number): void
```

**Parameters**

| Parameter  | Type     | Default | Description                                                             |
| ---------- | -------- | ------- | ----------------------------------------------------------------------- |
| `priority` | `number` | —       | Nice value to set (the current process, when called with one argument). |

### Users and network [#users-and-network]

#### `userInfo(uid?: number): UserInfo` [#userinfouid-number-userinfo]

Returns information about a current user. The `uid` value defaults to the current effective uid.

**Parameters**

| Parameter | Type     | Default | Description                                                |
| --------- | -------- | ------- | ---------------------------------------------------------- |
| `uid?`    | `number` | —       | User ID to look up; defaults to the current effective uid. |

#### `groupInfo(gid?: number): GroupInfo | null` [#groupinfogid-number-groupinfo--null]

Returns information about a group. The `gid` value defaults to the effective group ID of the calling process.

**Parameters**

| Parameter | Type     | Default | Description                                                                     |
| --------- | -------- | ------- | ------------------------------------------------------------------------------- |
| `gid?`    | `number` | —       | Group ID to look up; defaults to the effective group ID of the calling process. |

**Returns** [`GroupInfo`](#groupinfo) | `null` — `null` on platforms that do not support group lookups (for example, Windows).

#### `hostname(): string` [#hostname-string]

Returns the hostname of the operating system.

#### `networkInterfaces(): Record<string, NetworkInterface[]>` [#networkinterfaces-recordstring-networkinterface]

Returns an object containing network interfaces that have been assigned a network address. Each key on the returned object identifies a network interface.

### Memory and CPU [#memory-and-cpu]

#### `cpus` [#cpus]

```ts
cpus(): {
  model: string
  speed: number
  times: {
    user: number
    nice: number
    sys: number
    idle: number
    irq: number
  }
}[]
```

Returns an array of objects describing each logical CPU core.

#### `cpuUsage(previous?: CpuUsage): CpuUsage` [#cpuusageprevious-cpuusage-cpuusage]

Returns an object with `user` and `system` properties, each representing CPU time in microseconds. If `previous` is provided, the returned values are relative to it.

**Parameters**

| Parameter   | Type                    | Default | Description                                                        |
| ----------- | ----------------------- | ------- | ------------------------------------------------------------------ |
| `previous?` | [`CpuUsage`](#cpuusage) | —       | A previous `CpuUsage` snapshot to compute a relative diff against. |

#### `threadCpuUsage(previous?: CpuUsage): CpuUsage` [#threadcpuusageprevious-cpuusage-cpuusage]

Like `os.cpuUsage()` but for the current thread only.

**Parameters**

| Parameter   | Type                    | Default | Description                                                                                  |
| ----------- | ----------------------- | ------- | -------------------------------------------------------------------------------------------- |
| `previous?` | [`CpuUsage`](#cpuusage) | —       | A previous `CpuUsage` snapshot (from `threadCpuUsage()`) to compute a relative diff against. |

#### `resourceUsage` [#resourceusage]

```ts
resourceUsage(): {
  userCPUTime: number
  systemCPUTime: number
  maxRSS: number
  sharedMemorySize: number
  unsharedDataSize: number
  unsharedStackSize: number
  minorPageFault: number
  majorPageFault: number
  swappedOut: number
  fsRead: number
  fsWrite: number
  ipcSent: number
  ipcReceived: number
  signalsCount: number
  voluntaryContextSwitches: number
  involuntaryContextSwitches: number
}
```

Returns an object describing the resource usage of the current process.

#### `memoryUsage` [#memoryusage]

```ts
memoryUsage(): {
  rss: number
  heapTotal: number
  heapUsed: number
  external: number
}
```

Returns an object describing the memory usage of the process.

#### `freemem(): number` [#freemem-number]

Returns the amount of free system memory in bytes.

#### `totalmem(): number` [#totalmem-number]

Returns the total amount of system memory in bytes.

#### `availableMemory(): number` [#availablememory-number]

Returns an estimate of the amount of memory available for the process in bytes.

#### `constrainedMemory(): number` [#constrainedmemory-number]

Returns the amount of memory available to the process under resource constraints, such as cgroups.

#### `uptime(): number` [#uptime-number]

Returns the system uptime in seconds.

#### `loadavg(): ArrayLike<number>` [#loadavg-arraylikenumber]

Returns an array containing the 1, 5, and 15 minute load averages.

### Directories [#directories]

#### `tmpdir(): string` [#tmpdir-string]

Returns the operating system's default directory for temporary files.

#### `homedir(): string` [#homedir-string]

Returns the home directory of the current user.

### Environment variables [#environment-variables]

#### `getEnvKeys(): string[]` [#getenvkeys-string]

Returns an array of the names of all environment variables.

#### `getEnv(name: string): string | undefined` [#getenvname-string-string--undefined]

Returns the value of the environment variable `name`, or `undefined` if it is not set.

**Parameters**

| Parameter | Type     | Default | Description                               |
| --------- | -------- | ------- | ----------------------------------------- |
| `name`    | `string` | —       | Name of the environment variable to read. |

#### `hasEnv(name: string): boolean` [#hasenvname-string-boolean]

Returns `true` if the environment variable `name` is set, otherwise `false`.

**Parameters**

| Parameter | Type     | Default | Description                                |
| --------- | -------- | ------- | ------------------------------------------ |
| `name`    | `string` | —       | Name of the environment variable to check. |

#### `setEnv(name: string, value: string): void` [#setenvname-string-value-string-void]

Sets the environment variable `name` to `value`.

**Parameters**

| Parameter | Type     | Default | Description                                  |
| --------- | -------- | ------- | -------------------------------------------- |
| `name`    | `string` | —       | Name of the environment variable to set.     |
| `value`   | `string` | —       | Value to assign to the environment variable. |

#### `unsetEnv(name: string): void` [#unsetenvname-string-void]

Removes the environment variable `name`.

**Parameters**

| Parameter | Type     | Default | Description                                 |
| --------- | -------- | ------- | ------------------------------------------- |
| `name`    | `string` | —       | Name of the environment variable to remove. |

### Constants [#constants]

#### `EOL: '\r\n' | '\n'` [#eol-rn--n]

The platform-specific end-of-line marker: `'\r\n'` on Windows, `'\n'` everywhere else.

#### `devNull: '\\\\.\\nul' | '/dev/null'` [#devnull-nul--devnull]

The platform-specific path to the null device: `'\\.\nul'` on Windows, `'/dev/null'` everywhere else.

#### `constants` [#constants-1]

```ts
constants: {
  signals: Record<string, number>
  errnos: Record<string, number>
  priority: Record<string, number>
}
```

An object of signal, error-number, and process-priority constants.

#### `errors` [#errors]

```ts
class errors {
  code: string
}
```

### Types [#types]

#### `NetworkInterface` [#networkinterface]

```ts
interface NetworkInterface {
  address: string
  netmask: string
  family: 'IPv4' | 'IPv6'
  cidr: string
  mac: string
  internal: boolean
  scopeid?: number
}
```

#### `UserInfo` [#userinfo]

```ts
interface UserInfo {
  uid: number
  gid: number
  username: string
  homedir: string
  shell: string | null
}
```

#### `GroupInfo` [#groupinfo]

```ts
interface GroupInfo {
  groupname: string
  gid: number
  members: string[]
}
```

#### `CpuUsage` [#cpuusage]

```ts
interface CpuUsage {
  user: number
  system: number
}
```

## `bare-os/constants` [#bare-osconstants]

### Constants and variables [#constants-and-variables]

#### `constants.constants` [#constantsconstants]

```ts
constants: {
  signals: Record<string, number>
  errnos: Record<string, number>
  priority: Record<string, number>
}
```

An object of signal, error-number, and process-priority constants.

## `bare-os/errors` [#bare-oserrors]

### Classes [#classes]

#### `OSError` [#oserror]

```ts
class OSError {
  code: string
}
```

## See also [#see-also]

* [`bare-process`](/bare/reference/bare/modules/bare-process) — process-level control that complements these OS utilities.
* The higher-level `bare-env` wraps `getEnv`/`setEnv`/etc. into a `process.env`-style object.
* [Bare runtime API](/bare/reference/bare/runtime) — `Bare.platform` and `Bare.arch` for compile-time identifiers.
* [Bare modules](/bare/reference/bare/modules) — the full `bare-*` catalog.
* [Bare runtime API](/bare/reference/bare/runtime) — the runtime these modules extend.