Newer
Older
---
title: pressure-vessel-adverb
section: 1
...
<!-- This document:
Copyright © 2020-2021 Collabora Ltd.
SPDX-License-Identifier: MIT
-->
# NAME
pressure-vessel-adverb - wrap processes in various ways
# SYNOPSIS
**pressure-vessel-adverb**
[**--[no-]exit-with-parent**]
[**--fd** *FD*...]
[**--[no-]generate-locales**]
[**--ld-audit** *MODULE*[**:arch=***TUPLE*]...]
[**--ld-preload** *MODULE*[**:**...]...]
[[**--add-ld.so-path** *PATH*...]
**--regenerate-ld.so-cache** *PATH*]
[**--set-ld-library-path** *VALUE*]
[**--shell** **none**|**after**|**fail**|**instead**]
[**--terminal** **none**|**auto**|**tty**|**xterm**]
[**--terminate-timeout** *SECONDS* [**--terminate-idle-timeout** *SECONDS*]]
[[**--[no-]create**]
[**--[no-]wait**]
[**--[no-]write**]
**--lock-file** *FILENAME*...]
[**--verbose**]
[**--**]
*COMMAND* [*ARGUMENTS...*]
# DESCRIPTION
**pressure-vessel-adverb** runs *COMMAND* as a child process, with
modifications to its execution environment as determined by the options.
By default, it just runs *COMMAND* as a child process and reports its
exit status.
# OPTIONS
**--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.
**--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.
**--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.
**--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**.
**--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.
**--ld-audit** *MODULE*[**:arch=***TUPLE*]
: Add *MODULE* to **LD_AUDIT** before executing *COMMAND*.
The optional *TUPLE* is the same as for **--ld-preload**, below.
**--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.
**--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.
**--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**).
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
**--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`.
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.
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`.
**--set-ld-library-path** *VALUE*
: Set the environment variable LD_LIBRARY_PATH to *VALUE* after
processing **--regenerate-ld.so-cache** (if used), but before
executing *COMMAND*.
**--shell=after**
: Run an interactive shell after *COMMAND* exits.
In that shell, running **"$@"** will re-run *COMMAND*.
**--shell=fail**
: The same as **--shell=after**, but do not run the shell if *COMMAND*
exits with status 0.
**--shell=instead**
: The same as **--shell=after**, but do not run *COMMAND* at all.
**--shell=none**
: Don't run an interactive shell. This is the default.
**--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.
**--terminal=auto**
: Equivalent to **--terminal=xterm** if a **--shell** option other
than **none** is used, or **--terminal=none** otherwise.
This is the default.
**--terminal=none**
: Disable features that would ordinarily use a terminal.
**--terminal=tty**
: Use the current execution environment's controlling tty for
the **--shell** options.
**--terminal=xterm**
: Start an **xterm**(1), and run *COMMAND* and/or an interactive
shell in that environment.
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
**--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.
**--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.
**--verbose**
: Be more verbose.
**--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.
**--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.
# ENVIRONMENT
`PRESSURE_VESSEL_LOG_INFO` (boolean)
: If set to `1`, increase the log verbosity up to the info level.
If set to `0`, no effect.
`PRESSURE_VESSEL_LOG_WITH_TIMESTAMP` (boolean)
: If set to `1`, prepend the log entries with a timestamp.
If set to `0`, no effect.
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
# OUTPUT
The standard output from *COMMAND* is printed on standard output.
The standard error from *COMMAND* is printed on standard error.
Diagnostic messages from **pressure-vessel-adverb** may also be printed
on standard error.
# SIGNALS
If **pressure-vessel-adverb** receives signals **SIGHUP**, **SIGINT**,
**SIGQUIT**, **SIGTERM**, **SIGUSR1** or **SIGUSR2**, it immediately
sends the same signal to *COMMAND*, hopefully causing *COMMAND* to
exit gracefully.
# EXIT STATUS
Nonzero (failure) exit statuses are subject to change, and might be
changed to be more like **env**(1) in future.
0
: The *COMMAND* exited successfully with status 0
1
: An error occurred while setting up the execution environment or
starting the *COMMAND*
64 (**EX_USAGE**)
: Invalid arguments were given
69 (**EX_UNAVAILABLE**)
: An error occurred while setting up the execution environment
70 (**EX_SOFTWARE**)
: The *COMMAND* terminated in an unknown way
75 (**EX_TEMPFAIL**)
: A **--lock-file** could not be acquired, and **--wait** was not given
127
: The *COMMAND* could not be started
Any value 1-255
: The *COMMAND* exited unsuccessfully with the status indicated
128 + *n*
: The *COMMAND* was killed by signal *n*
(this is the same encoding used by **bash**(1), **bwrap**(1) and
**env**(1))
# EXAMPLE
When running a game in a container as a single command,
**pressure-vessel-wrap** uses a pattern similar to:
bwrap \
... \
/path/to/pressure-vessel-adverb \
--exit-with-parent \
--generate-locales \
--lock-file=/path/to/runtime/.ref \
--subreaper \
-- \
/path/to/game ...
to preserve Steam's traditional behaviour for native Linux games (where
all background processes must exit before the game is considered to have
exited).
When running **pressure-vessel-launcher** in a container, the adverb looks
more like this:
bwrap \
... \
/path/to/pressure-vessel-adverb \
--exit-with-parent \
--generate-locales \
--lock-file=/path/to/runtime/.ref \
--subreaper \
--terminate-timeout=10 \
-- \
/path/to/pressure-vessel-launcher ...
so that when the **pressure-vessel-launcher** is terminated by
**pressure-vessel-launch --terminate**, or when the **bwrap** process
receives a fatal signal, the **pressure-vessel-adverb** process will
gracefully terminate any remaining child/descendant processes before
exiting itself.
<!-- vim:set sw=4 sts=4 et: -->