---
title: "proc_spawn()"
description: "Spawns a new process within the context of this machine."
url: "https://wasix.org/docs/api-reference/wasix/proc_spawn/"
markdown: "https://wasix.org/docs/api-reference/wasix/proc_spawn.md"
---

# `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

```ebnf
  ;;; 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.

---

[Documentation index](https://wasix.org/llms.txt) · [HTML version](https://wasix.org/docs/api-reference/wasix/proc_spawn/)