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
stdoutandstderrseparately - 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")