std.env

Functions

pub fn arch(): string

Return OS architecture string.

Some possible values:

x86
x86_64
aarch64
arm

nv,

use std.env;

env.arch(); // "x86_64"

pub fn chdir(name: string) throws IoError

Change current working directory.

nv,

use std.env;

fn main() throws {
    try env.chdir("/home/username"); // ok
    try env.chdir("/a/not/exist/path"); // throw error
}

pub fn current_exe(): string throws IoError

Returns the full filesystem path of the current running executable.

Platform-specific behavior

If the executable was invoked through a symbolic link, some platforms will return the path of the symbolic link and other platforms will return the path of the symbolic link’s target.

If the executable is renamed while it is running, platforms may return the path at the time it was loaded instead of the new path.

Errors

Acquiring the path of the current executable is a platform-specific operation that can fail for a good number of reasons. Some errors can include, but not be limited to, filesystem operations failing or general syscall failures.

Security

The output of this function should not be trusted for anything that might have security implications. Basically, if users can run the executable, they can change the output arbitrarily.

As an example, you can easily introduce a race condition. It goes like this:

You get the path to the current executable using current_exe(), and store it in a variable.
Time passes. A malicious actor removes the current executable, and replaces it with a malicious one.
You then use the stored path to re-execute the current executable.

You expected to safely execute the current executable, but you're instead executing something completely different. The code you just executed run with your privileges.

This sort of behavior has been known to lead to privilege escalation when used incorrectly.

Examples

nv,

use std.env;
use std.io;

fn main() throws {
    println(try env.current_exe());
    // "/home/username"
}

pub fn cwd(): string throws IoError

Return current working directory.

nv,

use std.env;
use std.io;

fn main() throws {
    println(try env.cwd());
    // "/home/username"
}

pub fn expand(s: string): string

Return replaces ${var} or $var in the string according to the values of the current environment variables. References to undefined variables are replaced by the empty string.

nv,

use std.env;

env.set("MY_ENV", "hello");
env.expand("$MY_ENV world"); // "hello world"
env.expand("${MY_ENV} world"); // "hello world"

pub fn get(name: string): string?

Return value from OS environment variable.

If the variable is not set, return nil.

nv,

use std.env;

env.get("HOME"); // "/home/username"
env.get("NOT_EXIST_ENV_KEY"); // nil

pub fn join_paths(paths: ..string): string throws IoError

Joins a collection of Paths appropriately for the PATH environment variable.

Errors

if one of the input Paths contains an invalid character for constructing the PATH variable (a double quote on Windows or a colon on Unix), or if the system does not have a PATH-like variable.

nv,

use std.env;

let joined_path = try! env.join_paths("/usr/bin", "/usr/local/bin", "~/.bin");

if (env.platform() == "windows") {
    assert_eq joined_path, "/usr/bin;/usr/local/bin;~/.bin";
} else {
    assert_eq joined_path, "/usr/bin:/usr/local/bin:~/.bin";
}

pub fn platform(): string

Return OS platform string.

Some possible values:

linux
macos
windows

nv,

use std.env;

env.platform(); // "linux"

pub fn remove(name: string)

Remove OS environment variable.

nv,

use std.env;

env.remove("MY_ENV");
env.get("MY_ENV"); // nil

pub fn set(name: string, value: string)

Set value to OS environment variable.

nv,

use std.env;

env.set("MY_ENV", "value");
env.get("MY_ENV"); // "value"

pub fn tmpdir(): string

Return tmp directory path of the system.

nv,

use std.env;

env.tmpdir(); // "/tmp"

pub fn vars(): <string, string>

Get all env variables, return <string, string>

nv,

use std.env;

let vars = env.vars();
// vars is a { "ENV1": "...", "ENV2": "..." }