---
title: "proc_join()"
description: "Joins the child process, blocking the current process until the child process finishes."
url: "https://wasix.org/docs/api-reference/wasix/proc_join/"
markdown: "https://wasix.org/docs/api-reference/wasix/proc_join.md"
---

# `proc_join()`

Joins the child process, blocking the current process until the child process finishes.

## Description

The `proc_join()` function is used to wait for a specific child process to finish execution before continuing with the parent process. It blocks the execution of the current process until the child process exits. The function retrieves the PID of the child process from the `pid_ptr` parameter. If the `pid` value is `None`, the function waits for any child process to exit. After the child process finishes, the function retrieves the exit status and writes it to the `status_ptr` parameter.

On POSIX systems, a similar functionality is provided by the `waitpid()` function. It allows a parent process to wait for a specific child process or any child process to exit. The `waitpid()` function is part of the POSIX standard and is widely supported across different platforms.

## Syntax

```ebnf
  ;;; the process that exited.
  ;;; for any subprocess to exit. PID will be populated with
  ;;; Passing none to PID will mean that the call will wait
  ;;;
  ;;; Wait for process to exit
  (@interface func (export "proc_join")
    ;;; ID of the process to wait on
    (param $pid (@witx pointer $option_pid))
    ;;; Flags that determine how the join behaves
    (param $flags $join_flags)
    ;;; Returns the status of the process
    (result $error (expected $join_status (error $errno)))
  )
```

## Parameters

- `ctx`: A mutable reference to the function environment.
- `pid_ptr`: A wasm pointer to an `OptionPid` structure representing the PID of the child process to wait on.
- `_flags`: Unused parameter.
- `status_ptr`: A wasm pointer to a `JoinStatus` structure where the exit status of the child process will be stored.

## Return Value

The function returns a `Result` indicating the success or failure of the operation. If the operation is successful, it returns `Ok(Errno::Success)`. Otherwise, it returns an appropriate `WasiError` value.

## Logging

This function is instrumented with `trace` level logging. It includes the following fields for debugging purposes:

- `pid`: The raw PID of the process.

## Notes

- The `proc_join()` function waits for the child process specified by the PID to finish execution.
- If the `pid` value is `None`, the function waits for any child process to exit.
- The function clears the existing values in the `pid_ptr` and `status_ptr` parameters.
- After the child process finishes, the function retrieves the exit status and writes it to the `status_ptr` parameter.
- The function uses an asynchronous approach with a deep sleep mechanism to avoid blocking for too long when waiting for the child process.
- On POSIX systems, a similar functionality is provided by the `waitpid()` function, which allows a parent process to wait for a specific child process or any child process to exit.

---

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