sys

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

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.

main.osl

import "std:sys"

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

Click the code to edit it

Branch on the system#

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

main.osl

import "std:sys"

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

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

Click the code to edit it

The user and the machine#

username, homeDir and hostname are results, because the system might not know. uid and gid are numbers, or null on Windows, which has no such IDs.

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

Click the code to edit it

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

main.osl

import "std:sys"

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

Click the code to edit it

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

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.

main.osl

import "std:sys"

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

Click the code to edit it

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

Quick check

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

Your turn

Describe this machine

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

main.osl

import "std:sys"

log sys.os()

import "std:sys"

log sys.os()

Ctrl Enter runs

Expected output

ok

API reference#

23 members, generated from the std:sys source of OSL 9.3.0.

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.

Edit this page View as Markdown