Process Functions
This module provides functions for executing system commands from XQuery.
All functions and errors are in the http://basex.org/modules/proc namespace, to which the proc prefix is statically bound.
Updated: New options binary, normalize-newlines and fallback; binary input; invalid characters are rejected.
| Signature | proc:system( $command as xs:string, $arguments as xs:string* := (), $options as map(*)? := {}) as (xs:string|xs:base64Binary)admin |
|---|
| Summary | Executes a $command with the specified $arguments in a separate process and returns the standard output as a string. The following $options are available:
| option | default | description |
|---|
encoding | – |
Encoding of the input and the output. If no encoding is supplied, the output encoding is inferred from a byte order mark, and UTF-8 is used otherwise (see bin:infer-encoding).
| timeout | – |
Abort process execution after the specified number of seconds.
| dir | – |
Process command in the specified directory.
| input | – |
Standard input (stdin) to be passed on to the command. A string is encoded with the specified encoding, binary data is passed on unchanged. If no input is supplied, the standard input is closed.
| environment | {} |
Environment variables. If empty, the BaseX environment is inherited. Otherwise, the supplied variables replace the inherited environment; include PATH if the command needs it.
| binary | false |
Return the output as xs:base64Binary item.
| normalize-newlines | true |
Convert each CR character, optionally followed by an LF character, to a single LF character. As for file:read-text, line endings are normalized by default.
| fallback | false |
By default, invalid XML characters and invalid input are rejected. If enabled, they are replaced with the Unicode replacement character FFFD (�). The error output is always decoded with replacement characters.
|
|
|---|
| Errors | code.... | The result of a command call with an exit code other than 0. The four dots are replaced with the exit code, e.g. proc:code0002. | encoding | The specified encoding does not exist or is not supported. | error | An error occurred while executing a command. | timeout | The specified timeout was exceeded. |
|
|---|
| Examples | proc:system('date')
Returns the current date on a Linux system.
proc:system('wc', options := { 'input': 'A B' || char('\n') || 'C' })
Analyzes the given input and counts the number of lines, words and characters (provided that wc is available on the system).
try {
proc:system('xyz')
} catch proc:error {
'Command not found: ' || $err:description
}
The example returns “Command not found” (unless xyz is a valid command on the system). |
|---|
Updated: New options binary, normalize-newlines and fallback; binary input; invalid characters are rejected.
| Signature | proc:execute( $command as xs:string, $arguments as xs:string* := (), $options as map(*)? := {}) as element(result)admin |
|---|
| Summary | Executes a $command with the specified $arguments in a separate process and returns a result element with optional output, error and code child elements:
- The same
$options are allowed as for proc:system. If binary is enabled, the output is returned as Base64 string. - Instead of the
proc:error error, the error message is returned as error, and no code element is returned. - Instead of the
proc:code.... error, the error output and the exit code are returned.
|
|---|
| Errors | encoding | The specified encoding does not exist or is not supported. | timeout | The specified timeout was exceeded. |
|
|---|
| Examples | proc:execute('cmd', ('/c', 'dir', '\'))
Returns the files of the root directory of a Windows system.
proc:execute('ls', ('-l', '-a'))
Executes the ls -la command on Unix systems. |
|---|
| Signature | proc:fork( $command as xs:string, $arguments as xs:string* := (), $options as map(*)? := {}) as empty-sequence()admin |
|---|
| Summary | Executes a $command with the specified $arguments in a separate process and ignores the result. The same $options are allowed as for proc:system; the options for decoding the output are ignored. |
|---|
| Examples | proc:fork('sleep', '5')
Sleep for 5 seconds (no one should notice). |
|---|
The following functions return Java system properties as well as context parameters that are defined in the web.xml file (see Web Applications). For environment variables of the operating system, use fn:available-environment-variables.
| Signature | proc:property-map() as map(xs:string, xs:string)create |
|---|
| Summary | Returns a map with all system properties. |
|---|
| Signature | proc:property-names() as xs:string*create |
|---|
| Summary | Returns the names of all system properties. |
|---|
| Examples | map:merge(proc:property-names() ! map:entry(., proc:property(.)))
Returns a map with all system properties (equivalent to proc:property-map). |
|---|
| Signature | proc:property( $name as xs:string) as xs:string?create |
|---|
| Summary | Returns the value of a system property, specified by $name. |
|---|
| Examples | proc:property('java.class.path')
Returns the full user class path.
proc:property('java.runtime.version')
Returns the version of the Java runtime engine. |
|---|
| Code | Description |
|---|
code.... | The result of a command call with an exit code other than 0. The four dots are replaced with the exit code, e.g. proc:code0002. |
encoding | The specified encoding does not exist or is not supported. |
error | An error occurred while executing a command. |
timeout | The specified timeout was exceeded. |
Version 13.0- Updated:
proc:system: New options binary, normalize-newlines and fallback; binary input; invalid characters are rejected. - Updated:
proc:execute: New options binary, normalize-newlines and fallback; binary input; invalid characters are rejected.
Version 12.0Version 11.0Version 9.0- Added:
proc:fork - Updated: error codes; errors now use the module namespace
- Updated: new
input option; revised error handling
Version 8.6Version 8.3Version 7.3
⚡Generated with XQuery
