Skip to Content
wasix.by
CTRL K
Install WASIX
DocumentationAPI ReferenceWASIXproc_spawn
WASIX / API REFERENCE

proc_spawn()

Spawns a new process within the context of this machine.

Description

The proc_spawn() function is used to spawn a new process within the context of the current machine. It creates a new process with the specified parameters, such as the process name, arguments, preopens, working directory, and I/O handling. The function returns the bus handles associated with the spawned process.

In POSIX systems, spawn() is a common function used to create new processes. It allows specifying various attributes for the new process, such as the program to execute, command-line arguments, environment variables, working directory, file descriptors, and more.

Syntax

  ;;; permissions but runs standalone.
  ;;; (i.e. this process). It inherits the filesystem and sandbox
  ;;; Spawns a new process within the context of the parent process
  (@interface func (export "proc_spawn")
    ;;; Name of the process to be spawned
    (param $name string)
    ;;; Indicates if the process will chroot or not
    (param $chroot $bool)
    ;;; List of the arguments to pass the process
    ;;; (entries are separated by line feeds)
    (param $args string)
    ;;; List of the preopens for this process
    ;;; (entries are separated by line feeds)
    (param $preopen string)
    ;;; How will stdin be handled
    (param $stdin $stdio_mode)
    ;;; How will stdout be handled
    (param $stdout $stdio_mode)
    ;;; How will stderr be handled
    (param $stderr $stdio_mode)
    ;;; Working directory where this process should run
    ;;; (passing '.' will use the current directory)
    (param $working_dir string)
    ;;; Returns a bus process id that can be used to invoke calls
    (result $error (expected $process_handles (error $errno)))
  )

Parameters

  • ctx: A mutable reference to the function environment.
  • name: Name of the process to be spawned.
  • name_len: Length of the name parameter.
  • chroot: Indicates if the process will chroot or not.
  • args: List of the arguments to pass the process (entries are separated by line feeds).
  • args_len: Length of the args parameter.
  • preopen: List of the preopens for this process (entries are separated by line feeds).
  • preopen_len: Length of the preopen parameter.
  • stdin: How stdin will be handled.
  • stdout: How stdout will be handled.
  • stderr: How stderr will be handled.
  • working_dir: Working directory where this process should run (passing ’.’ will use the current directory).
  • working_dir_len: Length of the working_dir parameter.
  • ret_handles: Pointer to store the returned bus handles.

Return Value

The function returns Result<BusErrno, WasiError>. If the operation is successful, it returns Ok(BusErrno::Success). Otherwise, it returns an appropriate BusErrno or WasiError value.

Note

  • The proc_spawn() function is used to create a new process within the context of the current machine.
  • It supports various attributes for the new process, such as the process name, arguments, preopens, working directory, and I/O handling.
  • The function returns the bus handles associated with the spawned process, which can be used to invoke further calls on the process.
  • If chroot is set to Bool::True, indicating a chroot operation, a warning message will be logged as chroot is not currently supported.
  • After spawning the process, the function stores the bus handles in the specified ret_handles pointer.
  • The function calls WasiEnv::process_signals_and_exit() to process any pending signals and handle process termination if necessary.
proc_execproc_id