org.freedesktop.portal.Flatpak: Flatpak Library Reference Manual

org.freedesktop.portal.Flatpak

org.freedesktop.portal.Flatpak — Flatpak portal

Methods

Spawn               (IN  ay    cwd_path,
                     IN  aay   argv,
                     IN  a{uh} fds,
                     IN  a{ss} envs,
                     IN  u     flags,
                     IN  a{sv} options,
                     OUT u     pid);
SpawnSignal         (IN  u     pid,
                     IN  u     signal,
                     IN  b     to_process_group);
CreateUpdateMonitor (IN  a{sv} options,
                     OUT o     handle);

Signals

SpawnStarted (u pid,
              u relpid);
SpawnExited  (u pid,
              u exit_status);

Properties

version   readable   u
supports  readable   u

Description

The flatpak portal exposes some interactions with flatpak on the host to the sandbox. For example, it allows you to restart the applications or start a more sandboxed instance.

This portal is available on the D-Bus session bus under the bus name org.freedesktop.portal.Flatpak and the object path /org/freedesktop/portal/Flatpak.

This documentation describes version 7 of this interface.

Method Details

The Spawn() method

Spawn (IN  ay    cwd_path,
       IN  aay   argv,
       IN  a{uh} fds,
       IN  a{ss} envs,
       IN  u     flags,
       IN  a{sv} options,
       OUT u     pid);

`IN ay cwd_path`:
`IN aay argv`:
`IN a{uh} fds`:
`IN a{ss} envs`:
`IN u flags`:
`IN a{sv} options`:
`OUT u pid`:

The SpawnSignal() method

SpawnSignal (IN  u pid,
             IN  u signal,
             IN  b to_process_group);

This method lets you send a Unix signal to a process that was started with Spawn(). The pid argument here should be the PID that is returned by the Spawn() call: it is not necessarily valid in the caller's PID namespace.

`IN u pid`:	the PID inside the container to signal
`IN u signal`:	the signal to send (see signal(7))
`IN b to_process_group`:	whether to send the signal to the process group

The CreateUpdateMonitor() method

CreateUpdateMonitor (IN  a{sv} options,
                     OUT o     handle);

Creates an update monitor object that will emit signals when an update for the caller becomes available, and can be used to install it.

The handle will be of the form /org/freedesktop/portal/Flatpak/update_monitor/SENDER/TOKEN, where SENDER is the caller's unique name, with the initial ':' removed and all '.' replaced by '_', and TOKEN is a unique token that the caller can optionally provide with the 'handle_token' key in the options vardict.

Currently, no other options are accepted.

This was added in version 2 of this interface (available from flatpak 1.5.0 and later).

`IN a{sv} options`:	Vardict with optional further information
`OUT o handle`:	Object path for the org.freedesktop.portal.Flatpak.UpdateMonitor object

Signal Details

The "SpawnStarted" signal

SpawnStarted (u pid,
              u relpid);

This is only non-zero if the expose PIDs flag (32) or the share PIDs flag (128) was passed to Spawn(), and it may still be zero if the process exits before its relative PID could be read.

Emitted when a process started by Spawn() has fully started. In other words, Spawn() returns once the sandbox has been started, and this signal is emitted once the process inside itself is started.

Only emitted by version 4 of this interface (available from flatpak 1.8.0 and later) and if the notify start flag (64) was passed to Spawn().

`u pid`:	the PID of the process that has been started
`u relpid`:	the PID of the process relative to the current namespace.

The "SpawnExited" signal

SpawnExited (u pid,
             u exit_status);

Emitted when a process started by Spawn() exits. Use g_spawn_check_exit_status(), or the macros such as WIFEXITED documented in waitpid(2), to interpret the exit_status.

This signal is not emitted for processes that were not launched directly by Spawn(), for example if a process launched by Spawn() runs foreground or background child processes.

`u pid`:	the PID of the process that has ended
`u exit_status`:	the wait status (see waitpid(2))

Property Details

The "version" property

version  readable   u

The "supports" property

supports  readable   u

Flags marking what optional features are available. The following flags values are supported:

1 (FLATPAK_SPAWN_SUPPORT_FLAGS_EXPOSE_PIDS)

Supports the expose sandbox pids flag of Spawn. If the version of this interface is 5 or later, this also indicates that the share sandbox pids flag is available.

This was added in version 3 of this interface (available from flatpak 1.6.0 and later).