Process Functions
This module provides functions for executing system commands from XQuery.
All functions and errors in this module are assigned to the http://basex.org/modules/proc namespace, which is statically bound to the proc prefix.
Updated: proc:system: environment option added.
| Signature | proc:system(
$command as xs:string,
$arguments as xs:string* := (),
$options as map(*)? := {}
) as xs:string |
|---|
| Summary | Executes a $command with the specified $arguments in a separate process and returns the result as a string. The following $options are available:
| option | default | description |
|---|
encoding | – |
Convert result to the specified encoding. If no encoding is supplied, the system’s default encoding is used.
| timeout | – |
Abort process execution after the specified number of seconds.
| dir | – |
Process command in the specified directory.
| input | – |
Standard string input (stdin) to be passed on to the command.
| environment | {} |
Environment variables. If empty, the BaseX environment is inherited.
|
|
|---|
| Errors | code.... | The result of a command call with an exit code different to 0. | 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' })
Analyses 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). |
|---|
| Signature | proc:execute(
$command as xs:string,
$arguments as xs:string* := (),
$options as map(*)? := {}
) as element(result) |
|---|
| Summary | Executes a $command with the specified $arguments in a separate process and returns the result as an element:
- The same
$options are allowed as for proc:system. - Instead of the
proc:error error, the error message and process code will be assigned to the returned elements. - Instead of the
proc:code.... error, the error message will be assigned to the returned element (no process code will be returned).
A result element is returned with an output child element, a code child element with the process exit value, and an optional error child element.
|
|---|
| Errors | encoding | The specified encoding does not exist or is not supported. | timeout | The specified timeout was exceeded. |
|
|---|
| Examples | proc:execute('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 element(result) |
|---|
| 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 with the encoding being ignored. |
|---|
| Errors | encoding | The specified encoding does not exist or is not supported. |
|
|---|
| 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) |
|---|
| Summary | Returns a map with all system properties. |
|---|
| Signature | proc:property-names() as xs:string* |
|---|
| 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? |
|---|
| 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 different to 0. |
code9999 | A command could not be executed. |
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 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
