# System commands¶

System commands control the q environment. They have the form:

\cmd [p]


for some command cmd, and optional parameter list p.

.Q.opt (command parameters), .Q.x (non-command parameters)

Commands with optional parameters that set values, will show the current values if the parameters are elided.

Some system commands have equivalent command-line parameters.

system

The system keyword executes a string representation of a system command – and allows its result to be captured.

\   abort                       \s       number of slaves
\a  tables                      \S       random seed
\b  views                       \t       timer
\B  pending views               \T       timeout
\c  console size                \ts      time and space
\C  HTTP size                   \v       variables
\d  directory                   \w       workspace
\e  error trap clients          \W       week offset
\f  functions                   \x       expunge
\g  garbage collection mode     \z       date parsing
\l  load file or directory      \1 & \2  redirect
\o  offset from UTC             \_       hide q code
\p  listening port              \        terminate
\P  precision                   \        toggle q/k
\r  replication master          \\       quit
\r  rename


## \ (abort)¶

At the debugger’s q)) prompt clears one level from the execution stack and (eventually) returns to the interactive session.

q)f:{g[]}
q)g:{'xyz}
q)f[]
{g[]}
'xyz
@
{'xyz}
::
q))\
q)


At the session’s q) prompt

toggles in an out of the k interpreter. (Don’t go there.)

## \a (tables)¶

Syntax: \a [namespace]

Lists tables in namespace; default: current namespace.

q)\a
symbol$() q)aa:bb:23 q)\a symbol$()
q)tt:([]dd:12 34)
q)\a
,tt
q).nn.vv:([]uu:12 45)
q)\a
,tt
q)\a .n
'.n
q)\a .nn
,vv
q)\d .nn
q.nn)\a
,vv
q.nn)vv
uu
--
12
45
q.nn)


## \b (views)¶

Syntax: \b [namespace]

Lists dependencies (views) in namespace. Defaults to current namespace.

q)a::x+y
q)b::x+1
q)\b
s#ab


## \B (pending views)¶

Syntax: \B [namespace]

Lists pending dependencies (views) in namespace, i.e. dependencies not yet referenced, or not referenced after their referents have changed. Defaults to current namespace.

q)a::x+1          / a depends on x
q)\B              / the dependency is pending
,a
q)x:10
q)\B              / still pending after x is defined
,a
q)a               / use a
11
q)\B              / no longer pending
symbol$()  ## \c (console size)¶ Syntax: \c Syntax: \c [h,w] Sets console height and width. This is the same as the -c command line parameter. These settings determine when q elides output with .. Note You usually don’t need to set this. If the environment variables LINES and COLUMNS are found they’ll be taken as the default value. See Bash documentation for shopt parameter checkwinsize to make sure they’re reset as needed. q)\c 45 160 q)\c 5 5 q)\c 10 10 q)til each 20+til 10 0 1 2 3.. 0 1 2 3.. 0 1 2 3.. 0 1 2 3.. 0 1 2 3.. 0 1 2 3.. 0 1 2 3.. ..  ## \C (HTTP size)¶ Syntax: \C [h,w] Sets the HTTP height and width. This is the same as command-line option -C. ## \cd (change directory)¶ Syntax: \cd [name] Changes the current directory. ~/q$ q
KDB+ 2.6 2010.05.10 Copyright (C) 1993-2010 Kx Systems
..
q)\cd
"/home/guest/q"
q)\cd /home/guest/dev
q)\cd
"/home/guest/dev"


## \d (directory)¶

Syntax: \d [namespace]

Sets the current namespace (also known as directory or context). The namespace can be empty, and a new namespace is created when an object is defined in it. The prompt indicates the current namespace.

q)\d                  / default namespace
.
q)\d .o               / change to .o
q.o)\f
ColsColumnsFGFkeyGkeyKeySpecial..
q)key                / lists namespaces other than .z
qQoh
q)\d .s               / change to non-existent namespace
q.s)key              / not yet created
qQoh
q.s)a:1               / create object, also creates namespace
q.s)key
qQohs


## \e (error trap clients)¶

Syntax: \e [0|1]

