diff --git a/bin/dialog.md b/bin/dialog.md index f208ea7a03f6770f947c09f5657b13a9c950a672..9cb19b4980fd8c919c17461108c592947219b1bf 100644 --- a/bin/dialog.md +++ b/bin/dialog.md @@ -62,45 +62,66 @@ to be installed as part of Steam itself, under the name **steam-dialog**. Exactly one mode argument must be provided. +<dl> +<dt> + **--check-features=**_FEATURES_ -: If **steam-runtime-dialog** supports all of the feature flags in the - space-separated string _FEATURES_, and a user interface backend - supporting the same features is found, then exit with status 0. - Otherwise, exit with a non-zero status. - - The known feature flags are: - - **message** - : The **--error**, **--warning** and **--info** modes are supported. - The **--title** and **--text** options are supported. - The **--width** and **--no-wrap** options are supported to at least - a basic level (they might be ignored, if they are not applicable - to a particular user interface). - - **progress** - : The **--progress** mode is supported. - The **--pulsate** option is supported. - The **--auto-close** and **--no-cancel** options are supported - to at least a basic level (they might be ignored or on-by-default). + +</dt><dd> + +If **steam-runtime-dialog** supports all of the feature flags in the +space-separated string _FEATURES_, and a user interface backend +supporting the same features is found, then exit with status 0. +Otherwise, exit with a non-zero status. + +The known feature flags are: + +**message** +: The **--error**, **--warning** and **--info** modes are supported. + The **--title** and **--text** options are supported. + The **--width** and **--no-wrap** options are supported to at least + a basic level (they might be ignored, if they are not applicable + to a particular user interface). + +**progress** +: The **--progress** mode is supported. + The **--pulsate** option is supported. + The **--auto-close** and **--no-cancel** options are supported + to at least a basic level (they might be ignored or on-by-default). + +</dd> +<dt> **--error**, **--warning**, **--info** -: Show an error, warning or informational message and wait for it to be - acknowledged. - These modes are part of the **message** feature flag. + +</dt><dd> + +Show an error, warning or informational message and wait for it to be +acknowledged. +These modes are part of the **message** feature flag. + +</dd> +<dt> **--progress** -: Show a progress bar. - This mode reads progress information from standard input. - Each line read is expected to be either: - - * an ASCII decimal integer or floating-point number between 0 and 100: - set the progress bar to the given percentage - * `#` followed by arbitrary UTF-8 text: change the **--text** to the - given message - * `pulsate:true`: instead of progress, do the equivalent of **--pulsate** - * `pulsate:false`: show progress instead of the equivalent of **--pulsate** - - This mode is part of the **progress** feature flag. + +</dt><dd> + +Show a progress bar. +This mode reads progress information from standard input. +Each line read is expected to be either: + +* an ASCII decimal integer or floating-point number between 0 and 100: + set the progress bar to the given percentage +* `#` followed by arbitrary UTF-8 text: change the **--text** to the + given message +* `pulsate:true`: instead of progress, do the equivalent of **--pulsate** +* `pulsate:false`: show progress instead of the equivalent of **--pulsate** + +This mode is part of the **progress** feature flag. + +</dd> +</dl> # OPTIONS diff --git a/bin/identify-library-abi.md b/bin/identify-library-abi.md index d22a0505805e92bf4352cc71798fb60ae259606a..78058b55454817de3db699393712bfeedb73cad4 100644 --- a/bin/identify-library-abi.md +++ b/bin/identify-library-abi.md @@ -27,7 +27,7 @@ steam-runtime-identify-library-abi - Identify the ABI of the libraries stored in : Identify the ABI of the libraries listed by the executable `ldconfig`. **--print0** -: The generated library_path=library_ABI pairs are terminated with a null +: The generated *library\_path*=*library\_ABI* pairs are terminated with a null character instead of a newline. **--skip-unversioned** @@ -41,9 +41,11 @@ steam-runtime-identify-library-abi - Identify the ABI of the libraries stored in # OUTPUT **steam-runtime-identify-library-abi** standard output is machine parsable, with -pairs of `library_path=library_ABI` separated by a null character, with the option +pairs of *library\_path*=*library\_ABI* separated by a null character, +with the option **--print0**, or by newlines. -Where `library_ABI` follows the Debian-style multiarch tuples convention and + +*library\_ABI* follows the Debian-style multiarch tuples convention and currently can have the following values: `i386-linux-gnu`, `x86_64-linux-gnu`, `x86_64-linux-gnux32`, `aarch64-linux-gnu`, or `?` that groups all the other possible ABIs. diff --git a/bin/input-monitor.md b/bin/input-monitor.md index 12fc92efe27f509c0046e33f7911be5bfaf47f35..db60da81154a7f5bcd654daf165e4b1ae1ea19a2 100644 --- a/bin/input-monitor.md +++ b/bin/input-monitor.md @@ -83,34 +83,61 @@ taking precedence. Each event is a JSON object with a single key. Consumers should ignore unknown keys to allow for future expansion. +<dl> +<dt> + **all-for-now** -: The initial device enumeration has finished. If the **--once** option - was used, **steam-runtime-input-monitor** will exit. If not, it will - contine to monitor device hotplug events. - The value is **true**. +</dt><dd> + +The initial device enumeration has finished. If the **--once** option +was used, **steam-runtime-input-monitor** will exit. If not, it will +contine to monitor device hotplug events. + +The value is **true**. + +</dd> +<dt> **added** -: A device was added. The value is an object describing the device, - with the following keys and values: - **dev_node** - : The device node in `/dev` for this device. +</dt><dd> + +A device was added. The value is an object describing the device, +with the following keys and values: + +**dev_node** +: The device node in `/dev` for this device. + +**sys_path** +: The device directory in `/sys` for this device. - **sys_path** - : The device directory in `/sys` for this device. +**subsystem** +: The Linux kernel subsystem, either **input** or **hidraw**. - **subsystem** - : The Linux kernel subsystem, either **input** or **hidraw**. +Additional keys and values are likely to be added in future versions. - Additional keys and values are likely to be added in future versions. +</dd> +<dt> **removed** -: A device was removed. The value is an object with keys **dev_node** - and **sys_path**, as above. + +</dt><dd> + +A device was removed. The value is an object with keys **dev_node** +and **sys_path**, as above. + +</dd> +<dt> **#** -: Informational messages which are not intended to be machine-readable. + +</dt><dd> + +Informational messages which are not intended to be machine-readable. + +</dd> +</dl> # EXIT STATUS diff --git a/bin/launch-options.md b/bin/launch-options.md index 58ac5337d1d8f6ee1e2a215c960ce80d4707441e..2df7b2a53979e68b2d6b1c498c683aa32331f19b 100644 --- a/bin/launch-options.md +++ b/bin/launch-options.md @@ -37,8 +37,17 @@ extension and appending **.py**. # OPTIONS +<dl> +<dt> + **--verbose** -: Show additional information. + +</dt><dd> + +Show additional information. + +</dd> +</dl> # EXIT STATUS diff --git a/bin/launcher-interface-0.md b/bin/launcher-interface-0.md index c109bd74d72d2c189c499c40b3c702b7efc2f4e0..d39e44a3ddf3bf5b986b17a3b4b7702bdac64303 100644 --- a/bin/launcher-interface-0.md +++ b/bin/launcher-interface-0.md @@ -59,41 +59,68 @@ version of the Steam Runtime, the tool should be renamed to # ENVIRONMENT +<dl> +<dt> + `STEAM_COMPAT_LAUNCHER_SERVICE` (string) -: A tool name which is matched against the first parameter. + +</dt><dd> + +A tool name which is matched against the first parameter. + +</dd> +<dt> `SRT_LAUNCHER_SERVICE_STOP_ON_EXIT` (boolean) -: By default, or if set to `1`, the **steam-runtime-launcher-service**(1) - will terminate other launched processes and prepare to exit when - the *COMMAND* does. - This is appropriate when interacting with a game or other program - that is mostly working: it cleans up any associated debugging - processes when the game itself exits, so that Steam will correctly - conside the game to have exited. - - If set to `0`, the **steam-runtime-launcher-service**(1) will not - stop until it is explicitly terminated by **SIGTERM** or - **steam-runtime-launch-client --bus-name=... --terminate**. - This is particularly useful when debugging a game that crashes or - otherwise exits on startup. - As long as the **steam-runtime-launcher-service**(1) continues - to run, Steam will behave as though the game was still running: - the user is responsible for terminating the service when it is no - longer needed. - - This is a generic **steam-runtime-launcher-service**(1) option, - and is not specific to **steam-runtime-launcher-interface-0**. + +</dt><dd> + +By default, or if set to `1`, the **steam-runtime-launcher-service**(1) +will terminate other launched processes and prepare to exit when +the *COMMAND* does. +This is appropriate when interacting with a game or other program +that is mostly working: it cleans up any associated debugging +processes when the game itself exits, so that Steam will correctly +conside the game to have exited. + +If set to `0`, the **steam-runtime-launcher-service**(1) will not +stop until it is explicitly terminated by **SIGTERM** or +**steam-runtime-launch-client --bus-name=... --terminate**. +This is particularly useful when debugging a game that crashes or +otherwise exits on startup. +As long as the **steam-runtime-launcher-service**(1) continues +to run, Steam will behave as though the game was still running: +the user is responsible for terminating the service when it is no +longer needed. + +This is a generic **steam-runtime-launcher-service**(1) option, +and is not specific to **steam-runtime-launcher-interface-0**. + +</dd> +<dt> `SRT_LAUNCHER_SERVICE_STOP_ON_NAME_LOSS` (ignored) -: Ignored. - For robustness, the **steam-runtime-launcher-service**(1) run from - this tool always behaves as though this variable is set to `0`. - Even if its D-Bus well-known name is taken over by another process, - it can still be contacted via its D-Bus unique name. + +</dt><dd> + +Ignored. +For robustness, the **steam-runtime-launcher-service**(1) run from +this tool always behaves as though this variable is set to `0`. +Even if its D-Bus well-known name is taken over by another process, +it can still be contacted via its D-Bus unique name. + +</dd> +<dt> `SRT_LOG` -: A sequence of tokens separated by colons, spaces or commas - affecting how output is recorded. See source code for details. + +</dt><dd> + +A sequence of tokens separated by colons, spaces or commas +affecting how output is recorded. See source code for details. + +</dd> +</dl> # OUTPUT @@ -103,6 +130,8 @@ The *COMMAND* inherits standard output and standard error. # EXIT STATUS +The exit status is similar to **env**(1): + 0 : The *COMMAND* exited successfully diff --git a/bin/launcher-service.md b/bin/launcher-service.md index 35b7cc48380ecf072ca5adebc5716faaefbdd1a6..9164c6e159109f6b08c1b46ddaa8c0b4ed91d254 100644 --- a/bin/launcher-service.md +++ b/bin/launcher-service.md @@ -43,157 +43,244 @@ unless prevented by **--no-stop-on-exit** or # OPTIONS +<dl> +<dt> + **--socket** *PATH*, **--socket** *@ABSTRACT* -: Listen on the given `AF_UNIX` socket, which can either be an - absolute path, or `@` followed by an arbitrary string. In both cases, - the length is limited to 107 bytes and the value must not contain - ASCII control characters. - An absolute path indicates a filesystem-based socket, which is - associated with the filesystem and can be shared between filesystem - namespaces by bind-mounting. - The path must not exist before **steam-runtime-launcher-service** is run. - `@` indicates an an abstract socket, which is associated with a - network namespace, is shared between all containers that are in - the same network namespace, and cannot be shared across network - namespace boundaries. - - This option is deprecated. Using **--session** or **--bus-name** is - preferred. + +</dt><dd> + +Listen on the given `AF_UNIX` socket, which can either be an +absolute path, or `@` followed by an arbitrary string. In both cases, +the length is limited to 107 bytes and the value must not contain +ASCII control characters. +An absolute path indicates a filesystem-based socket, which is +associated with the filesystem and can be shared between filesystem +namespaces by bind-mounting. +The path must not exist before **steam-runtime-launcher-service** is run. +`@` indicates an an abstract socket, which is associated with a +network namespace, is shared between all containers that are in +the same network namespace, and cannot be shared across network +namespace boundaries. + +This option is deprecated. Using **--session** or **--bus-name** is +preferred. + +</dd> +<dt> **--socket-directory** *PATH* -: Create a filesystem-based socket with an arbitrary name in the - given directory and listen on that. Clients can use the information - printed on standard output to connect to the socket. Due to - limitations of `AF_UNIX` socket addresses, the absolute path to the - directory must be no more than 64 bytes. It must not contain ASCII - control characters. - This option is deprecated. Using **--session** or **--bus-name** is - preferred. +</dt><dd> + +Create a filesystem-based socket with an arbitrary name in the +given directory and listen on that. Clients can use the information +printed on standard output to connect to the socket. Due to +limitations of `AF_UNIX` socket addresses, the absolute path to the +directory must be no more than 64 bytes. It must not contain ASCII +control characters. + +This option is deprecated. Using **--session** or **--bus-name** is +preferred. + +</dd> +<dt> **--bus-name** *NAME* -: Connect to the well-known D-Bus session bus, request the given name - and listen for commands there. - This option may be used more than once. - If it is, each of the names will be requested in the order given. - If at least one name cannot be acquired or is subsequently lost, - **steam-runtime-launcher-service** will behave according to the - **--[no-]stop-on-exit** options. + +</dt><dd> + +Connect to the well-known D-Bus session bus, request the given name +and listen for commands there. +This option may be used more than once. +If it is, each of the names will be requested in the order given. +If at least one name cannot be acquired or is subsequently lost, +**steam-runtime-launcher-service** will behave according to the +**--[no-]stop-on-exit** options. + +</dd> +<dt> **--alongside-steam** -: Instead of this launcher service providing a way for processes outside - the Steam Linux Runtime container to launch debugging commands inside - the container, advertise it as a way for processes *inside* the container - to launch commands *outside* the container, adjacent to the Steam client - (but possibly inside a larger Flatpak or Snap container, if one was used - to run the Steam client). - This is mutually exclusive with **--inside-app**, - and should not be used inside a Steam Linux Runtime container - (which would make it misleading). - If this option is used, Steam Runtime environment variables will be - removed from the environment of child processes, to give them an - execution environment that most closely resembles the one from which - Steam was launched. - This option implies **--replace**, **--session** and - **--stop-on-parent-exit**. + +</dt><dd> + +Instead of this launcher service providing a way for processes outside +the Steam Linux Runtime container to launch debugging commands inside +the container, advertise it as a way for processes *inside* the container +to launch commands *outside* the container, adjacent to the Steam client +(but possibly inside a larger Flatpak or Snap container, if one was used +to run the Steam client). +This is mutually exclusive with **--inside-app**, +and should not be used inside a Steam Linux Runtime container +(which would make it misleading). +If this option is used, Steam Runtime environment variables will be +removed from the environment of child processes, to give them an +execution environment that most closely resembles the one from which +Steam was launched. +This option implies **--replace**, **--session** and +**--stop-on-parent-exit**. + +</dd> +<dt> **--exec-fallback** -: If unable to set up the **--socket**, **--socket-directory**, - **--bus-name** or **--session**, fall back to executing the - *COMMAND* directly (replacing the **steam-runtime-launcher-service** - process, similar to **env**(1)). - This option is only allowed if a *COMMAND* is specified. - It is useful if running the *COMMAND* is more important than the ability - to insert additional commands into its execution environment. + +</dt><dd> + +If unable to set up the **--socket**, **--socket-directory**, +**--bus-name** or **--session**, fall back to executing the +*COMMAND* directly (replacing the **steam-runtime-launcher-service** +process, similar to **env**(1)). +This option is only allowed if a *COMMAND* is specified. +It is useful if running the *COMMAND* is more important than the ability +to insert additional commands into its execution environment. + +</dd> +<dt> **--exit-on-readable** *FD* -: Exit when file descriptor *FD* (typically 0, for **stdin**) becomes - readable, meaning either data is available or end-of-file has been - reached. + +</dt><dd> + +Exit when file descriptor *FD* (typically 0, for **stdin**) becomes +readable, meaning either data is available or end-of-file has been +reached. + +</dd> +<dt> **--info-fd** *FD* -: Print details of the server on *FD* (see **OUTPUT** below). - This fd will be closed (reach end-of-file) when the server is ready. - If a *COMMAND* is not specified, the default is standard output, - equivalent to **--info-fd=1**. - If a *COMMAND* is specified, there is no default. + +</dt><dd> + +Print details of the server on *FD* (see **OUTPUT** below). +This fd will be closed (reach end-of-file) when the server is ready. +If a *COMMAND* is not specified, the default is standard output, +equivalent to **--info-fd=1**. +If a *COMMAND* is specified, there is no default. + +</dd> +<dt> **--inside-app** -: Advertise this launcher service as a way for processes outside a - Steam Linux Runtime per-app (per-game) container to launch commands - inside the container. - This is mutually exclusive with **--alongside-steam**, - and implies **--session**. + +</dt><dd> + +Advertise this launcher service as a way for processes outside a +Steam Linux Runtime per-app (per-game) container to launch commands +inside the container. +This is mutually exclusive with **--alongside-steam**, +and implies **--session**. + +</dd> +<dt> **--replace** -: When used with **--bus-name**, take over the bus name from - another **steam-runtime-launcher-service** process if any. - The other **steam-runtime-launcher-service** will either exit - or continue to run, depending on whether the **--[no-]stop-on-name-loss** - options were used. - This option is ignored if **--bus-name** is not used. + +</dt><dd> + +When used with **--bus-name**, take over the bus name from +another **steam-runtime-launcher-service** process if any. +The other **steam-runtime-launcher-service** will either exit +or continue to run, depending on whether the **--[no-]stop-on-name-loss** +options were used. +This option is ignored if **--bus-name** is not used. + +</dd> +<dt> **--session** -: Equivalent to **--bus-name** *NAME*, but *NAME* is chosen automatically. - By default, or with **--inside-app**, if a Steam app ID (game ID) can - be discovered from the environment, then the *NAME* is - **com.steampowered.App** followed by the app ID; - otherwise, **com.steampowered.App0** is used. - If **--alongside-steam** is specified, then - **com.steampowered.PressureVessel.LaunchAlongsideSteam** is used - instead. - - Additionally, a second name with an instance-specific suffix like - **com.steampowered.AppX.InstanceY** is generated, to allow multiple - instances of the same app with **--no-stop-on-name-loss**. - - If both **--session** and **--bus-name** are used, then **--session** - has no effect. + +</dt><dd> + +Equivalent to **--bus-name** *NAME*, but *NAME* is chosen automatically. +By default, or with **--inside-app**, if a Steam app ID (game ID) can +be discovered from the environment, then the *NAME* is +**com.steampowered.App** followed by the app ID; +otherwise, **com.steampowered.App0** is used. +If **--alongside-steam** is specified, then +**com.steampowered.PressureVessel.LaunchAlongsideSteam** is used +instead. + +Additionally, a second name with an instance-specific suffix like +**com.steampowered.AppX.InstanceY** is generated, to allow multiple +instances of the same app with **--no-stop-on-name-loss**. + +If both **--session** and **--bus-name** are used, then **--session** +has no effect. + +</dd> +<dt> **--[no-]stop-on-exit** -: With **--stop-on-exit** and a *COMMAND*, the server will terminate - other launched processes and prepare to exit when the *COMMAND* exits. - If other launched processes continue to run after receiving the - **SIGTERM** signal, the server will still wait for them to exit - before terminating. - This is the default. - - With **--no-stop-on-exit** and a *COMMAND*, do not do this: - the server will still be contactable via D-Bus using its unique bus name - until it is terminated, for example with **SIGTERM** or - **steam-runtime-launch-client --bus-name=:1.xx --terminate**. - Note that if the wrapped *COMMAND* is a Steam game, then Steam will - still consider the game to be running until the - **steam-runtime-launcher-service** is terminated. + +</dt><dd> + +With **--stop-on-exit** and a *COMMAND*, the server will terminate +other launched processes and prepare to exit when the *COMMAND* exits. +If other launched processes continue to run after receiving the +**SIGTERM** signal, the server will still wait for them to exit +before terminating. +This is the default. + +With **--no-stop-on-exit** and a *COMMAND*, do not do this: +the server will still be contactable via D-Bus using its unique bus name +until it is terminated, for example with **SIGTERM** or +**steam-runtime-launch-client --bus-name=:1.xx --terminate**. +Note that if the wrapped *COMMAND* is a Steam game, then Steam will +still consider the game to be running until the +**steam-runtime-launcher-service** is terminated. + +</dd> +<dt> **--[no-]stop-on-name-loss** -: With **--bus-name** and **--stop-on-name-loss**, the server will - prepare to exit when any of the well-known bus names *NAME* used with - **--bus-name** is lost, most likely because another server was - run with **--replace** and took over ownership. - If other launched processes are active, it will wait for them to exit - before terminating. - This is the default. - With **--bus-name** and **--no-stop-on-name-loss**, do not do this: - the server will still be contactable via D-Bus using its unique bus name. +</dt><dd> + +With **--bus-name** and **--stop-on-name-loss**, the server will +prepare to exit when any of the well-known bus names *NAME* used with +**--bus-name** is lost, most likely because another server was +run with **--replace** and took over ownership. +If other launched processes are active, it will wait for them to exit +before terminating. +This is the default. - These parameters have no effect if **--bus-name** is not used. +With **--bus-name** and **--no-stop-on-name-loss**, do not do this: +the server will still be contactable via D-Bus using its unique bus name. + +These parameters have no effect if **--bus-name** is not used. + +</dd> +<dt> **--[no-]stop-on-parent-exit** -: With **--stop-on-parent-exit**, the server will terminate - other launched processes and prepare to exit when its parent - process exits. - As with **--stop-on-exit**, if launched processes continue to run after - receiving the **SIGTERM** signal, the server will still wait for them - to exit. - With **--no-stop-on-parent-exit**, continue to run when reparented - to init or a subreaper. - This is the default. +</dt><dd> + +With **--stop-on-parent-exit**, the server will terminate +other launched processes and prepare to exit when its parent +process exits. +As with **--stop-on-exit**, if launched processes continue to run after +receiving the **SIGTERM** signal, the server will still wait for them +to exit. + +With **--no-stop-on-parent-exit**, continue to run when reparented +to init or a subreaper. +This is the default. + +</dd> +<dt> **--verbose** -: Be more verbose. + +</dt><dd> + +Be more verbose. + +</dd> +</dl> # ENVIRONMENT @@ -203,49 +290,109 @@ Some variables will be set programmatically in the subprocesses started by **steam-runtime-launcher-service** when a command is sent to it by **steam-runtime-launch-client**: +<dl> +<dt> + `MAINPID` -: If **steam-runtime-launcher-service** was run as a wrapper around a - *COMMAND* (for example as - **steam-runtime-launcher-service --bus-name=... -- my-game**), - and the initial process of the wrapped *COMMAND* is still running, - then this variable is set to its process ID (for example, the process - ID of **my-game**). Otherwise, this variable is cleared. + +</dt><dd> + +If **steam-runtime-launcher-service** was run as a wrapper around a +*COMMAND* (for example as +**steam-runtime-launcher-service --bus-name=... -- my-game**), +and the initial process of the wrapped *COMMAND* is still running, +then this variable is set to its process ID (for example, the process +ID of **my-game**). Otherwise, this variable is cleared. + +</dd> +<dt> `PWD` -: Set to the current working directory for each command executed - inside the container. + +</dt><dd> + +Set to the current working directory for each command executed +inside the container. + +</dd> +</dl> Additionally, **steam-runtime-launch-client** has several options that manipulate environment variables on a per-command basis. ## Variables read by steam-runtime-launcher-service +<dl> +<dt> + `PRESSURE_VESSEL_LOG_INFO` (boolean) -: If set to 1, same as `SRT_LOG=info` + +</dt><dd> + +If set to 1, same as `SRT_LOG=info` + +</dd> +<dt> `PRESSURE_VESSEL_LOG_WITH_TIMESTAMP` (boolean) -: If set to 1, same as `SRT_LOG=timestamp` + +</dt><dd> + +If set to 1, same as `SRT_LOG=timestamp` + +</dd> +<dt> `SRT_LAUNCHER_SERVICE_STOP_ON_EXIT` (boolean) -: If set to `0`, the default behaviour changes to be equivalent to - **--no-stop-on-exit**, unless overridden by **--stop-on-exit**. - If set to `1`, no effect. + +</dt><dd> + +If set to `0`, the default behaviour changes to be equivalent to +**--no-stop-on-exit**, unless overridden by **--stop-on-exit**. +If set to `1`, no effect. + +</dd> +<dt> `SRT_LAUNCHER_SERVICE_STOP_ON_NAME_LOSS` (boolean) -: If set to `0`, the default behaviour changes to be equivalent to - **--no-stop-on-name-loss**, unless overridden by **--stop-on-name-loss**. - If set to `1`, no effect. + +</dt><dd> + +If set to `0`, the default behaviour changes to be equivalent to +**--no-stop-on-name-loss**, unless overridden by **--stop-on-name-loss**. +If set to `1`, no effect. + +</dd> +<dt> `SRT_LOG` -: A sequence of tokens separated by colons, spaces or commas - affecting how output is recorded. See source code for details. + +</dt><dd> + +A sequence of tokens separated by colons, spaces or commas +affecting how output is recorded. See source code for details. + +</dd> +<dt> `STEAM_COMPAT_APP_ID` (integer) -: Used by **--session** to identify the Steam app ID (game ID). + +</dt><dd> + +Used by **--session** to identify the Steam app ID (game ID). + +</dd> +<dt> `SteamAppId` (integer) -: Used by **--session** to identify the Steam app ID (game ID), - if `STEAM_COMPAT_APP_ID` is not also set. + +</dt><dd> + +Used by **--session** to identify the Steam app ID (game ID), +if `STEAM_COMPAT_APP_ID` is not also set. + +</dd> +</dl> # OUTPUT @@ -262,25 +409,46 @@ different). The text printed to the **--info-fd** includes one or more of these: +<dl> +<dt> + **socket=**PATH -: The launcher is listening on *PATH*, and can be contacted by - **steam-runtime-launch-client --socket** _PATH_ - or by connecting a peer-to-peer D-Bus client to a D-Bus address - corresponding to _PATH_. + +</dt><dd> + +The launcher is listening on *PATH*, and can be contacted by +**steam-runtime-launch-client --socket** _PATH_ +or by connecting a peer-to-peer D-Bus client to a D-Bus address +corresponding to _PATH_. + +</dd> +<dt> **dbus_address=**ADDRESS -: The launcher is listening on *ADDRESS*, and can be contacted by - **steam-runtime-launch-client --dbus-address** _ADDRESS_, - or by connecting another peer-to-peer D-Bus client - (such as **dbus-send --peer=ADDRESS**) to _ADDRESS_. + +</dt><dd> + +The launcher is listening on *ADDRESS*, and can be contacted by +**steam-runtime-launch-client --dbus-address** _ADDRESS_, +or by connecting another peer-to-peer D-Bus client +(such as **dbus-send --peer=ADDRESS**) to _ADDRESS_. + +</dd> +<dt> **bus_name=**NAME -: The launcher is listening on the well-known D-Bus session bus, - and can be contacted by - **steam-runtime-launch-client --bus-name** *NAME*, - or by connecting an ordinary D-Bus client - (such as **dbus-send --session**) to the session bus and sending - method calls to _NAME_. + +</dt><dd> + +The launcher is listening on the well-known D-Bus session bus, +and can be contacted by +**steam-runtime-launch-client --bus-name** *NAME*, +or by connecting an ordinary D-Bus client +(such as **dbus-send --session**) to the session bus and sending +method calls to _NAME_. + +</dd> +</dl> Before connecting, clients must wait until after at least one of these: diff --git a/bin/logger.md b/bin/logger.md index 4f849999732fdadc35d8069ede7b7fdfb71baeee..8ad96abb61973f8b9520f9377842a9871ecbf183 100644 --- a/bin/logger.md +++ b/bin/logger.md @@ -62,292 +62,482 @@ a **#!/bin/sh** script. # OPTIONS +<dl> +<dt> + **--background** -: Run a new **srt-logger** process in the background (daemonized), - instead of having it become a child of the *COMMAND* or the parent - process. - This can be useful when combined with **steam-runtime-supervisor**, - because it is better for the **srt-logger** not to be killed during - process termination (if it was, then any buffered log output would - be lost). + +</dt><dd> + +Run a new **srt-logger** process in the background (daemonized), +instead of having it become a child of the *COMMAND* or the parent +process. + +This can be useful when combined with **steam-runtime-supervisor**, +because it is better for the **srt-logger** not to be killed during +process termination (if it was, then any buffered log output would +be lost). + +</dd> +<dt> **--exec-fallback** -: If unable to set up logging, run the *COMMAND* anyway. - If there is no *COMMAND*, and **--background** was not used, - mirror messages received on standard input - to standard error by running **cat**(1). - This option should be used in situations where fault-tolerance is - more important than logging. + +</dt><dd> + +If unable to set up logging, run the *COMMAND* anyway. +If there is no *COMMAND*, and **--background** was not used, +mirror messages received on standard input +to standard error by running **cat**(1). +This option should be used in situations where fault-tolerance is +more important than logging. + +</dd> +<dt> **--filename** *FILENAME* -: Write to the given *FILENAME* in the **--log-directory**, - with rotation when it becomes too large. - An empty *FILENAME* disables logging to flat files. +</dt><dd> + +Write to the given *FILENAME* in the **--log-directory**, +with rotation when it becomes too large. - If no **--filename** is given, the default is to append **.txt** - to the **--identifier**. +An empty *FILENAME* disables logging to flat files. + +If no **--filename** is given, the default is to append **.txt** +to the **--identifier**. + +</dd> +<dt> **--identifier** *STRING*, **-t** *STRING* -: When writing to the systemd Journal, log with the given *STRING* - as an identifier. - An empty *STRING* disables logging to the systemd Journal, - unless a **--journal-fd** is also given. +</dt><dd> + +When writing to the systemd Journal, log with the given *STRING* +as an identifier. - If no **--identifier** is given, the default is to remove the - extension from the **--filename**. +An empty *STRING* disables logging to the systemd Journal, +unless a **--journal-fd** is also given. - If no **--filename** is given either, when run with a *COMMAND*, - the default is the basename of the first word of the *COMMAND*, - similar to **systemd-cat**(1). +If no **--identifier** is given, the default is to remove the +extension from the **--filename**. + +If no **--filename** is given either, when run with a *COMMAND*, +the default is the basename of the first word of the *COMMAND*, +similar to **systemd-cat**(1). + +</dd> +<dt> **--journal-fd** *FD* -: Receive an inherited file descriptor instead of opening a new connection - to the Journal. + +</dt><dd> + +Receive an inherited file descriptor instead of opening a new connection +to the Journal. + +</dd> +<dt> **--log-directory** *PATH* -: Interpret the **--filename** as being in *PATH*. - If `$SRT_LOG_DIR` is set, the default is that directory, - interpreted as being absolute or relative to the current working - directory in the usual way. - Otherwise, if `$STEAM_CLIENT_LOG_FOLDER` is set, the default is - that directory interpreted as relative to `~/.steam/steam` (unusually, - this is done even if it starts with `/`). - Otherwise the default is `~/.steam/steam/logs`. - The log directory must already exist during **srt-logger** startup. + +</dt><dd> + +Interpret the **--filename** as being in *PATH*. +If `$SRT_LOG_DIR` is set, the default is that directory, +interpreted as being absolute or relative to the current working +directory in the usual way. +Otherwise, if `$STEAM_CLIENT_LOG_FOLDER` is set, the default is +that directory interpreted as relative to `~/.steam/steam` (unusually, +this is done even if it starts with `/`). +Otherwise the default is `~/.steam/steam/logs`. +The log directory must already exist during **srt-logger** startup. + +</dd> +<dt> **--log-fd** *FD* -: Receive an inherited file descriptor for the log file instead of - opening the log file again. - It is an error to provide a **--log-fd** that does not point to the - **--filename** in the **--log-directory**. - If this is done, it is likely to lead to unintended results and - potentially loss of log messages during log rotation. + +</dt><dd> + +Receive an inherited file descriptor for the log file instead of +opening the log file again. + +It is an error to provide a **--log-fd** that does not point to the +**--filename** in the **--log-directory**. +If this is done, it is likely to lead to unintended results and +potentially loss of log messages during log rotation. + +</dd> +<dt> **--mkfifo** -: Instead of carrying out logging, create a **fifo**(7) (named pipe) - in a subdirectory of any appropriate location, write its path to - standard output followed by a newline and exit. - This option cannot be combined with any other options. - It is primarily intended for use in portable shell scripts, to avoid - relying on external **mktemp**(1) and **mkfifo**(1) commands. - If the fifo is successfully created, the caller is responsible for - deleting both the fifo itself and its parent directory after use. - If **srt-logger** fails to create a fifo, no cleanup is required. - The current implementation for this option creates a subdirectory - with a random name in either **$XDG_RUNTIME_DIR**, **$TMPDIR** - or **/tmp**, similar to **mktemp -d**, then creates the fifo inside - that subdirectory. - If one of those directories cannot hold fifo objects, **srt-logger** - will show a warning and fall back to the next. + +</dt><dd> + +Instead of carrying out logging, create a **fifo**(7) (named pipe) +in a subdirectory of any appropriate location, write its path to +standard output followed by a newline and exit. + +This option cannot be combined with any other options. +It is primarily intended for use in portable shell scripts, to avoid +relying on external **mktemp**(1) and **mkfifo**(1) commands. + +If the fifo is successfully created, the caller is responsible for +deleting both the fifo itself and its parent directory after use. +If **srt-logger** fails to create a fifo, no cleanup is required. +The current implementation for this option creates a subdirectory +with a random name in either **$XDG_RUNTIME_DIR**, **$TMPDIR** +or **/tmp**, similar to **mktemp -d**, then creates the fifo inside +that subdirectory. +If one of those directories cannot hold fifo objects, **srt-logger** +will show a warning and fall back to the next. + +</dd> +<dt> **--no-auto-terminal** -: Don't copy logged messages to the terminal, if any. - If standard error is a terminal, the default is to copy logged messages - to that terminal, and also provide it to subprocesses via - `$SRT_LOG_TERMINAL`. - Otherwise, if `$SRT_LOG_TERMINAL` is set, the default is to copy logged - messages to that terminal. + +</dt><dd> + +Don't copy logged messages to the terminal, if any. +If standard error is a terminal, the default is to copy logged messages +to that terminal, and also provide it to subprocesses via +`$SRT_LOG_TERMINAL`. +Otherwise, if `$SRT_LOG_TERMINAL` is set, the default is to copy logged +messages to that terminal. + +</dd> +<dt> **--sh-syntax** -: Write machine-readable output to standard output. - The output format is line-oriented, can be parsed by **eval**(1posix), - and on success the last line will be exactly **SRT_LOGGER_READY=1** - followed by a newline. - When this option is used, if standard output is closed without any - output, that indicates that the logger failed to initialize. - If this happens, diagnostic messages will be written to standard error - as usual. - This is mainly used to implement **--background**, but can also be used - elsewhere. - - If a line before the last starts with **SRT_LOGGER_PID=**, then it - is a shell-style assignment indicating the process ID of the process - that is responsible for logging (which might be a daemonized background - process). - The associated value might be quoted, and will need to be unquoted - according to **sh**(1) rules before use, - for example with GLib's **g_shell_unquote** or Python's **shlex.split**. - - If a line before the last starts with **export** or **unset** followed - by a space, then it indicates an environment variable that should be - set or unset for processes that are writing their output to this - logger, to ensure that any **srt-logger** child processes direct their - log output to appropriate destinations. - The associated value for an **export** might be quoted, as above. - - Other output may be produced in future versions of this tool. + +</dt><dd> + +Write machine-readable output to standard output. +The output format is line-oriented, can be parsed by **eval**(1posix), +and on success the last line will be exactly **SRT_LOGGER_READY=1** +followed by a newline. +When this option is used, if standard output is closed without any +output, that indicates that the logger failed to initialize. +If this happens, diagnostic messages will be written to standard error +as usual. +This is mainly used to implement **--background**, but can also be used +elsewhere. + +If a line before the last starts with **SRT_LOGGER_PID=**, then it +is a shell-style assignment indicating the process ID of the process +that is responsible for logging (which might be a daemonized background +process). +The associated value might be quoted, and will need to be unquoted +according to **sh**(1) rules before use, +for example with GLib's **g_shell_unquote** or Python's **shlex.split**. + +If a line before the last starts with **export** or **unset** followed +by a space, then it indicates an environment variable that should be +set or unset for processes that are writing their output to this +logger, to ensure that any **srt-logger** child processes direct their +log output to appropriate destinations. +The associated value for an **export** might be quoted, as above. + +Other output may be produced in future versions of this tool. + +</dd> +<dt> **--rotate** *BYTES* -: If the **--filename** would exceed *BYTES*, rename it to a different - filename (for example `log.txt` becomes `log.previous.txt`) - and start a new log. - If log rotation fails or another process is holding a lock on the - log file, then rotation is disabled and *BYTES* may be exceeded. +</dt><dd> + +If the **--filename** would exceed *BYTES*, rename it to a different +filename (for example `log.txt` becomes `log.previous.txt`) +and start a new log. + +If log rotation fails or another process is holding a lock on the +log file, then rotation is disabled and *BYTES* may be exceeded. + +*BYTES* may be suffixed with +`K`, `KiB`, `M` or `MiB` for powers of 1024, +or `kB` or `MB` for powers of 1000. - *BYTES* may be suffixed with - `K`, `KiB`, `M` or `MiB` for powers of 1024, - or `kB` or `MB` for powers of 1000. +The default is 8 MiB. **--rotate=0** or environment variable +**SRT_LOG_ROTATION=0** can be used to disable rotation. - The default is 8 MiB. **--rotate=0** or environment variable - **SRT_LOG_ROTATION=0** can be used to disable rotation. +</dd> +<dt> **--terminal-fd** *FD* -: Receive an inherited file descriptor for the terminal instead of - opening the terminal device again. + +</dt><dd> + +Receive an inherited file descriptor for the terminal instead of +opening the terminal device again. + +</dd> +<dt> **--timestamps**, **--no-timestamps** -: Do or don't prepend timestamps to each line in the log file. - The default is to add timestamps, unless environment variable - **SRT_LOGGER_TIMESTAMPS=0** is set. + +</dt><dd> + +Do or don't prepend timestamps to each line in the log file. +The default is to add timestamps, unless environment variable +**SRT_LOGGER_TIMESTAMPS=0** is set. + +</dd> +<dt> **--use-journal** -: Write messages to the systemd Journal if possible, even if no - **--journal-fd** was given. + +</dt><dd> + +Write messages to the systemd Journal if possible, even if no +**--journal-fd** was given. + +</dd> +<dt> **--parse-level-prefix** -: If any log lines begin with a syslog priority prefix (an less-than `<`, - a level number 0-7, and a greater-than `>`), then strip that prefix off of - the line and use the number within as the line's log level. This is a - limited subset of RFC 5424's syslog message format, with the following - supported levels (available from C via the `LOG_*` constants in - **syslog**(3)), in order of most to least important: - - | Level number | Name | - | ------------ | --------- | - | 0 | emergency | - | 1 | alert | - | 2 | critical | - | 3 | error | - | 4 | warning | - | 5 | notice | - | 6 | info | - | 7 | debug | - - If an entire log line is `<remaining-lines-assume-level=N>`, where *N* is a - level number from 0-7 as mentioned above, then subsequent lines will be - logged with the level *N* and will not have any specific prefixes from them - parsed. - - For example, given these lines: - - ``` - <5>abc - def - <remaining-lines-assume-level=4> - ghi - <3>jkl - ``` - - - The first line will be logged as `abc` with log level 5 / notice. - - The second line will be logged as `def` with the log level given to - **--default-level**. - - The third line will not be logged but will instead direct the logger to - use the level 4 / warning for all lines that follow. - - The fourth line will be logged as `ghi` with log level 4 / warning. - - The fifth line will be logged as `<3>jkl` with log level 3 / error. + +</dt><dd> + +If any log lines begin with a syslog priority prefix (an less-than `<`, +a level number 0-7, and a greater-than `>`), then strip that prefix off of +the line and use the number within as the line's log level. This is a +limited subset of RFC 5424's syslog message format, with the following +supported levels (available from C via the `LOG_*` constants in +**syslog**(3)), in order of most to least important: + +| Level number | Name | +| ------------ | --------- | +| 0 | emergency | +| 1 | alert | +| 2 | critical | +| 3 | error | +| 4 | warning | +| 5 | notice | +| 6 | info | +| 7 | debug | + +If an entire log line is `<remaining-lines-assume-level=N>`, where *N* is a +level number from 0-7 as mentioned above, then subsequent lines will be +logged with the level *N* and will not have any specific prefixes from them +parsed. + +For example, given these lines: + +``` +<5>abc +def +<remaining-lines-assume-level=4> +ghi +<3>jkl +``` + +- The first line will be logged as `abc` with log level 5 / notice. +- The second line will be logged as `def` with the log level given to + **--default-level**. +- The third line will not be logged but will instead direct the logger to + use the level 4 / warning for all lines that follow. +- The fourth line will be logged as `ghi` with log level 4 / warning. +- The fifth line will be logged as `<3>jkl` with log level 3 / error. + +</dd> +<dt> **--default-level=**_LEVEL_ -: Use the given level as the default level for all log lines, unless - **--parse-level-prefix** is given and the line has its own prefix. The given - level must be one of the following numbers, corresponding names (in any - case), or aliases: - - | Level number | Name | Alias | Alias | - | ------------ | --------- | ----- | ----- | - | 0 | emergency | emerg | | - | 1 | alert | alert | | - | 2 | critical | crit | | - | 3 | error | err | e | - | 4 | warning | warn | w | - | 5 | notice | | n | - | 6 | info | | i | - | 7 | debug | | d | - - Defaults to `info`. + +</dt><dd> + +Use the given level as the default level for all log lines, unless +**--parse-level-prefix** is given and the line has its own prefix. The given +level must be one of the following numbers, corresponding names (in any +case), or aliases: + +| Level number | Name | Alias | Alias | +| ------------ | --------- | ----- | ----- | +| 0 | emergency | emerg | | +| 1 | alert | alert | | +| 2 | critical | crit | | +| 3 | error | err | e | +| 4 | warning | warn | w | +| 5 | notice | | n | +| 6 | info | | i | +| 7 | debug | | d | + +Defaults to `info`. + +</dd> +<dt> **--file-level=**_LEVEL_ -: Only send log lines to the log file from **--log-fd** or **--filename** that - have a log level at or more important than _LEVEL_, parsed in the same - format as **--default-level**. - Defaults to `debug` (which will effectively write everything). +</dt><dd> + +Only send log lines to the log file from **--log-fd** or **--filename** that +have a log level at or more important than _LEVEL_, parsed in the same +format as **--default-level**. + +Defaults to `debug` (which will effectively write everything). + +</dd> +<dt> **--journal-level=**_LEVEL_ -: Only send log lines to the systemd journal that have a log level at or more - important than _LEVEL_, parsed in the same format as **--default-level**. - Defaults to `debug` (which will effectively write everything). +</dt><dd> + +Only send log lines to the systemd journal that have a log level at or more +important than _LEVEL_, parsed in the same format as **--default-level**. + +Defaults to `debug` (which will effectively write everything). + +</dd> +<dt> **--terminal-level=**_LEVEL_ -: Only send log lines to the terminal that have a log level at or more - important than _LEVEL_, parsed in the same format as **--default-level**. - Defaults to `info`. +</dt><dd> + +Only send log lines to the terminal that have a log level at or more +important than _LEVEL_, parsed in the same format as **--default-level**. + +Defaults to `info`. + +</dd> +<dt> **--verbose**, **-v** -: Be more verbose. If used twice, debug messages are shown. + +</dt><dd> + +Be more verbose. If used twice, debug messages are shown. + +</dd> +<dt> **--version** -: Print version information in YAML format. + +</dt><dd> + +Print version information in YAML format. + +</dd> +</dl> # ENVIRONMENT +<dl> +<dt> + `NO_COLOR` -: If present and non-empty, disables all coloring of logs written to the - terminal. + +</dt><dd> + +If present and non-empty, disables all coloring of logs written to the +terminal. + +</dd> +<dt> `SRT_LOG` -: A sequence of tokens separated by colons, spaces or commas - affecting how diagnostic output from **srt-logger** itself is recorded. - In particular, `SRT_LOG=journal` has the same effect as - `SRT_LOG_TO_JOURNAL=1`. + +</dt><dd> + +A sequence of tokens separated by colons, spaces or commas +affecting how diagnostic output from **srt-logger** itself is recorded. +In particular, `SRT_LOG=journal` has the same effect as +`SRT_LOG_TO_JOURNAL=1`. + +</dd> +<dt> `SRT_LOG_DIR` -: An absolute or relative path to be used instead of the default - log directory. + +</dt><dd> + +An absolute or relative path to be used instead of the default +log directory. + +</dd> +<dt> `SRT_LOG_ROTATION` (`0` or `1`) -: If set to `0`, log rotation is disabled and **--rotate** is ignored. + +</dt><dd> + +If set to `0`, log rotation is disabled and **--rotate** is ignored. + +</dd> +<dt> `SRT_LOG_TERMINAL` -: If set to the absolute path of a terminal device such as `/dev/pts/0`, - **srt-logger** will attempt to copy all log messages to that - terminal device. - If set to the empty string, the effect is the same as - **--no-auto-terminal**. - If output to the terminal is enabled, **srt-logger** also sets this - environment variable for the *COMMAND*. + +</dt><dd> + +If set to the absolute path of a terminal device such as `/dev/pts/0`, +**srt-logger** will attempt to copy all log messages to that +terminal device. +If set to the empty string, the effect is the same as +**--no-auto-terminal**. +If output to the terminal is enabled, **srt-logger** also sets this +environment variable for the *COMMAND*. + +</dd> +<dt> `SRT_LOG_TO_JOURNAL`, `SRT_LOGGER_USE_JOURNAL` -: If either is set to `1`, log to the systemd Journal if available. - As well as redirecting diagnostic output from **srt-logger** itself, - this has an effect similar to adding - **--use-journal** to all **srt-logger** invocations. - If output to the Journal is enabled, **srt-logger** also sets - **SRT_LOGGER_USE_JOURNAL=1** for the *COMMAND*, - and may set **SRT_LOG_TO_JOURNAL=0** in order to ensure that child - processes that are part of the steam-runtime-tools suite do not write - directly to the Journal, which would cause them to bypass the - **srt-logger**. + +</dt><dd> + +If either is set to `1`, log to the systemd Journal if available. +As well as redirecting diagnostic output from **srt-logger** itself, +this has an effect similar to adding +**--use-journal** to all **srt-logger** invocations. +If output to the Journal is enabled, **srt-logger** also sets +**SRT_LOGGER_USE_JOURNAL=1** for the *COMMAND*, +and may set **SRT_LOG_TO_JOURNAL=0** in order to ensure that child +processes that are part of the steam-runtime-tools suite do not write +directly to the Journal, which would cause them to bypass the +**srt-logger**. + +</dd> +<dt> `SRT_LOGGER` -: If set, **logger-0.bash** will use this instead of locating an - adjacent **srt-logger** executable automatically. + +</dt><dd> + +If set, **logger-0.bash** will use this instead of locating an +adjacent **srt-logger** executable automatically. + +</dd> +<dt> `SRT_LOGGER_TIMESTAMPS` (`0` or `1`) -: Set the behaviour if neither **--timestamps** nor **--no-timestamps** - is specified. + +</dt><dd> + +Set the behaviour if neither **--timestamps** nor **--no-timestamps** +is specified. + +</dd> +<dt> `STEAM_CLIENT_LOG_FOLDER` -: A path relative to `~/.steam/steam` to be used as a default log - directory if `$SRT_LOG_DIR` is unset. - The default is `logs`. - Note that unusually, this is interpreted as a relative path, even if - it starts with `/` (this is consistent with the behaviour of the - Steam client). + +</dt><dd> + +A path relative to `~/.steam/steam` to be used as a default log +directory if `$SRT_LOG_DIR` is unset. +The default is `logs`. +Note that unusually, this is interpreted as a relative path, even if +it starts with `/` (this is consistent with the behaviour of the +Steam client). + +</dd> +</dl> # OUTPUT diff --git a/bin/run-outside-ldlp.md b/bin/run-outside-ldlp.md index e8be5f799e1bd8e88c06d1e0b21e62f4253528b6..dd1fcf98f31e78cfba0b95a8c7a814d8ecd67a92 100644 --- a/bin/run-outside-ldlp.md +++ b/bin/run-outside-ldlp.md @@ -34,8 +34,17 @@ running itself recursively if in the current `PATH`.) # OPTIONS +<dl> +<dt> + **--verbose**, **-v** -: Be more verbose. If used twice, debug messages are shown. + +</dt><dd> + +Be more verbose. If used twice, debug messages are shown. + +</dd> +</dl> # OUTPUT diff --git a/bin/supervisor.md b/bin/supervisor.md index efabfe0f033d800ceb3c8403a69269fd0e72c06c..c6ed96dd4fff9ea2736bfa593558b21674fb79b4 100644 --- a/bin/supervisor.md +++ b/bin/supervisor.md @@ -44,158 +44,296 @@ determined by the options. # OPTIONS +<dl> +<dt> + **--assign-fd** _TARGET_**=**_SOURCE_ -: Make file descriptor *TARGET* in the *COMMAND* a copy of file - descriptor *SOURCE* as passed to **steam-runtime-supervisor**, - similar to writing `TARGET>&SOURCE` as a shell redirection. - For example, **--assign-fd=1=3** is the same as **1>&3**. - The redirection is done at the last possible moment, so the output - of **steam-runtime-supervisor** (if any) will still go to the - original standard error. + +</dt><dd> + +Make file descriptor *TARGET* in the *COMMAND* a copy of file +descriptor *SOURCE* as passed to **steam-runtime-supervisor**, +similar to writing `TARGET>&SOURCE` as a shell redirection. +For example, **--assign-fd=1=3** is the same as **1>&3**. +The redirection is done at the last possible moment, so the output +of **steam-runtime-supervisor** (if any) will still go to the +original standard error. + +</dd> +<dt> **--close-fds** -: Do not pass inherited file descriptors to the *COMMAND*, - except for file descriptors 0, 1 and 2 - (**stdin**, **stdout** and **stderr**) - and any file descriptors passed to **--pass-fd** or as the target - of **--assign-fd**. - **--no-close-fds** disables this behaviour, and is the default. + +</dt><dd> + +Do not pass inherited file descriptors to the *COMMAND*, +except for file descriptors 0, 1 and 2 +(**stdin**, **stdout** and **stderr**) +and any file descriptors passed to **--pass-fd** or as the target +of **--assign-fd**. +**--no-close-fds** disables this behaviour, and is the default. + +</dd> +<dt> **--env** _VAR=VALUE_ -: Set environment variable _VAR_ to _VALUE_. - This is mostly equivalent to using - **env** _VAR=VALUE_ *COMMAND* *ARGUMENTS...* - as the command. + +</dt><dd> + +Set environment variable _VAR_ to _VALUE_. +This is mostly equivalent to using +**env** _VAR=VALUE_ *COMMAND* *ARGUMENTS...* +as the command. + +</dd> +<dt> **--env-fd** _FD_ -: Parse zero-terminated environment variables from _FD_, and set each - one as if via **--env**. - The format of _FD_ is the same as the output of `$(env -0)` or the - pseudo-file `/proc/PID/environ`. + +</dt><dd> + +Parse zero-terminated environment variables from _FD_, and set each +one as if via **--env**. +The format of _FD_ is the same as the output of `$(env -0)` or the +pseudo-file `/proc/PID/environ`. + +</dd> +<dt> **--exit-with-parent** -: Arrange for **steam-runtime-supervisor** to receive **SIGTERM** - (which it will pass on to *COMMAND*, if possible) when its parent - process exits. - **--no-exit-with-parent** disables this behaviour, and is the default. + +</dt><dd> + +Arrange for **steam-runtime-supervisor** to receive **SIGTERM** +(which it will pass on to *COMMAND*, if possible) when its parent +process exits. +**--no-exit-with-parent** disables this behaviour, and is the default. + +</dd> +<dt> **--inherit-env** *VAR* -: Undo the effect of a previous **--env**, **--unset-env** - or similar, returning to the default behaviour of inheriting *VAR* - from the execution environment of **steam-runtime-supervisor** - (unless **--clear-env** was used, in which case this option becomes - effectively equivalent to **--unset-env**). + +</dt><dd> + +Undo the effect of a previous **--env**, **--unset-env** +or similar, returning to the default behaviour of inheriting *VAR* +from the execution environment of **steam-runtime-supervisor** +(unless **--clear-env** was used, in which case this option becomes +effectively equivalent to **--unset-env**). + +</dd> +<dt> **--inherit-env-matching** *WILDCARD* -: Do the same as for **--inherit-env** for any environment variable - whose name matches *WILDCARD*. - If this command is run from a shell, the wildcard will usually need - to be quoted, for example **--inherit-env-matching="FOO*"**. + +</dt><dd> + +Do the same as for **--inherit-env** for any environment variable +whose name matches *WILDCARD*. +If this command is run from a shell, the wildcard will usually need +to be quoted, for example **--inherit-env-matching="FOO*"**. + +</dd> +<dt> **--lock-create** -: Create each **--lock-file** that appears on the command-line after - this option if it does not exist, until a **--no-lock-create** option - is seen. - **--no-lock-create** reverses this behaviour, and is the default. + +</dt><dd> + +Create each **--lock-file** that appears on the command-line after +this option if it does not exist, until a **--no-lock-create** option +is seen. +**--no-lock-create** reverses this behaviour, and is the default. + +</dd> +<dt> **--lock-exclusive** -: Each **--lock-file** that appears on the command-line after - this option will be locked in **F_WRLCK** mode (an exclusive/write - lock), until a **--no-lock-exclusive** or **--lock-shared** - option is seen. - **--no-lock-exclusive** or **--lock-shared** results - in use of **F_RDLCK** (a shared/read lock), and is the default. + +</dt><dd> + +Each **--lock-file** that appears on the command-line after +this option will be locked in **F_WRLCK** mode (an exclusive/write +lock), until a **--no-lock-exclusive** or **--lock-shared** +option is seen. +**--no-lock-exclusive** or **--lock-shared** results +in use of **F_RDLCK** (a shared/read lock), and is the default. + +</dd> +<dt> **--lock-fd** *FD* -: Receive file descriptor *FD* (specified as a small positive integer) - from the parent process, and keep it open until - **steam-runtime-supervisor** exits. This is most useful if *FD* - is locked with a Linux open file description lock (**F_OFD_SETLK** - or **F_OFD_SETLKW** from **fcntl**(2)), in which case the lock will - be held by **steam-runtime-supervisor**. + +</dt><dd> + +Receive file descriptor *FD* (specified as a small positive integer) +from the parent process, and keep it open until +**steam-runtime-supervisor** exits. This is most useful if *FD* +is locked with a Linux open file description lock (**F_OFD_SETLK** +or **F_OFD_SETLKW** from **fcntl**(2)), in which case the lock will +be held by **steam-runtime-supervisor**. + +</dd> +<dt> **--lock-file** *FILENAME* -: Lock the file *FILENAME* according to the most recently seen - **--[no-]lock-create**, **--[no-]lock-wait** and **--[no-]-lock-exclusive** - options, using a Linux open file description lock (**F_OFD_SETLK** or - **F_OFD_SETLKW** from **fcntl**(2)) if possible, or a POSIX - process-associated record lock (**F_SETLK** or **F_SETLKW**) on older - kernels. - - These locks interact in the expected way with **bwrap**(1), - **flatpak**(1) and other parts of **steam-runtime-tools**. - It is unspecified whether they exclude the **flock**(2) locks used - by util-linux **flock**(1) or not, so using those locks on lock - files used by **steam-runtime-tools** should be avoided. + +</dt><dd> + +Lock the file *FILENAME* according to the most recently seen +**--[no-]lock-create**, **--[no-]lock-wait** and **--[no-]-lock-exclusive** +options, using a Linux open file description lock (**F_OFD_SETLK** or +**F_OFD_SETLKW** from **fcntl**(2)) if possible, or a POSIX +process-associated record lock (**F_SETLK** or **F_SETLKW**) on older +kernels. + +These locks interact in the expected way with **bwrap**(1), +**flatpak**(1) and other parts of **steam-runtime-tools**. +It is unspecified whether they exclude the **flock**(2) locks used +by util-linux **flock**(1) or not, so using those locks on lock +files used by **steam-runtime-tools** should be avoided. + +</dd> +<dt> **--lock-wait** -: For each **--lock-file** that appears on the command-line after - this option until a **--no-lock-wait** option is seen, if the file is - already locked in an incompatible way, **steam-runtime-supervisor** - will wait for the current holder of the lock to release it. - With **--no-lock-wait**, which is the default, - **steam-runtime-supervisor** will exit with status 125 - if a lock cannot be acquired. + +</dt><dd> + +For each **--lock-file** that appears on the command-line after +this option until a **--no-lock-wait** option is seen, if the file is +already locked in an incompatible way, **steam-runtime-supervisor** +will wait for the current holder of the lock to release it. +With **--no-lock-wait**, which is the default, +**steam-runtime-supervisor** will exit with status 125 +if a lock cannot be acquired. + +</dd> +<dt> **--lock-wait-verbose** -: Same as **--lock-wait**, but if the lock cannot be acquired immediately, - log a message before waiting for it and another message after it is - acquired. + +</dt><dd> + +Same as **--lock-wait**, but if the lock cannot be acquired immediately, +log a message before waiting for it and another message after it is +acquired. + +</dd> +<dt> **--pass-fd** *FD* -: Pass the file descriptor *FD* (specified as a small positive integer) - from the parent process to the *COMMAND*, even if **--close-fds** - was specified. - This option has no practical effect if **--close-fds** was not used. + +</dt><dd> + +Pass the file descriptor *FD* (specified as a small positive integer) +from the parent process to the *COMMAND*, even if **--close-fds** +was specified. +This option has no practical effect if **--close-fds** was not used. + +</dd> +<dt> **--subreaper** -: If the *COMMAND* starts background processes, arrange for them to - be reparented to **steam-runtime-supervisor** instead of to **init** - when their parent process exits, and do not exit until all such - descendant processes have exited. + +</dt><dd> + +If the *COMMAND* starts background processes, arrange for them to +be reparented to **steam-runtime-supervisor** instead of to **init** +when their parent process exits, and do not exit until all such +descendant processes have exited. + +</dd> +<dt> **--terminate-idle-timeout** *SECONDS* -: If a non-negative **--terminate-timeout** is specified, wait this - many seconds before sending **SIGTERM** to child processes. - Non-integer decimal values are allowed. - 0 or negative means send **SIGTERM** immediately, which is the - default. - This option is ignored if **--terminate-timeout** is not used. + +</dt><dd> + +If a non-negative **--terminate-timeout** is specified, wait this +many seconds before sending **SIGTERM** to child processes. +Non-integer decimal values are allowed. +0 or negative means send **SIGTERM** immediately, which is the +default. +This option is ignored if **--terminate-timeout** is not used. + +</dd> +<dt> **--terminate-timeout** *SECONDS* -: If non-negative, terminate background processes after the *COMMAND* - exits. This implies **--subreaper**. - Non-integer decimal values are allowed. - When this option is enabled, after *COMMAND* exits, - **pressure-vessel-adverb** will wait for up to the time specified - by **--terminate-idle-timeout**, then send **SIGTERM** to any - remaining child processes and wait for them to exit gracefully. - If child processes continue to run after a further time specified - by this option, send **SIGKILL** to force them to be terminated, - and continue to send **SIGKILL** until there are no more descendant - processes. If *SECONDS* is 0, **SIGKILL** is sent immediately. - A negative number means signals are not sent, which is the default. + +</dt><dd> + +If non-negative, terminate background processes after the *COMMAND* +exits. This implies **--subreaper**. +Non-integer decimal values are allowed. +When this option is enabled, after *COMMAND* exits, +**pressure-vessel-adverb** will wait for up to the time specified +by **--terminate-idle-timeout**, then send **SIGTERM** to any +remaining child processes and wait for them to exit gracefully. +If child processes continue to run after a further time specified +by this option, send **SIGKILL** to force them to be terminated, +and continue to send **SIGKILL** until there are no more descendant +processes. If *SECONDS* is 0, **SIGKILL** is sent immediately. +A negative number means signals are not sent, which is the default. + +</dd> +<dt> **--unset-env** *VAR* -: Unset *VAR* when running the command. - This is mostly equivalent to using - **env -u** *VAR* *COMMAND* *ARGUMENTS...* - as the command. + +</dt><dd> + +Unset *VAR* when running the command. +This is mostly equivalent to using +**env -u** *VAR* *COMMAND* *ARGUMENTS...* +as the command. + +</dd> +<dt> **--verbose** -: Be more verbose. If used twice, debug messages are shown. + +</dt><dd> + +Be more verbose. If used twice, debug messages are shown. + +</dd> +</dl> # ENVIRONMENT +<dl> +<dt> + `PRESSURE_VESSEL_LOG_INFO` (boolean) -: If set to 1, same as `SRT_LOG=info` or **--verbose** + +</dt><dd> + +If set to 1, same as `SRT_LOG=info` or **--verbose** + +</dd> +<dt> `PRESSURE_VESSEL_LOG_WITH_TIMESTAMP` (boolean) -: If set to 1, same as `SRT_LOG=timestamp` + +</dt><dd> + +If set to 1, same as `SRT_LOG=timestamp` + +</dd> +<dt> `SRT_LOG` -: A sequence of tokens separated by colons, spaces or commas - affecting how output is recorded. See source code for details. + +</dt><dd> + +A sequence of tokens separated by colons, spaces or commas +affecting how output is recorded. See source code for details. + +</dd> +</dl> # OUTPUT diff --git a/bin/system-info.md b/bin/system-info.md index 5a48c4239d1c8db795aa3ce3ae3917535c03152a..a07bab366662eadaa6a0375f7f3aa15b42ce0cea 100644 --- a/bin/system-info.md +++ b/bin/system-info.md @@ -22,25 +22,52 @@ steam-runtime-system-info - examine the Steam runtime environment and diagnose p # OPTIONS +<dl> +<dt> + **--expectations** *PATH* -: Path to a directory containing details of the libraries that are - expected to be available. By default, *$STEAM_RUNTIME***/usr/lib/steamrt** - or **/usr/lib/steamrt** is used. + +</dt><dd> + +Path to a directory containing details of the libraries that are +expected to be available. By default, *$STEAM_RUNTIME***/usr/lib/steamrt** +or **/usr/lib/steamrt** is used. + +</dd> +<dt> **--no-graphics-tests** -: Don't check that graphics drivers work. - This avoids needing an X11 display, and can also save time if that - information is not required. + +</dt><dd> + +Don't check that graphics drivers work. +This avoids needing an X11 display, and can also save time if that +information is not required. + +</dd> +<dt> **--no-libraries** -: Don't check shared libraries against expectations. - This saves time if that information is not required, - particularly when using an emulation framework like FEX-Emu that - can make process startup more expensive. + +</dt><dd> + +Don't check shared libraries against expectations. +This saves time if that information is not required, +particularly when using an emulation framework like FEX-Emu that +can make process startup more expensive. + +</dd> +<dt> **--verbose** -: Show additional information. This currently adds details of all the - expected libraries that loaded successfully. + +</dt><dd> + +Show additional information. This currently adds details of all the +expected libraries that loaded successfully. + +</dd> +</dl> # OUTPUT diff --git a/bin/urlopen.md b/bin/urlopen.md index 8b97b47126c22e7a5cffdd82ba498d518762c6be..d6a65b088dc237b5827529ced1c97ce552c4ab2f 100644 --- a/bin/urlopen.md +++ b/bin/urlopen.md @@ -24,8 +24,17 @@ inside a Steam Runtime container. # OPTIONS +<dl> +<dt> + **--version** -: Instead of opening the file/URL, write in output the version number. + +</dt><dd> + +Instead of opening the file/URL, write in output the version number. + +</dd> +</dl> # OUTPUT diff --git a/pressure-vessel/adverb.1.md b/pressure-vessel/adverb.1.md index 5b1a71e8e8f0c0f065972df2d69a3babb5e079c5..55b04c26184897bca44e29f7692444f53ff884e8 100644 --- a/pressure-vessel/adverb.1.md +++ b/pressure-vessel/adverb.1.md @@ -53,237 +53,447 @@ exit status. # OPTIONS +<dl> +<dt> + **--add-ld.so-path** *PATH* -: Add *PATH* to the search path for **--regenerate-ld.so-cache**. - The final search path will consist of all **--add-ld.so-path** - arguments in the order they are given, followed by the lines - from `runtime-ld.so.conf` in order. + +</dt><dd> + +Add *PATH* to the search path for **--regenerate-ld.so-cache**. +The final search path will consist of all **--add-ld.so-path** +arguments in the order they are given, followed by the lines +from `runtime-ld.so.conf` in order. + +</dd> +<dt> **--assign-fd** _TARGET_**=**_SOURCE_ -: Make file descriptor *TARGET* in the *COMMAND* a copy of file - descriptor *SOURCE* as passed to **pressure-vessel-adverb**, - similar to writing `TARGET>&SOURCE` as a shell redirection. - For example, **--assign-fd=1=3** is the same as **1>&3**. - The redirection is done at the last possible moment, so the output - of **pressure-vessel-adverb** will still go to the original standard - error. + +</dt><dd> + +Make file descriptor *TARGET* in the *COMMAND* a copy of file +descriptor *SOURCE* as passed to **pressure-vessel-adverb**, +similar to writing `TARGET>&SOURCE` as a shell redirection. +For example, **--assign-fd=1=3** is the same as **1>&3**. +The redirection is done at the last possible moment, so the output +of **pressure-vessel-adverb** will still go to the original standard +error. + +</dd> +<dt> **--create** -: Create each **--lock-file** that appears on the command-line after - this option if it does not exist, until a **--no-create** option - is seen. **--no-create** reverses this behaviour, and is the default. + +</dt><dd> + +Create each **--lock-file** that appears on the command-line after +this option if it does not exist, until a **--no-create** option +is seen. **--no-create** reverses this behaviour, and is the default. + +</dd> +<dt> **--env** _VAR=VALUE_ -: Set environment variable _VAR_ to _VALUE_. - This is mostly equivalent to using - **env** _VAR=VALUE_ *COMMAND* *ARGUMENTS...* - as the command. + +</dt><dd> + +Set environment variable _VAR_ to _VALUE_. +This is mostly equivalent to using +**env** _VAR=VALUE_ *COMMAND* *ARGUMENTS...* +as the command. + +</dd> +<dt> **--env-fd** _FD_ -: Parse zero-terminated environment variables from _FD_, and set each - one as if via **--env**. - The format of _FD_ is the same as the output of `$(env -0)` or the - pseudo-file `/proc/PID/environ`. + +</dt><dd> + +Parse zero-terminated environment variables from _FD_, and set each +one as if via **--env**. +The format of _FD_ is the same as the output of `$(env -0)` or the +pseudo-file `/proc/PID/environ`. + +</dd> +<dt> **--exit-with-parent** -: Arrange for **pressure-vessel-adverb** to receive **SIGTERM** - (which it will pass on to *COMMAND*, if possible) when its parent - process exits. This is particularly useful when it is wrapped in - **bwrap** by **pressure-vessel-wrap**, to arrange for the - **pressure-vessel-adverb** command to exit when **bwrap** is killed. - **--no-exit-with-parent** disables this behaviour, and is the default. + +</dt><dd> + +Arrange for **pressure-vessel-adverb** to receive **SIGTERM** +(which it will pass on to *COMMAND*, if possible) when its parent +process exits. This is particularly useful when it is wrapped in +**bwrap** by **pressure-vessel-wrap**, to arrange for the +**pressure-vessel-adverb** command to exit when **bwrap** is killed. +**--no-exit-with-parent** disables this behaviour, and is the default. + +</dd> +<dt> **--fd** *FD* -: Receive file descriptor *FD* (specified as a small positive integer) - from the parent process, and keep it open until - **pressure-vessel-adverb** exits. This is most useful if *FD* - is locked with a Linux open file description lock (**F_OFD_SETLK** - or **F_OFD_SETLKW** from **fcntl**(2)), in which case the lock will - be held by **pressure-vessel-adverb**. + +</dt><dd> + +Receive file descriptor *FD* (specified as a small positive integer) +from the parent process, and keep it open until +**pressure-vessel-adverb** exits. This is most useful if *FD* +is locked with a Linux open file description lock (**F_OFD_SETLK** +or **F_OFD_SETLKW** from **fcntl**(2)), in which case the lock will +be held by **pressure-vessel-adverb**. + +</dd> +<dt> **--generate-locales** -: If not all configured locales are available, generate them in a - temporary directory which is passed to the *COMMAND* in the - **LOCPATH** environment variable. - **--no-generate-locales** disables this behaviour, and is the default. + +</dt><dd> + +If not all configured locales are available, generate them in a +temporary directory which is passed to the *COMMAND* in the +**LOCPATH** environment variable. +**--no-generate-locales** disables this behaviour, and is the default. + +</dd> +<dt> **--inherit-env** *VAR* -: Undo the effect of a previous **--env**, **--unset-env** - or similar, returning to the default behaviour of inheriting *VAR* - from the execution environment of **pressure-vessel-adverb** - (unless **--clear-env** was used, in which case this option becomes - effectively equivalent to **--unset-env**). + +</dt><dd> + +Undo the effect of a previous **--env**, **--unset-env** +or similar, returning to the default behaviour of inheriting *VAR* +from the execution environment of **pressure-vessel-adverb** +(unless **--clear-env** was used, in which case this option becomes +effectively equivalent to **--unset-env**). + +</dd> +<dt> **--inherit-env-matching** *WILDCARD* -: Do the same as for **--inherit-env** for any environment variable - whose name matches *WILDCARD*. - If this command is run from a shell, the wildcard will usually need - to be quoted, for example **--inherit-env-matching="FOO*"**. + +</dt><dd> + +Do the same as for **--inherit-env** for any environment variable +whose name matches *WILDCARD*. +If this command is run from a shell, the wildcard will usually need +to be quoted, for example **--inherit-env-matching="FOO*"**. + +</dd> +<dt> **--ld-audit** *MODULE*[**:arch=***TUPLE*] -: Add *MODULE* to **LD_AUDIT** before executing *COMMAND*. - The optional *TUPLE* is the same as for **--ld-preload**, below. + +</dt><dd> + +Add *MODULE* to **LD_AUDIT** before executing *COMMAND*. +The optional *TUPLE* is the same as for **--ld-preload**, below. + +</dd> +<dt> **--ld-preload** *MODULE*[**:arch=***TUPLE*] -: Add *MODULE* to **LD_PRELOAD** before executing *COMMAND*. - - If the optional **:arch=***TUPLE* is given, the *MODULE* is only used for - the given architecture, and is paired with other modules (if any) that - share its basename; for example, - `/home/me/.steam/root/ubuntu12_32/gameoverlayrenderer.so:arch=i386-linux-gnu` - and - `/home/me/.steam/root/ubuntu12_64/gameoverlayrenderer.so:arch=x86_64-linux-gnu` - will be combined into a single **LD_PRELOAD** entry of the form - `/tmp/pressure-vessel-libs-123456/${PLATFORM}/gameoverlayrenderer.so`. - - For a **LD_PRELOAD** module named `gameoverlayrenderer.so` in a directory - named `ubuntu12_32` or `ubuntu12_64`, the architecture is automatically - set to `i386-linux-gnu` or `x86_64-linux-gnu` respectively, if not - otherwise given. Other special-case behaviour might be added in future - if required. + +</dt><dd> + +Add *MODULE* to **LD_PRELOAD** before executing *COMMAND*. + +If the optional **:arch=***TUPLE* is given, the *MODULE* is only used for +the given architecture, and is paired with other modules (if any) that +share its basename; for example, +`/home/me/.steam/root/ubuntu12_32/gameoverlayrenderer.so:arch=i386-linux-gnu` +and +`/home/me/.steam/root/ubuntu12_64/gameoverlayrenderer.so:arch=x86_64-linux-gnu` +will be combined into a single **LD_PRELOAD** entry of the form +`/tmp/pressure-vessel-libs-123456/${PLATFORM}/gameoverlayrenderer.so`. + +For a **LD_PRELOAD** module named `gameoverlayrenderer.so` in a directory +named `ubuntu12_32` or `ubuntu12_64`, the architecture is automatically +set to `i386-linux-gnu` or `x86_64-linux-gnu` respectively, if not +otherwise given. Other special-case behaviour might be added in future +if required. + +</dd> +<dt> **--lock-file** *FILENAME* -: Lock the file *FILENAME* according to the most recently seen - **--[no-]create**, **--[no-]wait** and **--[no-]write** options, - using a Linux open file description lock (**F_OFD_SETLK** or - **F_OFD_SETLKW** from **fcntl**(2)) if possible, or a POSIX - process-associated record lock (**F_SETLK** or **F_SETLKW**) on older - kernels. - - These locks interact in the expected way with **bwrap**(1), - **flatpak**(1) and other parts of **steam-runtime-tools**. - It is unspecified whether they exclude the **flock**(2) locks used - by util-linux **flock**(1) or not, so using those locks on lock - files used by **steam-runtime-tools** should be avoided. + +</dt><dd> + +Lock the file *FILENAME* according to the most recently seen +**--[no-]create**, **--[no-]wait** and **--[no-]write** options, +using a Linux open file description lock (**F_OFD_SETLK** or +**F_OFD_SETLKW** from **fcntl**(2)) if possible, or a POSIX +process-associated record lock (**F_SETLK** or **F_SETLKW**) on older +kernels. + +These locks interact in the expected way with **bwrap**(1), +**flatpak**(1) and other parts of **steam-runtime-tools**. +It is unspecified whether they exclude the **flock**(2) locks used +by util-linux **flock**(1) or not, so using those locks on lock +files used by **steam-runtime-tools** should be avoided. + +</dd> +<dt> **--pass-fd** *FD* -: Pass the file descriptor *FD* (specified as a small positive integer) - from the parent process to the *COMMAND*. The default is to only pass - through file descriptors 0, 1 and 2 - (**stdin**, **stdout** and **stderr**). + +</dt><dd> + +Pass the file descriptor *FD* (specified as a small positive integer) +from the parent process to the *COMMAND*. The default is to only pass +through file descriptors 0, 1 and 2 +(**stdin**, **stdout** and **stderr**). + +</dd> +<dt> **--regenerate-ld.so-cache** *PATH* -: Regenerate "ld.so.cache" in the directory *PATH*. - On entry to **pressure-vessel-adverb**, *PATH* should - contain `runtime-ld.so.conf`, a symbolic link or copy - of the runtime's original `/etc/ld.so.conf`. It will - usually also contain `ld.so.conf` and `ld.so.cache` - as symbolic links or copies of the runtime's original - `/etc/ld.so.conf` and `/etc/ld.so.cache`. +</dt><dd> + +Regenerate "ld.so.cache" in the directory *PATH*. + +On entry to **pressure-vessel-adverb**, *PATH* should +contain `runtime-ld.so.conf`, a symbolic link or copy +of the runtime's original `/etc/ld.so.conf`. It will +usually also contain `ld.so.conf` and `ld.so.cache` +as symbolic links or copies of the runtime's original +`/etc/ld.so.conf` and `/etc/ld.so.cache`. - Before executing the *COMMAND*, **pressure-vessel-adverb** - will construct a new `ld.so.conf` in *PATH*, consisting of - all **--add-ld.so-path** arguments, followed by the contents - of `runtime-ld.so.conf`; then it will generate a new - `ld.so.cache` from that configuration. Both of these - will atomically replace the original files in *PATH*. +Before executing the *COMMAND*, **pressure-vessel-adverb** +will construct a new `ld.so.conf` in *PATH*, consisting of +all **--add-ld.so-path** arguments, followed by the contents +of `runtime-ld.so.conf`; then it will generate a new +`ld.so.cache` from that configuration. Both of these +will atomically replace the original files in *PATH*. - Other filenames in *PATH* will be used temporarily. +Other filenames in *PATH* will be used temporarily. - To make use of this feature, a container's `/etc/ld.so.conf` - and `/etc/ld.so.cache` should usually be symbolic links into - the *PATH* used here, which will typically be below `/run`. +To make use of this feature, a container's `/etc/ld.so.conf` +and `/etc/ld.so.cache` should usually be symbolic links into +the *PATH* used here, which will typically be below `/run`. + +</dd> +<dt> **--set-ld-library-path** *VALUE* -: Set the environment variable `LD_LIBRARY_PATH` to *VALUE* after - processing **--regenerate-ld.so-cache** (if used) and any - environment variable options such as **--env** (if used), - but before executing *COMMAND*. + +</dt><dd> + +Set the environment variable `LD_LIBRARY_PATH` to *VALUE* after +processing **--regenerate-ld.so-cache** (if used) and any +environment variable options such as **--env** (if used), +but before executing *COMMAND*. + +</dd> +<dt> **--shell=after** -: Run an interactive shell after *COMMAND* exits. - In that shell, running **"$@"** will re-run *COMMAND*. + +</dt><dd> + +Run an interactive shell after *COMMAND* exits. +In that shell, running **"$@"** will re-run *COMMAND*. + +</dd> +<dt> **--shell=fail** -: The same as **--shell=after**, but do not run the shell if *COMMAND* - exits with status 0. + +</dt><dd> + +The same as **--shell=after**, but do not run the shell if *COMMAND* +exits with status 0. + +</dd> +<dt> **--shell=instead** -: The same as **--shell=after**, but do not run *COMMAND* at all. + +</dt><dd> + +The same as **--shell=after**, but do not run *COMMAND* at all. + +</dd> +<dt> **--shell=none** -: Don't run an interactive shell. This is the default. + +</dt><dd> + +Don't run an interactive shell. This is the default. + +</dd> +<dt> **--subreaper** -: If the *COMMAND* starts background processes, arrange for them to - be reparented to **pressure-vessel-adverb** instead of to **init** - when their parent process exits, and do not exit until all such - descendant processes have exited. - A non-negative **--terminate-timeout** implies this option. + +</dt><dd> + +If the *COMMAND* starts background processes, arrange for them to +be reparented to **pressure-vessel-adverb** instead of to **init** +when their parent process exits, and do not exit until all such +descendant processes have exited. +A non-negative **--terminate-timeout** implies this option. + +</dd> +<dt> **--terminal=auto** -: Equivalent to **--terminal=xterm** if a **--shell** option other - than **none** is used, or **--terminal=none** otherwise. - This is the default. + +</dt><dd> + +Equivalent to **--terminal=xterm** if a **--shell** option other +than **none** is used, or **--terminal=none** otherwise. +This is the default. + +</dd> +<dt> **--terminal=none** -: Disable features that would ordinarily use a terminal. + +</dt><dd> + +Disable features that would ordinarily use a terminal. + +</dd> +<dt> **--terminal=tty** -: Use the current execution environment's controlling tty for - the **--shell** options. + +</dt><dd> + +Use the current execution environment's controlling tty for +the **--shell** options. + +</dd> +<dt> **--terminal=xterm** -: Start an **xterm**(1), and run *COMMAND* and/or an interactive - shell in that environment. + +</dt><dd> + +Start an **xterm**(1), and run *COMMAND* and/or an interactive +shell in that environment. + +</dd> +<dt> **--terminate-idle-timeout** *SECONDS* -: If a non-negative **--terminate-timeout** is specified, wait this - many seconds before sending **SIGTERM** to child processes. - Non-integer decimal values are allowed. - 0 or negative means send **SIGTERM** immediately, which is the - default. - This option is ignored if **--terminate-timeout** is not used. + +</dt><dd> + +If a non-negative **--terminate-timeout** is specified, wait this +many seconds before sending **SIGTERM** to child processes. +Non-integer decimal values are allowed. +0 or negative means send **SIGTERM** immediately, which is the +default. +This option is ignored if **--terminate-timeout** is not used. + +</dd> +<dt> **--terminate-timeout** *SECONDS* -: If non-negative, terminate background processes after the *COMMAND* - exits. This implies **--subreaper**. - Non-integer decimal values are allowed. - When this option is enabled, after *COMMAND* exits, - **pressure-vessel-adverb** will wait for up to the time specified - by **--terminate-idle-timeout**, then send **SIGTERM** to any - remaining child processes and wait for them to exit gracefully. - If child processes continue to run after a further time specified - by this option, send **SIGKILL** to force them to be terminated, - and continue to send **SIGKILL** until there are no more descendant - processes. If *SECONDS* is 0, **SIGKILL** is sent immediately. - A negative number means signals are not sent, which is the default. + +</dt><dd> + +If non-negative, terminate background processes after the *COMMAND* +exits. This implies **--subreaper**. +Non-integer decimal values are allowed. +When this option is enabled, after *COMMAND* exits, +**pressure-vessel-adverb** will wait for up to the time specified +by **--terminate-idle-timeout**, then send **SIGTERM** to any +remaining child processes and wait for them to exit gracefully. +If child processes continue to run after a further time specified +by this option, send **SIGKILL** to force them to be terminated, +and continue to send **SIGKILL** until there are no more descendant +processes. If *SECONDS* is 0, **SIGKILL** is sent immediately. +A negative number means signals are not sent, which is the default. + +</dd> +<dt> **--unset-env** *VAR* -: Unset *VAR* when running the command. - This is mostly equivalent to using - **env -u** *VAR* *COMMAND* *ARGUMENTS...* - as the command. + +</dt><dd> + +Unset *VAR* when running the command. +This is mostly equivalent to using +**env -u** *VAR* *COMMAND* *ARGUMENTS...* +as the command. + +</dd> +<dt> **--verbose** -: Be more verbose. + +</dt><dd> + +Be more verbose. + +</dd> +<dt> **--wait** -: For each **--lock-file** that appears on the command-line after - this option until a **--no-wait** option is seen, if the file is - already locked in an incompatible way, **pressure-vessel-adverb** - will wait for the current holder of the lock to release it. - With **--no-wait**, which is the default, **pressure-vessel-adverb** - will exit with status 75 (**EX_TEMPFAIL**) if a lock cannot be acquired. + +</dt><dd> + +For each **--lock-file** that appears on the command-line after +this option until a **--no-wait** option is seen, if the file is +already locked in an incompatible way, **pressure-vessel-adverb** +will wait for the current holder of the lock to release it. +With **--no-wait**, which is the default, **pressure-vessel-adverb** +will exit with status 75 (**EX_TEMPFAIL**) if a lock cannot be acquired. + +</dd> +<dt> **--write** -: Each **--lock-file** that appears on the command-line after - this option will be locked in **F_WRLCK** mode (an exclusive/write - lock), until a **--no-write** option is seen. **--no-write** results - in use of **F_RDLCK** (a shared/read lock), and is the default. + +</dt><dd> + +Each **--lock-file** that appears on the command-line after +this option will be locked in **F_WRLCK** mode (an exclusive/write +lock), until a **--no-write** option is seen. **--no-write** results +in use of **F_RDLCK** (a shared/read lock), and is the default. + +</dd> +</dl> # ENVIRONMENT +<dl> +<dt> + `PRESSURE_VESSEL_LOG_INFO` (boolean) -: If set to 1, same as `SRT_LOG=info` + +</dt><dd> + +If set to 1, same as `SRT_LOG=info` + +</dd> +<dt> `PRESSURE_VESSEL_LOG_WITH_TIMESTAMP` (boolean) -: If set to 1, same as `SRT_LOG=timestamp` + +</dt><dd> + +If set to 1, same as `SRT_LOG=timestamp` + +</dd> +<dt> `SRT_LOG` -: A sequence of tokens separated by colons, spaces or commas - affecting how output is recorded. See source code for details. + +</dt><dd> + +A sequence of tokens separated by colons, spaces or commas +affecting how output is recorded. See source code for details. + +</dd> +</dl> # OUTPUT diff --git a/pressure-vessel/locale-gen.1.md b/pressure-vessel/locale-gen.1.md index 207876d6044d965d9b27f46afebe60e208db4b10..93c43cf8fa146a41e36c625176606f5b831f7c91 100644 --- a/pressure-vessel/locale-gen.1.md +++ b/pressure-vessel/locale-gen.1.md @@ -32,22 +32,46 @@ they are outdated or invalid.) # OPTIONS +<dl> +<dt> + **--output-directory** *DIR*, **--output-dir** *DIR*, **-o** *DIR* -: Output to *DIR* instead of the current working directory. + +</dt><dd> + +Output to *DIR* instead of the current working directory. + +</dd> +<dt> **--verbose** -: Be more verbose. + +</dt><dd> + +Be more verbose. + +</dd> +</dl> # POSITIONAL ARGUMENTS +<dl> +<dt> + *LOCALE* -: One or more additional POSIX locale names, such as **en_US.UTF-8** or - **it_IT@euro**. By default, **pressure-vessel-locale-gen** - generates all the locales required by the standard locale environment - variables such as **LC_ALL**, plus the value of *$HOST_LC_ALL* if - set, plus the American English locale **en_US.UTF-8** (which is - frequently assumed to be present, even though many operating systems - do not guarantee it). + +</dt><dd> + +One or more additional POSIX locale names, such as **en_US.UTF-8** or +**it_IT@euro**. By default, **pressure-vessel-locale-gen** +generates all the locales required by the standard locale environment +variables such as **LC_ALL**, plus the value of *$HOST_LC_ALL* if +set, plus the American English locale **en_US.UTF-8** (which is +frequently assumed to be present, even though many operating systems +do not guarantee it). + +</dd> +</dl> # OUTPUT diff --git a/pressure-vessel/try-setlocale.1.md b/pressure-vessel/try-setlocale.1.md index 16dbf9391eeb58d712018d773829b3f2086e9e3a..7706fe5330609add2a659714db5324718e1c7609 100644 --- a/pressure-vessel/try-setlocale.1.md +++ b/pressure-vessel/try-setlocale.1.md @@ -28,10 +28,19 @@ There are no options. # POSITIONAL ARGUMENTS +<dl> +<dt> + *LOCALE* -: A POSIX locale name, such as **en_US.UTF-8** or **it_IT@euro**, - or an empty string to use the standard locale environment variables - (which is the default). + +</dt><dd> + +A POSIX locale name, such as **en_US.UTF-8** or **it_IT@euro**, +or an empty string to use the standard locale environment variables +(which is the default). + +</dd> +</dl> # OUTPUT diff --git a/pressure-vessel/unruntime.1.md b/pressure-vessel/unruntime.1.md index 03e4b210db3a5f4506c8ca873bc82de7859f660e..78ef4dd25d9eb26740fb5668bca98238d683e099 100644 --- a/pressure-vessel/unruntime.1.md +++ b/pressure-vessel/unruntime.1.md @@ -29,40 +29,94 @@ pressure-vessel-unruntime - run Steam games in a bubblewrap container All options are passed directly to **pressure-vessel-wrap**(1). One option is special: +<dl> +<dt> + `--batch` -: If present, the test-UI will not be run. + +</dt><dd> + +If present, the test-UI will not be run. + +</dd> +</dl> # ENVIRONMENT +<dl> +<dt> + `LD_LIBRARY_PATH` -: Unset, and passed to **pressure-vessel-wrap** via the - `--env-if-host` option so that it will be reinstated if the game - is run with the host `/usr`. + +</dt><dd> + +Unset, and passed to **pressure-vessel-wrap** via the +`--env-if-host` option so that it will be reinstated if the game +is run with the host `/usr`. + +</dd> +<dt> `LD_PRELOAD` -: Unset, and passed to **pressure-vessel-wrap** via the - `--env-if-host` option so that it will be reinstated if the game - is run with the host `/usr`. Individual items are also passed to - **pressure-vessel-wrap** via the **--host-ld-preload** option, - so that `LD_PRELOAD` modules can be made available read-only - in the container. + +</dt><dd> + +Unset, and passed to **pressure-vessel-wrap** via the +`--env-if-host` option so that it will be reinstated if the game +is run with the host `/usr`. Individual items are also passed to +**pressure-vessel-wrap** via the **--host-ld-preload** option, +so that `LD_PRELOAD` modules can be made available read-only +in the container. + +</dd> +<dt> `PATH` -: Reset to a sensible default, and passed to **pressure-vessel-wrap** - via the `--env-if-host` option so that it will be reinstated if the - game is run with the host `/usr`. + +</dt><dd> + +Reset to a sensible default, and passed to **pressure-vessel-wrap** +via the `--env-if-host` option so that it will be reinstated if the +game is run with the host `/usr`. + +</dd> +<dt> `PRESSURE_VESSEL_BATCH` -: If set to 1, it is equivalent to `--batch`. + +</dt><dd> + +If set to 1, it is equivalent to `--batch`. + +</dd> +<dt> `STEAM_RUNTIME` -: Unset. + +</dt><dd> + +Unset. + +</dd> +<dt> `SYSTEM_LD_LIBRARY_PATH` -: Used to reset `LD_LIBRARY_PATH` to the value it had on entry to Steam. + +</dt><dd> + +Used to reset `LD_LIBRARY_PATH` to the value it had on entry to Steam. + +</dd> +<dt> `SYSTEM_PATH` -: Used to reset `PATH` to the value it had on entry to Steam. + +</dt><dd> + +Used to reset `PATH` to the value it had on entry to Steam. + +</dd> +</dl> # SIGNALS diff --git a/pressure-vessel/verify.1.md b/pressure-vessel/verify.1.md index a2691b02be78cae5105787078fbd082201f76ee0..cd60396da1107f303199514ae7603488515dda5b 100644 --- a/pressure-vessel/verify.1.md +++ b/pressure-vessel/verify.1.md @@ -31,33 +31,75 @@ that contains pressure-vessel. # OPTIONS -`--minimized-runtime` -: Assume the *DIRECTORY* is a Steam Linux Runtime runtime in minimized - form (removing empty files, empty directories, symbolic links and so - on). This is normally the `*_platform_*/files` directory. +<dl> +<dt> -`--mtree` -: Use a non-default filename for the **mtree**(5) manifest. - It must currently be compressed with **gzip**(1) or compatible. - The default is normally `mtree.txt.gz` in the *DIRECTORY*. - If `--minimized-runtime` is used, the default is `../usr-mtree.txt.gz` - relative to the *DIRECTORY*. +**--minimized-runtime** -`--quiet` -: Don't show informational messages if the runtime is successfully verified, - just exit with status 0. +</dt><dd> -`--verbose` -: Be more verbose. +Assume the *DIRECTORY* is a Steam Linux Runtime runtime in minimized +form (removing empty files, empty directories, symbolic links and so +on). This is normally the `*_platform_*/files` directory. -`--version` -: Print the version number and exit. +</dd> +<dt> + +**--mtree** + +</dt><dd> + +Use a non-default filename for the **mtree**(5) manifest. +It must currently be compressed with **gzip**(1) or compatible. +The default is normally `mtree.txt.gz` in the *DIRECTORY*. +If `--minimized-runtime` is used, the default is `../usr-mtree.txt.gz` +relative to the *DIRECTORY*. + +</dd> +<dt> + +**--quiet** + +</dt><dd> + +Don't show informational messages if the runtime is successfully verified, +just exit with status 0. + +</dd> +<dt> + +**--verbose** + +</dt><dd> + +Be more verbose. + +</dd> +<dt> + +**--version** + +</dt><dd> + +Print the version number and exit. + +</dd> +</dl> # ENVIRONMENT +<dl> +<dt> + `SRT_LOG` -: A sequence of tokens separated by colons, spaces or commas - affecting how output is recorded. See source code for details. + +</dt><dd> + +A sequence of tokens separated by colons, spaces or commas +affecting how output is recorded. See source code for details. + +</dd> +</dl> # OUTPUT diff --git a/pressure-vessel/wrap.1.md b/pressure-vessel/wrap.1.md index d187ccd09f38cc40febe71305f9daee985eaf8c2..920d9d09ff6d92adefe0abeeff35f1bedc9692da 100644 --- a/pressure-vessel/wrap.1.md +++ b/pressure-vessel/wrap.1.md @@ -29,662 +29,1512 @@ pressure-vessel-wrap - run programs in a bubblewrap container # OPTIONS -`--batch` -: Disable all interactivity and redirection: ignore `--shell`, - all `--shell-` options, `--terminal`, `--tty` and `--xterm`. - -`--copy-runtime`, `--no-copy-runtime` -: If a `--runtime` is active, copy it into a subdirectory of the - `--variable-dir`, edit the copy in-place, and mount the copy read-only - in the container, instead of setting up elaborate bind-mount structures. - This option requires the `--variable-dir` option to be used. - - `--no-copy-runtime` disables this behaviour and is currently - the default. - -`--copy-runtime-into` *DIR* -: If *DIR* is an empty string, equivalent to `--no-copy-runtime`. - Otherwise, equivalent to `--copy-runtime --variable-dir=DIR`. - -`--deterministic` -: Process directories in a deterministic order. - This debugging option will make **pressure-vessel-wrap** slightly slower, - but makes it easier to compare log files. - -`--devel` -: Run in a mode that enables experimental or developer-oriented features. - Please see - [Steam Linux Runtime - guide for game developers](https://gitlab.steamos.cloud/steamrt/steam-runtime-tools/-/blob/main/docs/slr-for-game-developers.md#developer-mode) - for more details of the precise meaning of this option. - -`--env-if-host` *VAR=VAL* -: If *COMMAND* is run with `/usr` from the host system, set - environment variable *VAR* to *VAL*. If not, leave *VAR* unchanged. - -`--filesystem` *PATH* -: Share *PATH* from the host system with the container. - -`--freedesktop-app-id` *ID* -: If using `--unshare-home`, use *~/.var/app/ID* as the home - directory. This is the same home directory that a Flatpak app for - freedesktop.org app *ID* would use. - -`--gc-legacy-runtimes`, `--no-gc-legacy-runtimes` -: Garbage-collect old temporary runtimes in the `--runtime-base` that - appear to be left over from older versions of the **SteamLinuxRuntime** - launcher scripts. `--no-gc-legacy-runtimes` disables this behaviour, - and is the default. - -`--gc-runtimes`, `--no-gc-runtimes` -: If using `--variable-dir`, garbage-collect old temporary - runtimes that are left over from a previous **pressure-vessel-wrap**. - This is the default. `--no-gc-runtimes` disables this behaviour. - -`--generate-locales`, `--no-generate-locales` -: Passed to **pressure-vessel-adverb**(1). - The default is `--generate-locales`, overriding the default - behaviour of **pressure-vessel-adverb**(1). - -`--graphics-provider` *DIR* -: If using a `--runtime`, use *DIR* to provide graphics drivers. - - If *DIR* is the empty string, take the graphics drivers from the - runtime. This will often lead to software rendering, poor performance, - incompatibility with recent GPUs or a crash, and is only intended to - be done for development or debugging. - - Otherwise, *DIR* must be the absolute path to a directory that is - the root of an operating system installation (a "sysroot"). The - default is `/`. - -`--home` *DIR* -: Use *DIR* as the home directory. This implies `--unshare-home`. - -`--host-ld-preload` *MODULE* -: Deprecated equivalent of `--ld-preload`. Despite its name, the - *MODULE* has always been interpreted as relative to the current - execution environment, even if **pressure-vessel-wrap** is running - in a container. - -`--import-vulkan-layers`, `--no-import-vulkan-layers` -: If `--no-import-vulkan-layers` is specified, the Vulkan layers will - not be imported from the host system. - The default is `--import-vulkan-layers`. - -`--keep-game-overlay`, `--remove-game-overlay` -: If `--remove-game-overlay` is specified, remove the Steam Overlay - from the `LD_PRELOAD`. The default is `--keep-game-overlay`. - -`--launcher` -: Instead of specifying a command with its arguments to execute, all the - elements after `--` will be used as arguments for - `steam-runtime-launcher-service`. This option implies `--batch`. - -`--ld-audit` *MODULE* -: Add *MODULE* from the current execution environment to `LD_AUDIT` - when executing *COMMAND*. If *COMMAND* is run in a container, or if - **pressure-vessel-wrap** is run in a Flatpak sandbox and *COMMAND* - will be run in a different container or on the host system, then the - path of the *MODULE* will be adjusted as necessary. - -`--ld-audits` *MODULE*[**:**_MODULE_...] -: Same as `--ld-audit`, but the argument is a colon-delimited string - (the same as `$LD_AUDIT` itself). - -`--ld-preload` *MODULE* -: Add *MODULE* from the current execution environment to `LD_PRELOAD` - when executing *COMMAND*. If *COMMAND* is run in a container, or if - **pressure-vessel-wrap** is run in a Flatpak sandbox and *COMMAND* - will be run in a different container or on the host system, then the - path of the *MODULE* will be adjusted as necessary. - -`--ld-preloads` *MODULE*[**:**_MODULE_...] -: Same as `--ld-preload`, but the argument is a string delimited by - colons and/or spaces (the same as `$LD_PRELOAD` itself). - -`--only-prepare` -: Prepare the runtime, but do not actually run *COMMAND*. - With `--copy-runtime`, the prepared runtime will appear in - a subdirectory of the `--variable-dir`. - -`--pass-fd` *FD* -: Pass the file descriptor *FD* (specified as a small positive integer) - from the parent process to the *COMMAND*. The default is to only pass - through file descriptors 0, 1 and 2 - (**stdin**, **stdout** and **stderr**). - -`--runtime=` -: Use the current execution environment's /usr to provide /usr in - the container. - -`--runtime` *PATH* -: Use *PATH* to provide /usr in the container. - If *PATH*/files/ is a directory, *PATH*/files/ is used as the source - of runtime files: this is appropriate for Flatpak-style runtimes that - contain *PATH*/files/ and *PATH*/metadata. Otherwise, *PATH* is used - directly. - If *PATH*/files/usr or *PATH*/usr exists, the source of runtime files - is assumed to be a complete sysroot - (containing bin/sh, usr/bin/env and many other OS files). - Otherwise, it is assumed to be a merged-/usr environment - (containing bin/sh, bin/env and many other OS files). - For example, a Flatpak runtime is a suitable value for *PATH*. - -`--runtime-base` *PATH* -: If `--runtime` is specified as a relative path, - look for it relative to *PATH*. - -`--share-home`, `--unshare-home` -: If `--unshare-home` is specified, use the home directory given - by `--home`, `--freedesktop-app-id`, `--steam-app-id` or their - corresponding environment variables, at least one of which must be - provided. - - If `--share-home` is specified, use the home directory from the - current execution environment. - - The default is `--share-home`, unless `--home` or its - corresponding environment variable is used. - -`--share-pid`, `--unshare-pid` -: If `--unshare-pid` is specified, create a new process ID namespace. - Note that this is known to interfere with IPC between Steam and its - games. The default is `--share-pid`. - -`--shell=none` -: Don't run an interactive shell. This is the default. - -`--shell=after`, `--shell-after` -: Run an interactive shell in the container after *COMMAND* exits. - In that shell, running `"$@"` will re-run *COMMAND*. - -`--shell=fail`, `--shell-fail` -: The same as `--shell=after`, but do not run the shell if *COMMAND* - exits with status 0. - -`--shell=instead`, `--shell-instead` -: The same as `--shell=after`, but do not run *COMMAND* at all. - -`--single-thread` -: Avoid multi-threaded code paths, for debugging. - -`--steam-app-id` *N* -: Assume that we are running Steam app ID *N*, specified as an integer. - If using `--unshare-home`, use *~/.var/app/com.steampowered.AppN* - as the home directory. - -`--systemd-scope`, `--no-systemd-scope` -: If `--systemd-scope` is specified, attempt to put the game into a - `systemd --user` scope. Its name will be similar to - `app-steam-app975370-12345.scope`, or `app-steam-unknown-12345.scope` - if the Steam app ID is not known (for example when running the - `Help -> System Information` diagnostic tools). The scope can be viewed - with `systemctl --user` or `systemd-cgls`, and can be terminated with - a command like `systemctl --user kill app-steam-app975370-12345.scope`. - - These options have no effect if pressure-vessel cannot contact - systemd's D-Bus interface, and in particular they do not prevent - pressure-vessel from working on machines that do not have systemd. - - These options have no effect when running under Flatpak. Flatpak will - always try to put the game in a scope with a name like - `app-flatpak-com.valvesoftware.Steam-12345.scope`, separate from the - scope used to run Steam itself. - - The default is `--no-systemd-scope`. - -`--terminal=none` -: Disable features that would ordinarily use a terminal. - -`--terminal=auto` -: Equivalent to `--terminal=xterm` if a `--shell` option other - than `none` is used, or `--terminal=none` otherwise. - -`--terminal=tty`, `--tty` -: Use the current execution environment's controlling tty for - the `--shell` options. - -`--terminal=xterm`, `--xterm` -: Start an **xterm**(1) inside the container. - -`--terminate-timeout` *SECONDS*, `--terminate-idle-timeout` *SECONDS* -: Passed to **pressure-vessel-wrap**(1). - -`--test` -: Perform a smoke-test to determine whether **pressure-vessel-wrap** - can work, and exit. Exit with status 0 if it can or 1 if it cannot. - -`--variable-dir` *PATH* -: Use *PATH* as a cache directory for files that are temporarily - unpacked or copied. It will be created automatically if necessary. - -`--verbose` -: Be more verbose. - -`--version` -: Print the version number and exit. - -`--with-host-graphics`, `--without-host-graphics` -: Deprecated form of `--graphics-provider`. - `--with-host-graphics` is equivalent to either - `--graphics-provider=/run/host` if it looks suitable, or - `--graphics-provider=/` if not. - `--without-host-graphics` is equivalent to `--graphics-provider=""`. +<dl> +<dt> + +**--batch** + +</dt><dd> + +Disable all interactivity and redirection: ignore `--shell`, +all `--shell-` options, `--terminal`, `--tty` and `--xterm`. + +</dd> +<dt> + +**--copy-runtime**, **--no-copy-runtime** + +</dt><dd> + +If a `--runtime` is active, copy it into a subdirectory of the +`--variable-dir`, edit the copy in-place, and mount the copy read-only +in the container, instead of setting up elaborate bind-mount structures. +This option requires the `--variable-dir` option to be used. + +`--no-copy-runtime` disables this behaviour and is currently +the default. + +</dd> +<dt> + +**--copy-runtime-into** *DIR* + +</dt><dd> + +If *DIR* is an empty string, equivalent to `--no-copy-runtime`. +Otherwise, equivalent to `--copy-runtime --variable-dir=DIR`. + +</dd> +<dt> + +**--deterministic** + +</dt><dd> + +Process directories in a deterministic order. +This debugging option will make **pressure-vessel-wrap** slightly slower, +but makes it easier to compare log files. + +</dd> +<dt> + +**--devel** + +</dt><dd> + +Run in a mode that enables experimental or developer-oriented features. +Please see +[Steam Linux Runtime - guide for game developers](https://gitlab.steamos.cloud/steamrt/steam-runtime-tools/-/blob/main/docs/slr-for-game-developers.md#developer-mode) +for more details of the precise meaning of this option. + +</dd> +<dt> + +**--env-if-host** *VAR=VAL* + +</dt><dd> + +If *COMMAND* is run with `/usr` from the host system, set +environment variable *VAR* to *VAL*. If not, leave *VAR* unchanged. + +</dd> +<dt> + +**--filesystem** *PATH* + +</dt><dd> + +Share *PATH* from the host system with the container. + +</dd> +<dt> + +**--freedesktop-app-id** *ID* + +</dt><dd> + +If using `--unshare-home`, use *~/.var/app/ID* as the home +directory. This is the same home directory that a Flatpak app for +freedesktop.org app *ID* would use. + +</dd> +<dt> + +**--gc-legacy-runtimes**, **--no-gc-legacy-runtimes** + +</dt><dd> + +Garbage-collect old temporary runtimes in the `--runtime-base` that +appear to be left over from older versions of the **SteamLinuxRuntime** +launcher scripts. `--no-gc-legacy-runtimes` disables this behaviour, +and is the default. + +</dd> +<dt> + +**--gc-runtimes**, **--no-gc-runtimes** + +</dt><dd> + +If using `--variable-dir`, garbage-collect old temporary +runtimes that are left over from a previous **pressure-vessel-wrap**. +This is the default. `--no-gc-runtimes` disables this behaviour. + +</dd> +<dt> + +</dd> +<dt> + +**--generate-locales**, **--no-generate-locales** + +</dt><dd> + +Passed to **pressure-vessel-adverb**(1). +The default is `--generate-locales`, overriding the default +behaviour of **pressure-vessel-adverb**(1). + +</dd> +<dt> + +**--graphics-provider** *DIR* + +</dt><dd> + +If using a `--runtime`, use *DIR* to provide graphics drivers. + +If *DIR* is the empty string, take the graphics drivers from the +runtime. This will often lead to software rendering, poor performance, +incompatibility with recent GPUs or a crash, and is only intended to +be done for development or debugging. + +Otherwise, *DIR* must be the absolute path to a directory that is +the root of an operating system installation (a "sysroot"). The +default is `/`. + +</dd> +<dt> + +**--home** *DIR* + +</dt><dd> + +Use *DIR* as the home directory. This implies `--unshare-home`. + +</dd> +<dt> + +**--host-ld-preload** *MODULE* + +</dt><dd> + +Deprecated equivalent of `--ld-preload`. Despite its name, the +*MODULE* has always been interpreted as relative to the current +execution environment, even if **pressure-vessel-wrap** is running +in a container. + +</dd> +<dt> + +**--import-vulkan-layers**, **--no-import-vulkan-layers** + +</dt><dd> + +If `--no-import-vulkan-layers` is specified, the Vulkan layers will +not be imported from the host system. +The default is `--import-vulkan-layers`. + +</dd> +<dt> + +**--keep-game-overlay**, **--remove-game-overlay** + +</dt><dd> + +If `--remove-game-overlay` is specified, remove the Steam Overlay +from the `LD_PRELOAD`. The default is `--keep-game-overlay`. + +</dd> +<dt> + +**--launcher** + +</dt><dd> + +Instead of specifying a command with its arguments to execute, all the +elements after `--` will be used as arguments for +`steam-runtime-launcher-service`. This option implies `--batch`. + +</dd> +<dt> + +**--ld-audit** *MODULE* + +</dt><dd> + +Add *MODULE* from the current execution environment to `LD_AUDIT` +when executing *COMMAND*. If *COMMAND* is run in a container, or if +**pressure-vessel-wrap** is run in a Flatpak sandbox and *COMMAND* +will be run in a different container or on the host system, then the +path of the *MODULE* will be adjusted as necessary. + +</dd> +<dt> + +**--ld-audits** *MODULE*[**:**_MODULE_...] + +</dt><dd> + +Same as `--ld-audit`, but the argument is a colon-delimited string +(the same as `$LD_AUDIT` itself). + +</dd> +<dt> + +**--ld-preload** *MODULE* + +</dt><dd> + +Add *MODULE* from the current execution environment to `LD_PRELOAD` +when executing *COMMAND*. If *COMMAND* is run in a container, or if +**pressure-vessel-wrap** is run in a Flatpak sandbox and *COMMAND* +will be run in a different container or on the host system, then the +path of the *MODULE* will be adjusted as necessary. + +</dd> +<dt> + +**--ld-preloads** *MODULE*[**:**_MODULE_...] + +</dt><dd> + +Same as `--ld-preload`, but the argument is a string delimited by +colons and/or spaces (the same as `$LD_PRELOAD` itself). + +</dd> +<dt> + +**--only-prepare** + +</dt><dd> + +Prepare the runtime, but do not actually run *COMMAND*. +With `--copy-runtime`, the prepared runtime will appear in +a subdirectory of the `--variable-dir`. + +</dd> +<dt> + +**--pass-fd** *FD* + +</dt><dd> + +Pass the file descriptor *FD* (specified as a small positive integer) +from the parent process to the *COMMAND*. The default is to only pass +through file descriptors 0, 1 and 2 +(**stdin**, **stdout** and **stderr**). + +</dd> +<dt> + +**--runtime=** + +</dt><dd> + +Use the current execution environment's /usr to provide /usr in +the container. + +</dd> +<dt> + +**--runtime** *PATH* + +</dt><dd> + +Use *PATH* to provide /usr in the container. +If *PATH*/files/ is a directory, *PATH*/files/ is used as the source +of runtime files: this is appropriate for Flatpak-style runtimes that +contain *PATH*/files/ and *PATH*/metadata. Otherwise, *PATH* is used +directly. + +If *PATH*/files/usr or *PATH*/usr exists, the source of runtime files +is assumed to be a complete sysroot +(containing bin/sh, usr/bin/env and many other OS files). +Otherwise, it is assumed to be a merged-/usr environment +(containing bin/sh, bin/env and many other OS files). +For example, a Flatpak runtime is a suitable value for *PATH*. + +</dd> +<dt> + +**--runtime-base** *PATH* + +</dt><dd> + +If `--runtime` is specified as a relative path, +look for it relative to *PATH*. + +</dd> +<dt> + +**--share-home**, **--unshare-home** + +</dt><dd> + +If `--unshare-home` is specified, use the home directory given +by `--home`, `--freedesktop-app-id`, `--steam-app-id` or their +corresponding environment variables, at least one of which must be +provided. + +If `--share-home` is specified, use the home directory from the +current execution environment. + +The default is `--share-home`, unless `--home` or its +corresponding environment variable is used. + +</dd> +<dt> + +**--share-pid**, **--unshare-pid** + +</dt><dd> + +If `--unshare-pid` is specified, create a new process ID namespace. +Note that this is known to interfere with IPC between Steam and its +games. The default is `--share-pid`. + +</dd> +<dt> + +**--shell=none** + +</dt><dd> + +Don't run an interactive shell. This is the default. + +</dd> +<dt> + +**--shell=after**, **--shell-after** + +</dt><dd> + +Run an interactive shell in the container after *COMMAND* exits. +In that shell, running `"$@"` will re-run *COMMAND*. + +</dd> +<dt> + +**--shell=fail**, **--shell-fail** + +</dt><dd> + +The same as `--shell=after`, but do not run the shell if *COMMAND* +exits with status 0. + +</dd> +<dt> + +**--shell=instead**, **--shell-instead** + +</dt><dd> + +The same as `--shell=after`, but do not run *COMMAND* at all. + +</dd> +<dt> + +**--single-thread** + +</dt><dd> + +Avoid multi-threaded code paths, for debugging. + +</dd> +<dt> + +**--steam-app-id** *N* + +</dt><dd> + +Assume that we are running Steam app ID *N*, specified as an integer. +If using `--unshare-home`, use *~/.var/app/com.steampowered.AppN* +as the home directory. + +</dd> +<dt> + +**--systemd-scope**, **--no-systemd-scope** + +</dt><dd> + +If `--systemd-scope` is specified, attempt to put the game into a +`systemd --user` scope. Its name will be similar to +`app-steam-app975370-12345.scope`, or `app-steam-unknown-12345.scope` +if the Steam app ID is not known (for example when running the +`Help -> System Information` diagnostic tools). The scope can be viewed +with `systemctl --user` or `systemd-cgls`, and can be terminated with +a command like `systemctl --user kill app-steam-app975370-12345.scope`. + +These options have no effect if pressure-vessel cannot contact +systemd's D-Bus interface, and in particular they do not prevent +pressure-vessel from working on machines that do not have systemd. + +These options have no effect when running under Flatpak. Flatpak will +always try to put the game in a scope with a name like +`app-flatpak-com.valvesoftware.Steam-12345.scope`, separate from the +scope used to run Steam itself. + +The default is `--no-systemd-scope`. + +</dd> +<dt> + +**--terminal=none** + +</dt><dd> + +Disable features that would ordinarily use a terminal. + +</dd> +<dt> + +**--terminal=auto** + +</dt><dd> + +Equivalent to `--terminal=xterm` if a `--shell` option other +than `none` is used, or `--terminal=none` otherwise. + +</dd> +<dt> + +**--terminal=tty**, **--tty** + +</dt><dd> + +Use the current execution environment's controlling tty for +the `--shell` options. + +</dd> +<dt> + +**--terminal=xterm**, **--xterm** + +</dt><dd> + +Start an **xterm**(1) inside the container. + +</dd> +<dt> + +**--terminate-timeout** *SECONDS*, **--terminate-idle-timeout** *SECONDS* + +</dt><dd> + +Passed to **pressure-vessel-adverb**(1). + +</dd> +<dt> + +**--test** + +</dt><dd> + +Perform a smoke-test to determine whether **pressure-vessel-wrap** +can work, and exit. Exit with status 0 if it can or 1 if it cannot. + +</dd> +<dt> + +**--variable-dir** *PATH* + +</dt><dd> + +Use *PATH* as a cache directory for files that are temporarily +unpacked or copied. It will be created automatically if necessary. + +</dd> +<dt> + +**--verbose** + +</dt><dd> + +Be more verbose. + +</dd> +<dt> + +**--version** + +</dt><dd> + +Print the version number and exit. + +</dd> +<dt> + +**--with-host-graphics**, **--without-host-graphics** + +</dt><dd> + +Deprecated form of `--graphics-provider`. +`--with-host-graphics` is equivalent to either +`--graphics-provider=/run/host` if it looks suitable, or +`--graphics-provider=/` if not. +`--without-host-graphics` is equivalent to `--graphics-provider=""`. + +</dd> +</dl> # ENVIRONMENT The following environment variables (among others) are read by **pressure-vessel-wrap**(1). +<dl> +<dt> + `__EGL_VENDOR_LIBRARY_DIRS`, `__EGL_VENDOR_LIBRARY_FILENAMES` -: Used to locate EGL ICDs to be made available in the container - if `--runtime` and `--graphics-provider` are active. + +</dt><dd> + +Used to locate EGL ICDs to be made available in the container +if `--runtime` and `--graphics-provider` are active. + +</dd> +<dt> `BWRAP` (path) -: Absolute path to **bwrap**(1). - The default is to try several likely locations. + +</dt><dd> + +Absolute path to **bwrap**(1). +The default is to try several likely locations. + +</dd> +<dt> `DBUS_SESSION_BUS_ADDRESS`, `DBUS_SYSTEM_BUS_ADDRESS` -: Used to locate the well-known D-Bus session and system buses - so that they can be made available in the container. + +</dt><dd> + +Used to locate the well-known D-Bus session and system buses +so that they can be made available in the container. + +</dd> +<dt> `DISPLAY` -: Used to locate the X11 display to make available in the container. + +</dt><dd> + +Used to locate the X11 display to make available in the container. + +</dd> +<dt> `FLATPAK_ID` -: Used to locate the app-specific data directory when running in a - Flatpak environment. + +</dt><dd> + +Used to locate the app-specific data directory when running in a +Flatpak environment. + +</dd> +<dt> `LIBGL_DRIVERS_PATH` -: Used to locate Mesa DRI drivers to be made available in the container - if `--runtime` and `--graphics-provider` are active. + +</dt><dd> + +Used to locate Mesa DRI drivers to be made available in the container +if `--runtime` and `--graphics-provider` are active. + +</dd> +<dt> `LIBVA_DRIVERS_PATH` -: Used to locate VA-API drivers to be made available in the container - if `--runtime` and `--graphics-provider` are active. + +</dt><dd> + +Used to locate VA-API drivers to be made available in the container +if `--runtime` and `--graphics-provider` are active. + +</dd> +<dt> `PRESSURE_VESSEL_BATCH` (boolean) -: If set to `1`, equivalent to `--batch`. - If set to `0`, no effect. + +</dt><dd> + +If set to `1`, equivalent to `--batch`. +If set to `0`, no effect. + +</dd> +<dt> `PRESSURE_VESSEL_COPY_RUNTIME` (boolean) -: If set to `1`, equivalent to `--copy-runtime`. - If set to `0`, equivalent to `--no-copy-runtime`. + +</dt><dd> + +If set to `1`, equivalent to `--copy-runtime`. +If set to `0`, equivalent to `--no-copy-runtime`. + +</dd> +<dt> `PRESSURE_VESSEL_COPY_RUNTIME_INTO` (path or empty string) -: If the string is empty, it is a deprecated equivalent of - `--no-copy-runtime`. Otherwise, it is a deprecated equivalent of - `--copy-runtime --variable-dir="$PRESSURE_VESSEL_COPY_RUNTIME_INTO"`. + +</dt><dd> + +If the string is empty, it is a deprecated equivalent of +`--no-copy-runtime`. Otherwise, it is a deprecated equivalent of +`--copy-runtime --variable-dir="$PRESSURE_VESSEL_COPY_RUNTIME_INTO"`. + +</dd> +<dt> `PRESSURE_VESSEL_DETERMINISTIC` (boolean) -: If set to `1`, equivalent to `--deterministic`. - If set to `0`, no effect. + +</dt><dd> + +If set to `1`, equivalent to `--deterministic`. +If set to `0`, no effect. + +</dd> +<dt> `PRESSURE_VESSEL_DEVEL` (boolean) -: If set to `1`, equivalent to `--devel`. - If set to `0`, no effect. + +</dt><dd> + +If set to `1`, equivalent to `--devel`. +If set to `0`, no effect. + +</dd> +<dt> `PRESSURE_VESSEL_FILESYSTEMS_RO` (`:`-separated list of paths) -: Make these paths available read-only inside the container if they - exist, similar to `--filesystem` but read-only. - For example, MangoHUD and vkBasalt users might use - `PRESSURE_VESSEL_FILESYSTEMS_RO="$MANGOHUD_CONFIGFILE:$VKBASALT_CONFIG_FILE"` - if the configuration files are outside the home directory. + +</dt><dd> + +Make these paths available read-only inside the container if they +exist, similar to `--filesystem` but read-only. +For example, MangoHUD and vkBasalt users might use +`PRESSURE_VESSEL_FILESYSTEMS_RO="$MANGOHUD_CONFIGFILE:$VKBASALT_CONFIG_FILE"` +if the configuration files are outside the home directory. + +</dd> +<dt> `PRESSURE_VESSEL_FILESYSTEMS_RW` (`:`-separated list of paths) -: Make these paths available read/write inside the container if they - exist, similar to `--filesystem`. + +</dt><dd> + +Make these paths available read/write inside the container if they +exist, similar to `--filesystem`. + +</dd> +<dt> `PRESSURE_VESSEL_FDO_APP_ID` (string) -: Equivalent to - `--freedesktop-app-id="$PRESSURE_VESSEL_FDO_APP_ID"`. + +</dt><dd> + +Equivalent to +`--freedesktop-app-id="$PRESSURE_VESSEL_FDO_APP_ID"`. + +</dd> +<dt> `PRESSURE_VESSEL_GC_RUNTIMES` (boolean) -: If set to `1`, equivalent to `--gc-runtimes`. - If set to `0`, equivalent to `--no-gc-runtimes`. + +</dt><dd> + +If set to `1`, equivalent to `--gc-runtimes`. +If set to `0`, equivalent to `--no-gc-runtimes`. + +</dd> +<dt> `PRESSURE_VESSEL_GENERATE_LOCALES` (boolean) -: If set to `1`, equivalent to `--generate-locales`. - If set to `0`, equivalent to `--no-generate-locales`. + +</dt><dd> + +If set to `1`, equivalent to `--generate-locales`. +If set to `0`, equivalent to `--no-generate-locales`. + +</dd> +<dt> `PRESSURE_VESSEL_GRAPHICS_PROVIDER` (absolute path or empty string) -: Equivalent to `--graphics-provider="$PRESSURE_VESSEL_GRAPHICS_PROVIDER"`. + +</dt><dd> + +Equivalent to `--graphics-provider="$PRESSURE_VESSEL_GRAPHICS_PROVIDER"`. + +</dd> +<dt> `PRESSURE_VESSEL_HOME` (path) -: Equivalent to `--home="$PRESSURE_VESSEL_HOME"`. + +</dt><dd> + +Equivalent to `--home="$PRESSURE_VESSEL_HOME"`. + +</dd> +<dt> `PRESSURE_VESSEL_HOST_GRAPHICS` (boolean) -: Deprecated form of `$PRESSURE_VESSEL_GRAPHICS_PROVIDER`. - If set to `1`, equivalent to either - `--graphics-provider=/run/host` if it looks suitable, or - `--graphics-provider=/` if not. - If set to `0`, equivalent to `--graphics-provider=""`. + +</dt><dd> + +Deprecated form of `$PRESSURE_VESSEL_GRAPHICS_PROVIDER`. +If set to `1`, equivalent to either +`--graphics-provider=/run/host` if it looks suitable, or +`--graphics-provider=/` if not. +If set to `0`, equivalent to `--graphics-provider=""`. + +</dd> +<dt> `PRESSURE_VESSEL_IMPORT_VULKAN_LAYERS` (boolean) -: If set to `1`, equivalent to `--import-vulkan-layers`. - If set to `0`, equivalent to `--no-import-vulkan-layers`. + +</dt><dd> + +If set to `1`, equivalent to `--import-vulkan-layers`. +If set to `0`, equivalent to `--no-import-vulkan-layers`. + +</dd> +<dt> `PRESSURE_VESSEL_LOG_INFO` (boolean) -: If set to 1, same as `SRT_LOG=info` + +</dt><dd> + +If set to 1, same as `SRT_LOG=info` + +</dd> +<dt> `PRESSURE_VESSEL_LOG_WITH_TIMESTAMP` (boolean) -: If set to 1, same as `SRT_LOG=timestamp` + +</dt><dd> + +If set to 1, same as `SRT_LOG=timestamp` + +</dd> +<dt> `PRESSURE_VESSEL_PREFIX` (path) -: pressure-vessel itself does not use this, - but the Steam Linux Runtime container runtime framework uses it to - locate a custom version of pressure-vessel. - If used, it must be set to a relocatable build of pressure-vessel, - so that `$PRESSURE_VESSEL_PREFIX/bin/pressure-vessel-unruntime` exists. + +</dt><dd> + +pressure-vessel itself does not use this, +but the Steam Linux Runtime container runtime framework uses it to +locate a custom version of pressure-vessel. +If used, it must be set to a relocatable build of pressure-vessel, +so that `$PRESSURE_VESSEL_PREFIX/bin/pressure-vessel-unruntime` exists. + +</dd> +<dt> `PRESSURE_VESSEL_REMOVE_GAME_OVERLAY` (boolean) -: If set to `1`, equivalent to `--remove-game-overlay`. - If set to `0`, equivalent to `--keep-game-overlay`. + +</dt><dd> + +If set to `1`, equivalent to `--remove-game-overlay`. +If set to `0`, equivalent to `--keep-game-overlay`. + +</dd> +<dt> `PRESSURE_VESSEL_RUNTIME` (path, filename or empty string) -: Equivalent to `--runtime="$PRESSURE_VESSEL_RUNTIME"`. + +</dt><dd> + +Equivalent to `--runtime="$PRESSURE_VESSEL_RUNTIME"`. + +</dd> +<dt> `PRESSURE_VESSEL_RUNTIME_BASE` (path, filename or empty string) -: Equivalent to `--runtime-base="$PRESSURE_VESSEL_RUNTIME_BASE"`. + +</dt><dd> + +Equivalent to `--runtime-base="$PRESSURE_VESSEL_RUNTIME_BASE"`. + +</dd> +<dt> `PRESSURE_VESSEL_SHARE_HOME` (boolean) -: If set to `1`, equivalent to `--share-home`. - If set to `0`, equivalent to `--unshare-home`. + +</dt><dd> + +If set to `1`, equivalent to `--share-home`. +If set to `0`, equivalent to `--unshare-home`. + +</dd> +<dt> `PRESSURE_VESSEL_SHARE_PID` (boolean) -: If set to `1`, equivalent to `--share-pid`. - If set to `0`, equivalent to `--unshare-pid`. + +</dt><dd> + +If set to `1`, equivalent to `--share-pid`. +If set to `0`, equivalent to `--unshare-pid`. + +</dd> +<dt> `PRESSURE_VESSEL_SHELL` (`none`, `after`, `fail` or `instead`) -: Equivalent to `--shell="$PRESSURE_VESSEL_SHELL"`. + +</dt><dd> + +Equivalent to `--shell="$PRESSURE_VESSEL_SHELL"`. + +</dd> +<dt> `PRESSURE_VESSEL_SYSTEMD_SCOPE` (boolean) -: If set to `1`, equivalent to `--systemd-scope`. - If set to `0`, equivalent to `--no-systemd-scope`. + +</dt><dd> + +If set to `1`, equivalent to `--systemd-scope`. +If set to `0`, equivalent to `--no-systemd-scope`. + +</dd> +<dt> `PRESSURE_VESSEL_TERMINAL` (`none`, `auto`, `tty` or `xterm`) -: Equivalent to `--terminal="$PRESSURE_VESSEL_TERMINAL"`. + +</dt><dd> + +Equivalent to `--terminal="$PRESSURE_VESSEL_TERMINAL"`. + +</dd> +<dt> `PRESSURE_VESSEL_VARIABLE_DIR` (path) -: Equivalent to `--variable-dir="$PRESSURE_VESSEL_VARIABLE_DIR"`. + +</dt><dd> + +Equivalent to `--variable-dir="$PRESSURE_VESSEL_VARIABLE_DIR"`. + +</dd> +<dt> `PRESSURE_VESSEL_VERBOSE` (boolean) -: If set to `1`, equivalent to `--verbose`. + +</dt><dd> + +If set to `1`, equivalent to `--verbose`. + +</dd> +<dt> `PRESSURE_VESSEL_WORKAROUNDS` (tokens separated by space, tab and/or comma) -: Tokens of the form `foo` or `+foo` enable various workarounds. - Tokens of the form `-foo` or `!foo` disable the corresponding workaround. - See pressure-vessel source code for details. - The default is to auto-detect which workarounds are needed. + +</dt><dd> + +Tokens of the form `foo` or `+foo` enable various workarounds. +Tokens of the form `-foo` or `!foo` disable the corresponding workaround. +See pressure-vessel source code for details. +The default is to auto-detect which workarounds are needed. + +</dd> +<dt> `PULSE_CLIENTCONFIG` -: Used to locate PulseAudio client configuration. + +</dt><dd> + +Used to locate PulseAudio client configuration. + +</dd> +<dt> `PULSE_SERVER` -: Used to locate a PulseAudio server. + +</dt><dd> + +Used to locate a PulseAudio server. + +</dd> +<dt> `PWD` -: Used to choose between logically equivalent names for the current - working directory (see **get_current_dir_name**(3)). + +</dt><dd> + +Used to choose between logically equivalent names for the current +working directory (see **get_current_dir_name**(3)). + +</dd> +<dt> `SRT_LAUNCHER_SERVICE` (path) -: pressure-vessel itself does not use this, - but in the Steam Linux Runtime container runtime framework, - it sets an implementation of **steam-runtime-launcher-service**(1) - to use instead of selecting one automatically. + +</dt><dd> + +pressure-vessel itself does not use this, +but in the Steam Linux Runtime container runtime framework, +it sets an implementation of **steam-runtime-launcher-service**(1) +to use instead of selecting one automatically. + +</dd> +<dt> `SRT_LAUNCHER_SERVICE_STOP_ON_EXIT` (boolean) -: pressure-vessel itself does not use this, - but in the Steam Linux Runtime container runtime framework, - setting it to `0` prevents the service started by - **STEAM_COMPAT_LAUNCHER_SERVICE** from exiting until it is specifically - terminated by `steam-runtime-launch-client --terminate` or a signal. + +</dt><dd> + +pressure-vessel itself does not use this, +but in the Steam Linux Runtime container runtime framework, +setting it to `0` prevents the service started by +**STEAM_COMPAT_LAUNCHER_SERVICE** from exiting until it is specifically +terminated by `steam-runtime-launch-client --terminate` or a signal. + +</dd> +<dt> `SRT_LOG` -: A sequence of tokens separated by colons, spaces or commas - affecting how output is recorded. See source code for details. + +</dt><dd> + +A sequence of tokens separated by colons, spaces or commas +affecting how output is recorded. See source code for details. + +</dd> +<dt> `SRT_LOG_ROTATION` (boolean) -: pressure-vessel itself does not use this, - but in the Steam Linux Runtime container runtime framework, - setting it to `0` prevents cleanup of old log files. + +</dt><dd> + +pressure-vessel itself does not use this, +but in the Steam Linux Runtime container runtime framework, +setting it to `0` prevents cleanup of old log files. + +</dd> +<dt> `STEAM_COMPAT_APP_ID` (integer) -: Equivalent to `--steam-app-id="$STEAM_COMPAT_APP_ID"`. + +</dt><dd> + +Equivalent to `--steam-app-id="$STEAM_COMPAT_APP_ID"`. + +</dd> +<dt> `STEAM_COMPAT_APP_LIBRARY_PATH` (path) -: Deprecated equivalent of `STEAM_COMPAT_MOUNTS`, except that it is - a single path instead of being colon-delimited. + +</dt><dd> + +Deprecated equivalent of `STEAM_COMPAT_MOUNTS`, except that it is +a single path instead of being colon-delimited. + +</dd> +<dt> `STEAM_COMPAT_APP_LIBRARY_PATHS` (`:`-separated list of paths) -: Deprecated equivalent of `STEAM_COMPAT_MOUNTS`. + +</dt><dd> + +Deprecated equivalent of `STEAM_COMPAT_MOUNTS`. + +</dd> +<dt> `STEAM_COMPAT_CLIENT_INSTALL_PATH` (path) -: When used as a Steam compatibility tool, the absolute path to the - Steam client installation directory. - This is made available read/write in the container. + +</dt><dd> + +When used as a Steam compatibility tool, the absolute path to the +Steam client installation directory. +This is made available read/write in the container. + +</dd> +<dt> `STEAM_COMPAT_DATA_PATH` (path) -: When used as a Steam compatibility tool, the absolute path to the - variable data directory used by Proton, if any. - This is made available read/write in the container. + +</dt><dd> + +When used as a Steam compatibility tool, the absolute path to the +variable data directory used by Proton, if any. +This is made available read/write in the container. + +</dd> +<dt> `STEAM_COMPAT_FLAGS` (comma-separated list of tokens) -: `runtime-sdl2` is equivalent to `STEAM_COMPAT_RUNTIME_SDL2=1`. - `runtime-sdl3` is equivalent to `STEAM_COMPAT_RUNTIME_SDL3=1`. - Other tokens are ignored by pressure-vessel-wrap, but might - have an effect on other components. + +</dt><dd> + +`runtime-sdl2` is equivalent to `STEAM_COMPAT_RUNTIME_SDL2=1`. +`runtime-sdl3` is equivalent to `STEAM_COMPAT_RUNTIME_SDL3=1`. +Other tokens are ignored by pressure-vessel-wrap, but might +have an effect on other components. + +</dd> +<dt> `STEAM_COMPAT_INSTALL_PATH` (path) -: Top-level directory containing the game itself, even if the current - working directory is actually a subdirectory of this. - This is made available read/write in the container. + +</dt><dd> + +Top-level directory containing the game itself, even if the current +working directory is actually a subdirectory of this. +This is made available read/write in the container. + +</dd> +<dt> `STEAM_COMPAT_LAUNCHER_SERVICE` (token) -: pressure-vessel itself does not use this, - but in the Steam Linux Runtime container runtime framework, - setting it to **container-runtime** provides a D-Bus service - which can be used to send debugging commands into the container - environment. - In Steam Linux Runtime 1.0, - setting it to **scout-in-container** provides a similar D-Bus service - where the execution environment is compatible with Steam Runtime 1 'scout'. - In Proton, setting it to **proton** provides a similar D-Bus service - with an execution environment that is preconfigured to run Proton's - version of Wine. - See **steam-runtime-launch-client**(1) for examples of how to use this. + +</dt><dd> + +pressure-vessel itself does not use this, +but in the Steam Linux Runtime container runtime framework, +setting it to **container-runtime** provides a D-Bus service +which can be used to send debugging commands into the container +environment. +In Steam Linux Runtime 1.0, +setting it to **scout-in-container** provides a similar D-Bus service +where the execution environment is compatible with Steam Runtime 1 'scout'. +In Proton, setting it to **proton** provides a similar D-Bus service +with an execution environment that is preconfigured to run Proton's +version of Wine. +See **steam-runtime-launch-client**(1) for examples of how to use this. + +</dd> +<dt> `STEAM_COMPAT_LIBRARY_PATHS` (`:`-separated list of paths) -: Colon-delimited list of paths to Steam Library directories containing - the game, the compatibility tools if any, and any other resources - that the game will need, such as DirectX installers. - Each is currently made available read/write in the container. + +</dt><dd> + +Colon-delimited list of paths to Steam Library directories containing +the game, the compatibility tools if any, and any other resources +that the game will need, such as DirectX installers. +Each is currently made available read/write in the container. + +</dd> +<dt> `STEAM_COMPAT_MOUNT_PATHS` (`:`-separated list of paths) -: Deprecated equivalent of `STEAM_COMPAT_MOUNTS`. + +</dt><dd> + +Deprecated equivalent of `STEAM_COMPAT_MOUNTS`. + +</dd> +<dt> `STEAM_COMPAT_MOUNTS` (`:`-separated list of paths) -: Colon-delimited list of paths to additional directories that are to - be made available read/write in the container. + +</dt><dd> + +Colon-delimited list of paths to additional directories that are to +be made available read/write in the container. + +</dd> +<dt> `STEAM_COMPAT_RUNTIME_SDL2` (boolean) -: If set to `1`, set `SDL_DYNAMIC_API` so that the runtime's version - of SDL 2 will be used in preference to any copy that might be bundled - or statically linked in an app or game (as long as it is version ≥ 2.0.2 - and the `dynapi` feature has not been disabled). - The advantage of this variable over setting `SDL_DYNAMIC_API` directly - is that pressure-vessel-wrap sets up appropriate distribution-specific - paths so that both 32- and 64-bit SDL 2 will work. - Typically this would be enabled by setting a game's Steam launch - options to `STEAM_COMPAT_RUNTIME_SDL2=1 %command%`. + +</dt><dd> + +If set to `1`, set `SDL_DYNAMIC_API` so that the runtime's version +of SDL 2 will be used in preference to any copy that might be bundled +or statically linked in an app or game (as long as it is version ≥ 2.0.2 +and the `dynapi` feature has not been disabled). +The advantage of this variable over setting `SDL_DYNAMIC_API` directly +is that pressure-vessel-wrap sets up appropriate distribution-specific +paths so that both 32- and 64-bit SDL 2 will work. +Typically this would be enabled by setting a game's Steam launch +options to `STEAM_COMPAT_RUNTIME_SDL2=1 %command%`. + +</dd> +<dt> `STEAM_COMPAT_RUNTIME_SDL3` (boolean) -: Same as `STEAM_COMPAT_RUNTIME_SDL2`, but setting `SDL3_DYNAMIC_API` - for SDL 3 apps or games. + +</dt><dd> + +Same as `STEAM_COMPAT_RUNTIME_SDL2`, but setting `SDL3_DYNAMIC_API` +for SDL 3 apps or games. + +</dd> +<dt> `STEAM_COMPAT_SESSION_ID` (integer) -: (Not used yet, but should be.) + +</dt><dd> + +(Not used yet, but should be.) + +</dd> +<dt> `STEAM_COMPAT_SHADER_PATH` (path) -: When used as a Steam compatibility tool, the absolute path to the - variable data directory used for cached shaders, if any. - This is made available read/write in the container. + +</dt><dd> + +When used as a Steam compatibility tool, the absolute path to the +variable data directory used for cached shaders, if any. +This is made available read/write in the container. + +</dd> +<dt> `STEAM_COMPAT_TOOL_PATH` (path) -: Deprecated equivalent of `STEAM_COMPAT_TOOL_PATHS`, except that it is - a single path instead of being colon-delimited. + +</dt><dd> + +Deprecated equivalent of `STEAM_COMPAT_TOOL_PATHS`, except that it is +a single path instead of being colon-delimited. + +</dd> +<dt> `STEAM_COMPAT_TOOL_PATHS` (`:`-separated list of paths) -: Colon-delimited list of paths to Steam compatibility tools in use, - such as Proton and the Steam Linux Runtime. - They are currently made available read/write in the container. + +</dt><dd> + +Colon-delimited list of paths to Steam compatibility tools in use, +such as Proton and the Steam Linux Runtime. +They are currently made available read/write in the container. + +</dd> +<dt> `STEAM_COMPAT_TRACING` (boolean) -: If set to `1`, allow system tracing if it is enabled at system level. - This currently results in `/sys/kernel/tracing` being read/write, - which has no practical effect unless the OS has granted access to that - directory to the user running Steam. - Steam automatically sets this when system tracing is enabled on a - Steam Deck in developer mode. + +</dt><dd> + +If set to `1`, allow system tracing if it is enabled at system level. +This currently results in `/sys/kernel/tracing` being read/write, +which has no practical effect unless the OS has granted access to that +directory to the user running Steam. +Steam automatically sets this when system tracing is enabled on a +Steam Deck in developer mode. + +</dd> +<dt> `STEAM_LINUX_RUNTIME_LOG` (boolean) -: pressure-vessel itself does not use this, - but in the Steam Linux Runtime container runtime framework, - setting it to `1` redirects standard output and standard error to - `$STEAM_LINUX_RUNTIME_LOG_DIR/slr-*.log` or - `$PRESSURE_VESSEL_VARIABLE_DIR/slr-*.log`, - while also enabling info-level logging similar to - `PRESSURE_VESSEL_LOG_INFO=1`. + +</dt><dd> + +pressure-vessel itself does not use this, +but in the Steam Linux Runtime container runtime framework, +setting it to `1` redirects standard output and standard error to +`$STEAM_LINUX_RUNTIME_LOG_DIR/slr-*.log` or +`$PRESSURE_VESSEL_VARIABLE_DIR/slr-*.log`, +while also enabling info-level logging similar to +`PRESSURE_VESSEL_LOG_INFO=1`. + +</dd> +<dt> `STEAM_LINUX_RUNTIME_KEEP_LOGS` (boolean) -: pressure-vessel itself does not use this, - but in the Steam Linux Runtime container runtime framework, - setting it to `1` prevents cleanup of old log files. + +</dt><dd> + +pressure-vessel itself does not use this, +but in the Steam Linux Runtime container runtime framework, +setting it to `1` prevents cleanup of old log files. + +</dd> +<dt> `STEAM_LINUX_RUNTIME_VERBOSE` (boolean) -: pressure-vessel itself does not use this, - but in the Steam Linux Runtime container runtime framework, - setting it to `1` enables debug-level messages similar to - `PRESSURE_VESSEL_VERBOSE=1`. + +</dt><dd> + +pressure-vessel itself does not use this, +but in the Steam Linux Runtime container runtime framework, +setting it to `1` enables debug-level messages similar to +`PRESSURE_VESSEL_VERBOSE=1`. + +</dd> +<dt> `STEAM_RUNTIME` (path) -: **pressure-vessel-wrap** refuses to run if this environment variable + +</dt><dd> + +**pressure-vessel-wrap** refuses to run if this environment variable is set. Use **pressure-vessel-unruntime**(1) instead. +</dd> +<dt> + `SteamAppId` (integer) -: Equivalent to `--steam-app-id="$SteamAppId"`. - Must only be set for the main processes that are running a game, not - for any setup/installation steps that happen first. - `STEAM_COMPAT_APP_ID` is used with a higher priority. + +</dt><dd> + +Equivalent to `--steam-app-id="$SteamAppId"`. +Must only be set for the main processes that are running a game, not +for any setup/installation steps that happen first. +`STEAM_COMPAT_APP_ID` is used with a higher priority. + +</dd> +<dt> `VDPAU_DRIVER_PATH` -: Used to locate VDPAU drivers to be made available in the container - if `--runtime` and `--graphics-provider` are active. + +</dt><dd> + +Used to locate VDPAU drivers to be made available in the container +if `--runtime` and `--graphics-provider` are active. + +</dd> +<dt> `VK_ADD_DRIVER_FILES`, `VK_DRIVER_FILES`, `VK_ICD_FILENAMES` -: Used to locate Vulkan ICDs to be made available in the container - if `--runtime` and `--graphics-provider` are active. + +</dt><dd> + +Used to locate Vulkan ICDs to be made available in the container +if `--runtime` and `--graphics-provider` are active. + +</dd> +<dt> `VK_ADD_LAYER_PATH`, `VK_LAYER_PATH` -: Used to locate Vulkan explicit layers - if `--runtime` and `--graphics-provider` are active. + +</dt><dd> + +Used to locate Vulkan explicit layers +if `--runtime` and `--graphics-provider` are active. + +</dd> +<dt> `WAYLAND_DISPLAY` -: Used to locate the Wayland display to make available in the container. + +</dt><dd> + +Used to locate the Wayland display to make available in the container. + +</dd> +<dt> `XDG_DATA_DIRS` -: Used to locate Vulkan ICDs and layers - if `--runtime` and `--graphics-provider` are active. + +</dt><dd> + +Used to locate Vulkan ICDs and layers +if `--runtime` and `--graphics-provider` are active. + +</dd> +</dl> The following environment variables are set by **pressure-vessel-wrap**(1). +<dl> +<dt> + `__EGL_VENDOR_LIBRARY_DIRS` -: Unset if `--runtime` and `--graphics-provider` are active, - to make sure `__EGL_VENDOR_LIBRARY_FILENAMES` will be used instead. + +</dt><dd> + +Unset if `--runtime` and `--graphics-provider` are active, +to make sure `__EGL_VENDOR_LIBRARY_FILENAMES` will be used instead. + +</dd> +<dt> `__EGL_VENDOR_LIBRARY_FILENAMES` -: Set to a search path for EGL ICDs - if `--runtime` and `--graphics-provider` are active. + +</dt><dd> + +Set to a search path for EGL ICDs +if `--runtime` and `--graphics-provider` are active. + +</dd> +<dt> `DBUS_SESSION_BUS_ADDRESS`, `DBUS_SYSTEM_BUS_ADDRESS` -: Set to paths in the container's private `/run` where the well-known - D-Bus session and system buses are made available. + +</dt><dd> + +Set to paths in the container's private `/run` where the well-known +D-Bus session and system buses are made available. + +</dd> +<dt> `DISPLAY` -: Set to a value corresponding to the socket in the container's - `/tmp/.X11-unix`. + +</dt><dd> + +Set to a value corresponding to the socket in the container's +`/tmp/.X11-unix`. + +</dd> +<dt> `LD_AUDIT` -: Set according to `--ld-audit`. + +</dt><dd> + +Set according to `--ld-audit`. + +</dd> +<dt> `LD_LIBRARY_PATH` -: Set to a search path for shared libraries if `--runtime` is active. + +</dt><dd> + +Set to a search path for shared libraries if `--runtime` is active. + +</dd> +<dt> `LD_PRELOAD` -: Set according to `--ld-preload`, `--keep-game-overlay`, - `--remove-game-overlay`. + +</dt><dd> + +Set according to `--ld-preload`, `--keep-game-overlay`, +`--remove-game-overlay`. + +</dd> +<dt> `LIBGL_DRIVERS_PATH` -: Set to a search path for Mesa DRI drivers - if `--runtime` and `--graphics-provider` are active. + +</dt><dd> + +Set to a search path for Mesa DRI drivers +if `--runtime` and `--graphics-provider` are active. + +</dd> +<dt> `LIBVA_DRIVERS_PATH` -: Set to a search path for VA-API drivers - if `--runtime` and `--graphics-provider` are active. + +</dt><dd> + +Set to a search path for VA-API drivers +if `--runtime` and `--graphics-provider` are active. + +</dd> +<dt> `PATH` -: Reset to a reasonable value if `--runtime` is active. + +</dt><dd> + +Reset to a reasonable value if `--runtime` is active. + +</dd> +<dt> `PULSE_CLIENTCONFIG` -: Set to the address of a PulseAudio client configuration file. + +</dt><dd> + +Set to the address of a PulseAudio client configuration file. + +</dd> +<dt> `PULSE_SERVER` -: Set to the address of a PulseAudio server socket. + +</dt><dd> + +Set to the address of a PulseAudio server socket. + +</dd> +<dt> `PWD` -: Set to the current working directory inside the container. + +</dt><dd> + +Set to the current working directory inside the container. + +</dd> +<dt> `STEAM_RUNTIME` -: Set to `/` if using the Steam Runtime 1 'scout' runtime. + +</dt><dd> + +Set to `/` if using the Steam Runtime 1 'scout' runtime. + +</dd> +<dt> `TERMINFO_DIRS` -: Set to the required search path for **terminfo**(5) files if - the `--runtime` appears to be Debian-based. + +</dt><dd> + +Set to the required search path for **terminfo**(5) files if +the `--runtime` appears to be Debian-based. + +</dd> +<dt> `VDPAU_DRIVER_PATH` -: Set to a search path for VDPAU drivers - if `--runtime` and `--graphics-provider` are active. + +</dt><dd> + +Set to a search path for VDPAU drivers +if `--runtime` and `--graphics-provider` are active. + +</dd> +<dt> `VK_DRIVER_FILES`, `VK_ICD_FILENAMES` -: Set to a search path for Vulkan ICDs - if `--runtime` and `--graphics-provider` are active. + +</dt><dd> + +Set to a search path for Vulkan ICDs +if `--runtime` and `--graphics-provider` are active. + +</dd> +<dt> `VK_ADD_DRIVER_FILES`, `VK_ADD_LAYER_PATH`, `VK_LAYER_PATH` -: Unset if `--runtime` and `--graphics-provider` are active. + +</dt><dd> + +Unset if `--runtime` and `--graphics-provider` are active. + +</dd> +<dt> `XAUTHORITY` -: Set to a value corresponding to a file in the container's - private `/run`. + +</dt><dd> + +Set to a value corresponding to a file in the container's +private `/run`. + +</dd> +<dt> `XDG_CACHE_HOME` -: Set to `$HOME/.cache` (in the private home directory) - if `--unshare-home` is active. + +</dt><dd> + +Set to `$HOME/.cache` (in the private home directory) +if `--unshare-home` is active. + +</dd> +<dt> `XDG_CONFIG_HOME` -: Set to `$HOME/.config` (in the private home directory) - if `--unshare-home` is active. + +</dt><dd> + +Set to `$HOME/.config` (in the private home directory) +if `--unshare-home` is active. + +</dd> +<dt> `XDG_DATA_HOME` -: Set to `$HOME/.local/share` (in the private home directory) - if `--unshare-home` is active. + +</dt><dd> + +Set to `$HOME/.local/share` (in the private home directory) +if `--unshare-home` is active. + +</dd> +<dt> `XDG_DATA_DIRS` -: Set to include a search path for Vulkan layers - if `--runtime` and `--graphics-provider` are active. + +</dt><dd> + +Set to include a search path for Vulkan layers +if `--runtime` and `--graphics-provider` are active. + +</dd> +<dt> + +</dd> +<dt> `XDG_RUNTIME_DIR` -: Set to a new directory in the container's private `/run` - if `--runtime` is active. + +</dt><dd> + +Set to a new directory in the container's private `/run` +if `--runtime` is active. + +</dd> +</dl> # OUTPUT