silk.platform.native.host_input.

When to use#

The native runtime captures a NativeHostInput at start, and gives it to main as an OsHostInput. Use NativeHostInput.environmentSnapshot in a library that gets no arguments, or NativeHostInput.capture in a custom runtime.

Details#

A capture copies all bytes, so later lookups do not use the memory of the process. The working directory is read at each call, not captured.

Errors#

HostInputError if the input is not valid. OutOfMemoryError if a copy cannot be allocated.

Gotchas#

• The capture functions are unsafe. The input vectors and their strings must stay readable and unchanged during the capture. No other code can change the environment at that time.

• The module is empty on targets other than Darwin on aarch64, and Linux with GNU libc on x86_64 or aarch64.

Examples#

Copy the environment#

import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.collections.bytes { Bytes }
import silk.core.effect { Effect }
import silk.system.host_input { HostInputError }
import silk.platform.native.host_input { NativeHostInput }
import silk.core.option { Option }

effect fn program() -> i32
  ! HostInputError | OutOfMemoryError
  ? &mut Allocator {
  // Copy the environment. No other code changes the environment now.
  let inputs = run unsafe NativeHostInput.environmentSnapshot()
  if NativeHostInput.argumentCount(&inputs) != 0 {
    return 1
  }

  // An empty output asks only for the length.
  let mut empty: [u8; 0] = []
  let missing = NativeHostInput.variable(&inputs, b"SILK_DOC_NOT_SET", &mut empty)
  match move missing {
    Option.Some { value: _ } => {
      return 1
    }
    Option.None => {}
  }
  let directory = run NativeHostInput.workingDirectory()
  if Bytes.length(&directory) == 0 {
    return 1
  }
  return 0
}

effect fn failed<E>(error: E) -> i32 {
  drop error
  return 1
}

pub fn main() -> i32 {
  let mut allocator = Allocator.systemAllocatorProvider()
  return run Effect.catchAll(program(), failed) |> Effect.provideMut<Allocator>(&mut allocator)
}

Import as NativeHostInput with import silk.platform.native.host_input { NativeHostInput }.

Public declarations: 1.

NativeHostInput#

pub struct NativeHostInput

An owned copy of the command-line arguments and the environment of the process.

When to use#

The native runtime captures one at start, and gives it to main as an OsHostInput. Use NativeHostInput.environmentSnapshot in a library that gets no arguments, or NativeHostInput.capture in a custom runtime.

Details#

A capture copies all bytes, so later lookups do not use the memory of the process. The working directory is read at each call, not captured.

Gotchas#

The capture functions are unsafe. The input vectors and their strings must stay readable and unchanged during the capture. No other code can change the environment at that time.

Implementation NativeHostInput#

impl NativeHostInput

Associated function environmentSnapshot#

pub unsafe effect fn environmentSnapshot() -> NativeHostInput ! HostInputError | OutOfMemoryError ? &mut Allocator

Copies the environment of the process, with no arguments.

Gotchas#

No other code can change the environment during the call. A null environment gives no variables.

Associated function captureProcess#

pub unsafe effect fn captureProcess(argc: i32, argv: [*]const ?[*]const u8) -> NativeHostInput ! HostInputError | OutOfMemoryError ? &mut Allocator

Copies argc arguments from argv, and the environment of the process.

Gotchas#

argv must have argc readable entries, each a NUL-terminated string that does not change. No other code can change the environment during the call. If it fails, all copies are freed.

Associated function capture#

pub unsafe effect fn capture(
      argc: i32,
      argv: [*]const ?[*]const u8,
      environment: [*]const ?[*]const u8
    ) -> NativeHostInput ! HostInputError | OutOfMemoryError ? &mut Allocator

Copies argc arguments from argv, and the entries of environment up to its null entry.

Gotchas#

Each non-null entry must be a NUL-terminated string that does not change during the call. If it fails, all copies are freed.

Method argumentCount#

pub fn argumentCount(self: &Self) -> usize

Returns the number of arguments, with the program name if there is one.

Method argument#

pub fn argument(self: &Self, index: usize, output: &mut [u8]) -> Option<usize>

Copies the start of argument index to output, and returns its full length, or None if there is no such argument.

Details#

An empty argument returns Some(0). If output is too short, only its length is copied, and the bytes after the copy are not changed.

Method variable#

pub fn variable(self: &Self, name: &[u8], output: &mut [u8]) -> Option<usize>

Copies the start of the value of the first variable named name to output, and returns its full length, or None.

Details#

The name must match byte for byte. An empty value returns Some(0). A name with NUL or = never matches. Entries without = are ignored.

Associated function workingDirectory#

pub effect fn workingDirectory() -> Bytes ! HostInputError | OutOfMemoryError ? &mut Allocator

Returns the current working directory of the process.

Details#

It starts with a 256-byte buffer, and makes it larger when the path does not fit, up to 1 MiB.

Errors#

OutOfMemoryError if a buffer cannot be allocated. HostInputError for other failures.

Associated function workingDirectoryCopy#

pub effect fn workingDirectoryCopy(output: &mut [u8]) -> usize ! HostInputError | OutOfMemoryError ? &mut Allocator

Copies the start of the working directory to output, and returns its full length. The bytes after the copy are not changed.

Category: Native platform.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, x86_64-unknown-linux-gnu.