Skip to content

system

Execute a system command

system x     system[x]

Where x is a string representing a KDB-X system command or operating system shell command, and any parameters to it, executes the command and returns its result.

KDB-X system commands

Refer to the system commands reference for a full list of available commands.

The argument to system does not include a leading \.

If you enter a system command with \, q passes any trailing comment to the command as part of its argument, so put comments on a separate line.

q)s:([]a:1 2);p:([]b:3 4);sp:([]c:5 6)
q)/ tables in namespace
q)\a
`p`s`sp
q)/ \ must be the first character
q)count \a
'\
  [0]  count \a
             ^
q)system "a"             / same command called with system
`p`s`sp
q)count system "a"       / this returns a result
3

Working directory changes on Windows

If the working directory changes unexpectedly on Windows, refer to why the current directory can change on The Old New Thing.

Operating system shell commands

As with \, if the argument is not a q command, system runs it in the shell and returns the output of the command as a list of strings:

q)system "pwd"
"/home/guest/q"

If the shell command exits with a nonzero status, system signals an os error. To get the exit status instead, use the OS module.

Binary output

system expects the result to be text and captures it as a list of character vectors. During capture, it removes line feeds and their associated carriage returns.

This transformation makes it impractical to capture binary data from the result of the system call. In such cases, redirect the output to a file or FIFO and read the file with read1, or use the OS module with the `bin option.

Direct output to a file

To capture the output, KDB-X redirects it to a temporary file. If you redirect the output to a file yourself, append a semicolon to the command to avoid an unnecessary redirection.

q)system"cat x"

is essentially the same as the shell command:

cat x > tmpout

because KDB-X captures the output. If you redirect the output yourself:

q)system"cat x > y"

the shell receives:

cat x > y > tmpout

which redirects the output twice. If you add the semicolon:

q)system"cat x > y;"

the shell treats it as two statements:

cat x > y; > tmpout

The same mechanism means that, for several commands separated by semicolons, only the output of the last command is captured.

Capture stderr output

You cannot capture stderr from system directly. As a workaround, redirect it to a file and read the file:

q)/ Force capture to a file, and cat the file
q)system"ls egg > file 2>&1;cat file"
"ls: egg: No such file or directory"

q)/ Try and fail to capture the text
q)@[system;"ls egg";{0N!"error - ",x;}]
ls: egg: No such file or directory
"error - os"

To capture stderr without a workaround, use the OS module.

Run a subprocess with the OS module

The OS module function os.proc.start runs a subprocess and returns a dictionary instead of signalling an error. Use it when you need to:

  • capture stdout and stderr separately
  • read the exit status of a command that fails
  • capture binary output as bytes
  • run a subprocess asynchronously, or pass data to its standard input
q)os:use`kx.os
q)os.proc.start["ls egg";([stdout:`text;stderr:`text])]
status| 1i
stdout| ()
stderr| ,"ls: egg: No such file or directory"
q)os.proc.start[("printf";"a\\000b");([stdout:`bin])]
status| 0i
stdout| 0x610062

Unlike system, os.proc.start doesn't run the command in a shell, so shell syntax such as ;, |, and > isn't interpreted. To use shell features, run the shell explicitly:

q)os.proc.start[("sh";"-c";"echo hi; echo there");([stdout:`text])]
status| 0i
stdout| ("hi";"there")

OS module, System commands