# sys

> Find out which operating system, machine and user your program runs on, and open a URL in the default app.

This is the Markdown version of https://osl-lang.org/packages/sys. Every page of the OSL docs has one: add .md to its path. https://osl-lang.org/llms.txt lists them all.

```osl
import "std:sys"
```

`sys` answers "where am I running?": the operating system, the processor, the user and the machine. Use it to pick a path or a command that differs between systems, or to open a link in the browser.

```osl
import "std:sys"
```

## What system is this?

`sys.os()` and `sys.arch()` return short names such as `linux`, `darwin` (macOS), `windows`, `amd64` and `arm64`. The answer depends on the machine, so this example is marked as varying: run it and see your own.

```osl
import "std:sys"

log sys.os() sys.arch()
log sys.cpus() "logical CPUs"
```

Its output changes from run to run.

> **Tip**
>
> Edit the example and print `sys.os() == "linux"`. Comparing strings in OSL ignores case.

## Branch on the system

The common use is a decision. This picks the command that lists files:

```osl
import "std:sys"

def listCommand() string (
  if sys.os() == "windows" return "dir"
  return "ls"
)

log listCommand().len > 0
log sys.cpus() >= 1
```

Output:

```text
true
true
```

## The user and the machine

`username`, `homeDir` and `hostname` are [results](/learn/errors.md), because the system might not know. `uid` and `gid` are numbers, or `null` on Windows, which has no such IDs.

```osl
import "std:sys"

log sys.username().unwrapOr("unknown")
log sys.homeDir().unwrapOr("no home")
log sys.hostname().unwrapOr("no name")
log sys.uid() sys.gid()
```

Its output changes from run to run.

Facts about the machine make poor test data, so print stable properties instead. These always hold:

```osl
import "std:sys"

log sys.username().isOk()
log sys.homeDir().unwrap().startsWith("/")
log sys.hostname().unwrap().len > 0
```

Output:

```text
true
true
true
```

Try it: build the path of a config file with `fs.joinPath(sys.homeDir().unwrap(), ".myapp.json")`, using [fs](/packages/fs.md).

## Open a URL

`sys.openURL(url)` opens a web address, or a `file://` path, in the default app and returns at once. It needs a desktop, so this example is compiled but not run.

```osl
import "std:sys"

switch sys.openURL("https://osl-lang.org") (
  case ok(_)
    log "opened"
  case err(e)
    log "could not open:" e.kind
)
```

A URL without a scheme (`osl-lang.org`) is a `ParseError`, and a system with no opener (`open`, `xdg-open`) gives `NotFoundError`.

**Quiz.** Why does `sys.username()` return a result instead of a string?

- [ ] Because user names can change while the program runs.
- [x] Because the system may have no record of the user, such as in a minimal container.
- [ ] Because it needs a network request.

Answer: Anything that asks the operating system can fail, so the failure is part of the type.

### Exercise: Describe this machine

Print `ok` if the machine has at least one CPU and the OS name is not empty, otherwise `strange`.

Starting code:

```osl
import "std:sys"

log sys.os()
```

It should print:

```text
ok
```

Hint 1: Combine two comparisons with `and`.

A solution:

```osl
import "std:sys"

if sys.cpus() >= 1 and sys.os() != "" (
  log "ok"
) else (
  log "strange"
)
```

## API reference

## API reference

Every member of `std:sys`, generated from the source of OSL.

### Functions

#### `sys.arch() string`

arch returns the processor architecture, such as "amd64" or "arm64".

#### `sys.chdir(string path) boolean`

**Deprecated.** Deprecated: use process.chdir(path) instead.

chdir changes the working directory and reports whether it worked.

#### `sys.cmd(string cmd, any ...args) string`

**Deprecated.** Deprecated: use process.exec(command, ...args) instead.

cmd runs a command and returns its stdout, or "" when it fails.

#### `sys.cpus() int`

cpus returns the number of logical CPUs.

#### `sys.getArgs() string[]`

**Deprecated.** Deprecated: use process.args() instead, which leaves out the program.

getArgs returns the program's arguments, starting with the program.

#### `sys.getCwd() string`

**Deprecated.** Deprecated: use process.cwd() instead.

getCwd returns the working directory, or "".

#### `sys.getEnv(string key) string`

**Deprecated.** Deprecated: use env.get(key) instead.

getEnv returns an environment variable, or "".

#### `sys.getExecutablePath() string`

**Deprecated.** Deprecated: use process.executable() instead.

getExecutablePath returns the program's path, or "".

#### `sys.getGid() int`

**Deprecated.** Deprecated: use sys.gid() instead.

getGid returns the group ID.

#### `sys.getHomeDir() string`

**Deprecated.** Deprecated: use sys.homeDir() instead.

getHomeDir returns the home directory, or "".

#### `sys.getPid() int`

**Deprecated.** Deprecated: use process.pid() instead.

getPid returns the current process ID.

#### `sys.getPpid() int`

**Deprecated.** Deprecated: use process.ppid() instead.

getPpid returns the parent process ID, or -1 when there is none.

#### `sys.getUid() int`

**Deprecated.** Deprecated: use sys.uid() instead.

getUid returns the user ID.

#### `sys.getUsername() string`

**Deprecated.** Deprecated: use sys.username() instead.

getUsername returns the user name, or "".

#### `sys.gid() int?`

gid returns the current user's numeric group ID, or null on Windows,
which has none.

#### `sys.homeDir() result<string, error>`

homeDir returns the current user's home directory. Fails with
NotFoundError when it isn't known.

#### `sys.hostname() result<string, error>`

hostname returns the machine's host name. Fails with IOError when the OS
can't report it.

#### `sys.openURL(string url) result<unit, error>`

openURL opens a URL (or a file path given as a file:// URL) in the
default app, such as the web browser, without waiting for it. Fails with
ParseError when url has no scheme or contains control characters, and
NotFoundError when the system's opener (open, xdg-open or rundll32)
isn't available.

#### `sys.os() string`

os returns the operating system: "linux", "darwin" (macOS), "windows",
"freebsd" and so on.

#### `sys.setEnv(string key, string value) boolean`

**Deprecated.** Deprecated: use env.set(key, value) instead.

setEnv sets an environment variable and reports whether it worked.

#### `sys.uid() int?`

uid returns the current user's numeric ID, or null on Windows, which
has none.

#### `sys.unsetEnv(string key) boolean`

**Deprecated.** Deprecated: use env.unset(key) instead.

unsetEnv removes an environment variable and reports whether it worked.

#### `sys.username() result<string, error>`

username returns the name of the user running the program. Fails with
NotFoundError when the OS has no record of the user.