The p:os-exec step runs an external command passing the
input that arrives on its source port as standard input,
reading result from standard output, and error
from standard error.
Summary
| Input port | Primary | Sequence | Content types |
|---|---|---|---|
| source | ✔ | ✔ | any |
Errors
| Error code | Description |
|---|---|
| err:XC0032 | It is a dynamic error if more than one document appears on the source port of the p:os-exec step. |
| err:XC0033 | It is a dynamic error if the command cannot be run. |
| err:XC0034 | It is a dynamic error if the current working directory cannot be changed to the value of the cwd option. |
| err:XC0063 | It is a dynamic error if the path-separator option is specified and is not exactly one character long. |
| err:XC0064 | It is a dynamic error if the exit code from the command is greater than the specified failure-threshold value. |
Implementation details
| Implementation | Description |
|---|---|
| Defined | If cwd is not specified, the current working directory is implementation-defined. |
| Dependent | The specific exit status values returned by a process invoked with p:os-exec are implementation-dependent. |
Declaration
<p:declare-step type="p:os-exec">
<p:input port="source" sequence="true" content-types="any"/>
<p:output port="result" primary="true" sequence="true" content-types="any"/>
<p:output port="error" sequence="true" content-types="any"/>
<p:output port="exit-status" content-types="application/xml"/>
<p:option name="command" required="true" as="xs:string"/>
<p:option name="args" select="()" as="xs:string*"/>
<p:option name="cwd" as="xs:string?"/>
<p:option name="result-content-type" select="'text/plain'" as="xs:string"/>
<p:option name="error-content-type" select="'text/plain'" as="xs:string"/>
<p:option name="path-separator" as="xs:string?"/>
<p:option name="failure-threshold" as="xs:integer?"/>
<p:option name="serialization" as="map(xs:QName,item()*)?"/> </p:declare-step>
The p:os-exec step executes the command passed on
command with the arguments passed on
args. The processor does not interpolate the values
of the command or args (for example,
expanding references to environment variables).
It is a dynamic
error (err:XC0033) if the command cannot be run.
If the cwd option is specified, it identifies the directory
that will be the current working directory when execution begins.
To resolve variations in the syntax of directory specifications (“/tmp”
vs. “C:\tmp” vs “file:///c:/tmp”, for example), the value will be
normalized with the p:urify function.
It is a dynamic
error (err:XC0034) if the current working directory cannot be changed
to the value of the cwd option.
If cwd is not
specified, the current working directory is
implementation-defined.
If the path-separator option is specified,
every occurrence of the character identified as the
path-separator character that occurs in the
command, args, or
cwd will be replaced by the platform-specific path
separator character. It is a dynamic
error (err:XC0063) if the path-separator option is
specified and is not exactly one character long.
The source port is declared to accept a sequence so
that it can be empty. If no document appears on the
source port, then the command receives nothing on
standard input. If a document does arrive on the source
port, it will be passed to the command as its standard input. It is a dynamic error (err:XC0032) if more than
one document appears on the source port of the
p:os-exec step.
The serialization option is used to control the serialization
of the document before passing it to the standard input. If a document has a
“serialization” document property, the effective value of
the serialization options is the union of the two maps, where the entries in
the “serialization” document property take precedence.
Serialization is described in [XProc 3.1].
If there is content on standard output, it is read and processed as described
in p:load with result-content-type taken as
value for p:load's content-type option. The
created document is returned on result. Otherwise result
will be empty.
If there is content on standard error, it is read and processed as described
in p:load with error-content-type taken as
value for p:load's content-type option. The
created document is returned on error. Otherwise error
will be empty.
The exit-status port always returns a single
c:result element which contains the system exit status that
the process returned. The specific exit status values returned by
a process invoked with p:os-exec are
implementation-dependent.
If a failure-threshold value is supplied, and the
exit status is greater than that threshold, then the p:os-exec
step must fail.
It is a dynamic
error (err:XC0064) if the exit code from the command is greater than
the specified failure-threshold value.
This failure, like any step failure,
can be captured with a p:try.
Document properties
No document properties are preserved.