p:os-exec (3.0)

Runs an external command.

Summary
Description
Examples
- Basic usage
Additional details
Errors raised
Reference information

Summary

<p:declare-step type="p:os-exec">
  <input port="source" primary="true" content-types="any" sequence="true"/>
  <output port="result" primary="true" content-types="any" sequence="true"/>
  <output port="error" primary="false" content-types="any" sequence="true"/>
  <output port="exit-status" primary="false" content-types="application/xml" sequence="false"/>
  <option name="command" as="xs:string" required="true"/>
  <option name="args" as="xs:string*" required="false" select="()"/>
  <option name="cwd" as="xs:string?" required="false" select="()"/>
  <option name="error-content-type" as="xs:string" required="false" select="'text/plain'"/>
  <option name="failure-threshold" as="xs:integer?" required="false" select="()"/>
  <option name="path-separator" as="xs:string?" required="false" select="()"/>
  <option name="result-content-type" as="xs:string" required="false" select="'text/plain'"/>
  <option name="serialization" as="map(xs:QName,item()*)?" required="false" select="()"/>
</p:declare-step>

The p:os-exec step runs the external command as specified in the command and args options. It passes the input that arrives on its source port as standard input to the command. The standard output and standard error of the command are returned on the result and error ports.

Ports:

Port	Type	Primary?	Content types	Seq?	Description
`source`	`input`	`true`	`any`	`true`	The document that appears on the standard input of the external command. If the `source` port is empty, the command receives nothing on standard input. This document is serialized (as if written to disk) first. For this, the value of the `serialization` document-property and that of the `serialization` option are used. See the `serialization` option for more information. The port accepts zero or one document. For multiple documents, error `XC0032` is raised. If you want the source port to be empty, you must specify this: <p:with-input port="source"> <p:empty/> </p:with-input>
`result`	`output`	`true`	`any`	`true`	The result of the external command: what was written by the command on the standard output. The standard output of the command is processed as if it was read from disk by `p:load`. The value of the `result-content-type` option of `p:os-exec` is taken as the value for the `content-type` option of `p:load`. If there is no content on the standard output, this port will be empty.
`error`	`output`	`false`	`any`	`true`	The error result of the external command: what was written by the command on the standard error. The standard error of the command is processed as if it was read from disk by `p:load`. The value of the `error-content-type` option of `p:os-exec` is taken as the value for the `content-type` option of `p:load`. If there is no content on the standard error, this port will be empty.
`exit-status`	`output`	`false`	`application/xml`	`false`	A `<c:result>` element containing the system exit status, as an integer (the `c` prefix here is bound to the `http://www.w3.org/ns/xproc-step` namespace).

Options:

Name	Type	Req?	Default	Description
`command`	`xs:string`	`true`		The external command to execute (without arguments).
`args`	`xs:string*`	`false`	`()`	The arguments for the external command (as a sequence of strings).
`cwd`	`xs:string?`	`false`	`()`	The current working directory for the execution of the command. If this option is left unspecified, the current working directory will be implementation-defined and therefore depends on the XProc processor used. The exact format for this option is unspecified, and is operating system dependent (as, for instance, `C:/x/y/z` on Windows).
`error-content-type`	`xs:string`	`false`	`text/plain`	The content type of the command’s error result (its standard error). See the description of the `error` port.
`failure-threshold`	`xs:integer?`	`false`	`()`	If a value for this option is supplied and the command exit status is greater than this value, error `XC0064` is raised.
`path-separator`	`xs:string?`	`false`	`()`	If specified, every occurrence of this character that occurs in the `command`, `args`, or `cwd` options will be replaced by the platform-specific path separator character. The value for this option must be exactly one character long. if not, error `XC0063` is raised.
`result-content-type`	`xs:string`	`false`	`text/plain`	The content type of the command’s result (its standard output). See the description of the `result` port.
`serialization`	`map(xs:QName,item()*)?`	`false`	`()`	This option can supply a map with serialization properties for serializing the document on the `source` port, before it is passed as the standard input of the command. If the source document has a `serialization` document-property, the two sets of serialization properties are merged (properties in the document-property have precedence). Example: `serialization="map{'method': 'text'}"`

Description

The p:os-exec step can be used to run an external command. For instance, a Python script or post-process some result with something not available in XProc.

The command itself is specified using the command and args options. Every string in the args option is a separate argument (also when it contains spaces). What appears on the result> port is passed as the command’s standard input.

The command’s output and error information is returned on the result and error ports. You can use the result-content-type and error-content-type options to tailor how this comes out.

Examples

Basic usage

This example runs the (Windows) dir command (that shows a directory overview) on the data/ subdirectory of where the pipeline is stored. It does so by starting the Windows command processor (called cmd) with the arguments /C dir data. This is the same as typing dir data on the Windows command line.

A problem we have here is that we need to set the current working directory (in the cwd) to the location of the pipeline. The example computes this, based on the static-base-uri() of the pipeline, using regular expression magic. The cwd option of p:os-exec does not accept a URI, so we have to strip the file:/ in front also. The result is stored in the $cwd variable.

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:output port="result"/>

  <p:variable name="cwd" select="static-base-uri() =&gt; replace('^file:/+', '') =&gt; replace('[^/\\]+$', '')"/>

  <p:os-exec command="cmd" cwd="{$cwd}">
    <p:with-option name="args" select="('/C', 'dir', 'data')"/>
    <p:with-input port="source">
      <p:empty/>
    </p:with-input>
  </p:os-exec>
  
</p:declare-step>

Result document (text):

Volume in drive C is OS
 Volume Serial Number is 9EA2-E853

 Directory of C:\…\data

08/01/2025  10:44    <DIR>          .
08/01/2025  10:44    <DIR>          ..
08/01/2025  10:44                44 x1.xml
08/01/2025  10:44                44 x2.xml
               2 File(s)             88 bytes
               2 Dir(s)  518.830.137.344 bytes free

Additional details

The documents appearing on the output ports only have a content-type property. They have no other document-properties (also no base-uri).

Errors raised

Error code	Description
`XC0032`	It is a dynamic error if more than one document appears on the `source` port of the `<p:os-exec>` step.
`XC0033`	It is a dynamic error if the command cannot be run.
`XC0034`	It is a dynamic error if the current working directory cannot be changed to the value of the `cwd` option.
`XC0063`	It is a dynamic error if the `path-separator` option is specified and is not exactly one character long.
`XC0064`	It is a dynamic error if the exit code from the command is greater than the specified `failure-threshold` value.

Reference information

This description of the p:os-exec step is for XProc version: 3.0. This is a non-required step (an XProc 3.0 processor does not have to support this).

The formal specification for the p:os-exec step can be found here.

The p:os-exec step is part of categories:

The p:os-exec step is also present in version: 3.1.