This enables error trapping for client requests. The default is 0 (off).

When a client request has an error, by default the server clears the stack. This is appropriate for production use as it enables the server to continue processing other client requests.

For development, you can set \e 1 to enable debugging on the server. In this case, the server suspends on an error, and does not process other requests until the stack is cleared.

## \f (functions)¶

Syntax: \f [namespace]

Lists functions in the given namespace, default current namespace.

q)f:g:h:{x+2*y}
q)\f
fgh
q)\f .h
cdcodedataebecedesestrframhahbhchehnhphrhthtahtachtchtmlhttphuhughyjxnbrpretdtextuhxdxmpxsxt
q){x where x like"ht??"}system"f .h"
htachtmlhttp


## \g (garbage collection mode)¶

Syntax: \g [mode]

Since V2.7 2011.02.04. Switch garbage collection between immediate (1) and deferred (0) modes.

## \l (load file or directory)¶

Syntax: \l name

The parameter can be a script filename or a directory. A script is loaded, and a directory database is opened. When q opens a directory, it changes its current directory to it. This allows reloading the current database using \l .. If the directory is specified as ., any scripts in that directory will be ignored; this is to allow (re)loading of data only.

If a file or directory under the path being loaded has a dollar-sign suffix then it is also ignored. e.g. db/tickdata/myfile$ and db/tickdata/mydir$ would be ignored on \l db/tickdata or on \l . if db/tickdata is the current directory.

q)\l sp.q            / load sp.q script
...
q)\a                 / tables defined in sp.q
pssp
q)\l db/tickdata     / load the data found in db/tickdata
q)\a                 / with tables quote and trade
pquotessptrade


.Q.l (load)

## \o (offset from UTC)¶

Syntax: \o [n]

Sets the local time offset, as hours from UTC, or as minutes if abs[n]>23. Initially, the value is 0N, meaning that the machine’s offset is used.

q)\o
0N
q).z.p                        / UTC
2010.05.31D23:45:52.086467000
q).z.P                        / local time is UTC + 8
2010.06.01D07:45:53.830469000
q)\o -5                       / set local time as UTC - 5
q).z.P
2010.05.31D18:45:58.470468000
q)\o 390                      / set local time as UTC + 6:30
q).z.P
2010.06.01D06:16:06.603981000


This corresponds to the -o command line parameter.

## \p (listening port)¶

Syntax: \p [i]

Sets the listening port number. The default is 0 (no listening port). The port must be available and the process must have permission for the port.

A negative parameter sets a multi-threaded port and if used it must be the initial and only mode of operation, i.e. do not dynamically switch between positive port and negative port.

A parameter of 0W means pick a random available port within the range 32768–60999.

q)\p 5010     / set port 5010
q)\p
5010
q)\p 0W       / pick a random available port within the range 32768 - 60999
q)\p
45512
q)\p 0        / turn off listening port


This corresponds to the -p command line parameter.

## \P (precision)¶

Syntax: \P [n]

Sets display precision for floating point numbers, i.e. the number of digits shown.

## \r (replication master)¶

Syntax: \r

This should not be executed manually otherwise it can disrupt replication. It is executed automatically by the replicating process on the master process, and returns the log file name and log file count.

## \r (rename)¶

Syntax: \r src dst

This renames file src to dst. It is equivalent to the Unix mv command, or the windows move command (except that it will not rename to a different disk drive).

## \s (number of slaves)¶

Syntax: \s

This queries or limits the number of slaves, set with the -s command line option.

As of V3.5 2017.05.02, slave threads can be adjusted dynamically up to the maximum specified on the command line. A negative number indicates that processes should be used, instead of threads.

q)0N!("current slave threads";system"s");system"s 4";0N!("current,max slave threads";system"s";system"s 0N"); / q -s 8
q)system"s 0" / disable slave threads
q)system"s 0N" / show max slave threads
8i


## \S (random seed)¶

Syntax: \S [n]

Where n is

• omitted: display the last value to which the random seed was initialized
• 0N: display the current value of the random seed (since V3.6)
• non-zero integer: re-initialize the seed to n

