Spawn: libportal Reference Manual

## Spawn Spawn — launch another sandbox |

## Functions

void | xdp_portal_spawn ()
pid_t | xdp_portal_spawn_finish ()
void | xdp_portal_spawn_signal ()

## Types and Values

enum | XdpSpawnFlags

## Description

These functions let applications spawn a process in another copy of their sandbox.

To monitor spawned processes, use the “spawn-exited” signal.

The underlying portal is org.freedesktop.portal.Flatpak.

## Functions

### xdp_portal_spawn ()

    void
    xdp_portal_spawn (XdpPortal *portal,
                      const char *cwd,
                      const char * const *argv,
                      int *fds,
                      int *map_to,
                      int n_fds,
                      const char * const *env,
                      XdpSpawnFlags flags,
                      const char * const *sandbox_expose,
                      const char * const *sandbox_expose_ro,
                      GCancellable *cancellable,
                      GAsyncReadyCallback callback,
                      gpointer data);

Creates a new copy of the applications sandbox, and runs a process in, with the given arguments.

The learn when the spawned process exits, connect to the “spawn-exited” signal.

#### Parameters

portal | a XdpPortal |
cwd | the cwd for the new process |
argv | the argv for the new process. | [array zero-terminated]
fds | an array of open fds to pass to the new process, or `NULL`. | [array length=n_fds][nullable]
map_to | an array of integers to map the `fds` to, or `NULL`. Must be the same length as `fds` . | [array length=n_fds][nullable]
n_fds | the length of `fds` and `map_to` arrays |
env | an array of KEY=VALUE environment settings, or `NULL`. | [array zero-terminated][nullable]
flags | flags influencing the spawn operation |
sandbox_expose | paths to expose rw in the new sandbox, or `NULL`. | [array zero-terminated][nullable]
sandbox_expose_ro | paths to expose ro in the new sandbox, or `NULL`. | [array zero-terminated][nullable]
cancellable | optional GCancellable. | [nullable]
callback | a callback to call when the request is done. | [scope async]
data | data to pass to `callback` . | [closure]

### xdp_portal_spawn_finish ()

    pid_t
    xdp_portal_spawn_finish (XdpPortal *portal,
                             GAsyncResult *result,
                             GError **error);

Finishes the spawn request, and returns the pid of the newly spawned process.

#### Parameters

portal | a XdpPortal |
result | a GAsyncResult |
error | return location for an error |

#### Returns

the pid of the spawned process.

### xdp_portal_spawn_signal ()

    void
    xdp_portal_spawn_signal (XdpPortal *portal,
                             pid_t pid,
                             int signal,
                             gboolean to_process_group);

Sends a Unix signal to a process that has been spawned by `xdp_portal_spawn()`.

#### Parameters

portal | a XdpPortal |
pid | the pid of the process to send a signal to |
signal | the Unix signal to send (see signal(7)) |
to_process_group | whether to send the signal to the process group of the process |

## Types and Values

### enum XdpSpawnFlags

Flags influencing the spawn operation and how the new sandbox is created.

#### Members

XDP_SPAWN_FLAG_CLEARENV | Clear the environment |
XDP_SPAWN_FLAG_LATEST | Spawn the latest version of the app |
XDP_SPAWN_FLAG_SANDBOX | Spawn in a sandbox (equivalent to the --sandbox option of flatpak run) |
XDP_SPAWN_FLAG_NO_NETWORK | Spawn without network (equivalent to the --unshare=network option of flatpak run) |
XDP_SPAWN_FLAG_WATCH | Kill the sandbox when the caller disappears from the session bus |