Note that \S displays the last value to which the seed was initialized: it is not updated as the random-number generator (rng) is used.

q)\S                       / default
-314159i
q)5?10
8 1 9 5 4
q)5?10
6 6 1 8 5
q)\S -314159               / restore default seed
q)5?10                     / same random numbers generated
8 1 9 5 4
q)\S                       / seed is not updated
-314159
q)x:system "S 0N"          / current value of seed
q)r:10?10
q)system "S ",string x     / re-initialize seed
q)r~10?10
1b


Since V3.1 2013.08.19

Since V3.1 the behavior is as follows.

Random-number generation (rng) is thread-local. \S 1234 sets the seed for the rng for the main thread only. The rng in a slave thread is assigned a seed based on the slave thread number. In multithreaded input mode, the seed is based on socket descriptor. Instances started on ports 20000 through 20099 (slave procs, used with e.g. q -s -4 have the main thread’s default seed based on the port number.

## \t (timer)¶

Syntax: \t [p]

This command has two different uses depending on the parameter given.

An integer parameter is the number of milliseconds between timer ticks. If 0, the timer is turned off, otherwise the timer is turned on and the first tick given. On each tick, the function assigned to .z.ts is executed.

q)\t                           / default off
0
2010.06.01
q)\z 1
q)"D"$"06/01/2010" 2010.01.06  ## \1 & \2 (redirect)¶ Syntax: \1 filename Syntax: \2 filename \1 and \2 allow redirecting stdout and stderr to files from within the q session. The files and intermediate directories are created if necessary. ~/q$ rm -f t1.txt t2.txt
~/q$l64/q KDB+ 2.6 2010.05.10 Copyright (C) 1993-2010 Kx Systems ...  q)\1 t1.txt / stdout q)\2 t2.txt / stderr til 10 2 + "hello" \\  ~/q$ cat t1.txt          / entry in stdout
0 1 2 3 4 5 6 7 8 9
~/q\$ cat t2.txt          / entry in stderr
q)q)'type


On macOS and Linux \1 /dev/stdin returns output to the default.

## \_ (hide q code)¶

Syntax: \_ [scriptname]

This command has two different uses depending on whether a parameter is given.

If no parameter, then \_ checks if client write access is blocked.

q)\_
0b


If a parameter is given, it should be a scriptname and \_ f.q makes a runtime script f.q_. The q code cannot be viewed or serialized.

q):t1.q 0:enlist "a:123;f:{x+2*y}"
q)\_ t1.q               / create locked script
t1.q_
q)\l t1.q_              / can be loaded as usual
q)a                     / definitions are correct
123
q)f[10;1 2 3]
12 14 16
q)f                     / q code is not displayed
locked
q)-8!f                  / or serialized
'type
[0]  -8!f
^
"a:123;f:{x+2*y}"
q)read0:t1.q_          / file contents are scrambled
"'\374E\331\207'\262\355"
"S\014%\210\0273\245"


## \ (terminate)¶

If there is a suspension, this exits one level of the suspension. Otherwise, it toggles between q and k mode. (To switch languages from inside a suspension, type "\".)

q){1+x}"hello"
{1+x}
'type
+
1
"hello"
q))\                         / clear suspension (only one level)
q)\                          / toggle to k mode
!5
0 1 2 3 4
\                          / toggle to q mode
q)


## \ (toggle q/k)¶

In the interactive session \ toggles between the q and k interpreters.

q)\
\
q)


## \\ (quit)¶

Syntax: \\

• In the interactive session type \\ at the prompt to quit the session.
• Inside a function, use value"\\\\" or exit 0 for the same result.

The text following \\ and white space is ignored by q. This is often useful in scripts where \\ can be followed by comments or usage examples.

## OS Commands¶

If an expression begins with \ but is not recognized as a system command, then it is executed as an OS command.

q)\ls                 / usual ls command
"help.q"
"k4.lic"
"l64"
"odbc.k"
"profile.q"
"q.k"
..


Typos can get passed to the OS.

When you are run rm -r /` you are have of many problem, but Big Data is not of one of them. — DevOps Borat