Skip to content

C API Reference

Quick guide


K object

The C API provides access to the fundamental data K object of kdb+ and methods of manipulating it. The K object is a pointer to a k0 struct, a tagged union, and most of the API manipulates this pointer.

It is defined as

typedef struct k0 *K;

More detailed information can be found in C API header file k.h. The C API defines some types to improve uniformity of the API.

unsigned char   G
16-bit int      H
32-bit int      I
64-bit int      J
32-bit float    E
64-bit double   F
char            C
char*           S
void            V
16-byte array   U

Accessing members of the K object

K object properties for object x

The members which are common to all variant types are t, u, and r. The field n is common to all variant types which have a length. These may be dereferenced as usual in the C language:

x->t    type of K object. (signed char)
x->u    attribute. 0 means no attributes. (C)
x->r    reference count. Modify only via r1(x), r0(x). (I)
x->n    number of elements in a list. (J)

Atom accessors for object x

The fields of the variant types which represent an atom (sometimes called a scalar) are:

kdb+ type   accessor    derived types
byte        x->g (G)    boolean, char
short       x->h (H)
int         x->i (I)    month, date, minute, second, time
long        x->j (J)    timestamp, timespan
real        x->e (E)
float       x->f (F)    datetime
symbol      x->s (S)    error
table       x->k (K)

List accessors

To simplify accessing the members for list variant, the following multiple helper macros are provided, to be used as, kG(x), for example.

q type name   interface list accessor function
mixed list    K* kK(x)
boolean       G* kG(x)
guid          U* kU(x)
byte          G* kG(x)
short         H* kH(x)
int           I* kI(x)
long          J* kJ(x)
real          E* kE(x)
float         F* kF(x)
char          C* kC(x)
symbol        S* kS(x)
timestamp     J* kJ(x)
month         I* kI(x)
date          I* kI(x)  days from 2000.01.01
datetime      F* kF(x)  days from 2000.01.01
timespan      J* kJ(x)  nanoseconds
minute        I* kI(x)
second        I* kI(x)
time          I* kI(x)  milliseconds
dictionary    kK(x)[0]  or keys and kK(x)[1] for values

Reference counting

Q uses reference counting to manage object lifetimes. You are said to own a reference if you have created it with r1 or received it with an object returned to a call by a C API function. You are responsible for destroying the reference you own with r0 when you are finished with the object.

Ownership of a reference to an object passed as parameter can be taken from you by some of the C API functions. Other C API functions, and all functions from dynamically-linked modules, do not take ownership of references to their parameters; they have to create a new reference to any object they wish to retain or return.

If ownership of a reference has been taken from you, you are no longer responsible for it and should not destroy it. To retain an owned reference to an object, create a new reference to it prior to the call.

Error handling

C API functions marked as requiring ee return 0 on error. You should either propagate the error further by returning 0 or handle it by calling ee and handling the resulting object.

Note that you can only return an error object at a top level from a C function called from q.


Q has a rich type system. The type is indicated by a type number and many of these numbers have a constant defined around 0. Positive numbers are used for types which have a length, and the negative of these represent the scalar type.

For example, KB is the type for a vector of booleans, and the negative, -KB is for an atom of type boolean.

Some types do not have a constant. For example, mixed list has type 0, and error has a type -128.

constant  associated type  value
KB        boolean          1
UU        guid             2
KG        byte             4
KH        short            5
KI        int              6
KJ        long             7
KE        real             8
KF        float            9
KC        char             10
KS        symbol           11
KP        timestamp        12
KM        month            13
KD        date             14
KZ        datetime         15
KN        timespan         16
KU        minute           17
KV        second           18
KT        time             19
XT        table            98
XD        dictionary       99

Some numeric constants are defined and have special meaning – indicating null or positive infinity for that type.

constant   value                                      description
nh         0xFFFF8000                                 short null
wh         0x7FFF                                     short infinity
ni         0x80000000                                 int null
wi         0x7FFFFFFF                                 int infinity
nj         0x8000000000000000                         long null
wj         0x7FFFFFFFFFFFFFFF                         long infinity
nf         log(-1.0) on Windows or (0/0.0) on Linux   float null
wf         -log(0.0) in Windows or (1/0.0) on Linux   float infinity

Functions by category


ka atom kj long ktj timespan kb boolean knk list ktn vector kc char knt keyed table ku guid kd date kp char array kz datetime ke real kpn char array vaknk va_list version of knk kf float ks symbol xD dictionary kg byte kt time xT table kh short ktd simple table ki int ktj timestamp


ja raw value to list js interned string to symbol vector jk K object to list jv K list to first of same type

When appending to a list, if the capacity of the list is insufficient to accommodate the new data, the list is reallocated with the contents of x updated. The new data is always appended, unless the reallocation causes an out-of-memory condition which is then fatal; these functions never return NULL. The reallocation of the list will cause the initial list’s reference count to be decremented. The target list passed to join functions should not have an attribute, and the caller should consider that modifications to that target object will be visible to all references to that object unless a reallocation occurred.

Other functions

b9 serialize r0 decrement ref count d9 deserialize r1 increment ref count dj date to integer sd0 remove callback dl dynamic link sd0x remove callback dot apply sd1 function on event loop ee capture error setm toggle symbol lock k evaluate sn intern chars from string krr signal C error ss intern null-terminated string m9 release memory vak va_list version of k okx verify IPC message ymd encode q date orr signal system error

Standalone applications

kclose disconnect from host khp connect to host without credentials khpu connect to host without timeout khpun connect to host khpunc connect to host with capability

Unless otherwise specified, no function accepting K objects should be passed NULL.

Functions by name

In the following descriptions, functions are tagged as follows.

c.o  is also available in c.o
own  takes ownership of a reference
ee   requires ee for error handling

b9 (serialize)

K b9(I mode, K x)
Tags: c.o ee

Uses q IPC and mode capabilities level, where mode is:

value effect
-1 valid for V3.0+ for serializing/deserializing within the same process
0 unenumerate, block serialization of timespan and timestamp (for working with versions prior to V2.6)
1 retain enumerations, allow serialization of timespan and timestamp: Useful for passing data between threads
2 unenumerate, allow serialization of timespan and timestamp
3 unenumerate, compress, allow serialization of timespan and timestamp
4 (reserved)
5 allow 1TB msgs, but no single vector may exceed 2 billion items
6 allow 1TB msgs, and individual vectors may exceed 2 billion items

On success, returns a byte-array K object with serialized representation. On error, NULL is returned; use ee to retrieve error string.

d9 (deserialize)

K d9(K x)
Tags: c.o ee

The byte array x is not modified.

On success, returns deserialized K object. On error, NULL is returned; use ee to retrieve the error string.

dj (date to number)

I dj(I date)
Tags: c.o

Converts a q date to a yyyymmdd integer.

ymd – numbers to date

K dl(V* f, J n)

Function takes a C function that would take n K objects as arguments and returns a K object. Shared library only.

Returns a q function.

dot (apply)

K dot(K x, K y)
Tags: ee

The same as the q function Apply, i.e. .[x;y]. Shared library only.

On success, returns a K object with the result of the . application. On error, NULL is returned. See ee for result-handling example.

ee (error string)

K ee(K)
Tags: c.o

Capture (and reset) error string into usual error object, e.g.

K x=ee(dot(a,b));if(xt==-128)printf("error %s\n", x->s);

Since V3.5 2017.02.16, V3.4 2017.03.13

Handling errors

If a function returns type K and has the option to return NULL, the user should wrap the call with ee, and check for the error result, also considering that the error string pointer (x->s) may also be NULL. e.g.

​K x=ee(dot(a,b));if(xt==-128)printf("error %s\n", x->s?x->s:"");

Otherwise the error status within the interpreter may still be set, resulting in the error being signalled incorrectly elsewhere in kdb+.

Calling ee(…) has the side effect of clearing the interpreter’s error status for the NULL result path.

ja (join value)

K ja(K* x, V*)
Tags: c.o

Appends a raw value to a list. x points to a K object, which may be reallocated during the function. The contents of x, i.e. *x, will be updated in case of reallocation.

Returns a pointer to the (potentially reallocated) K object.

jk (join K object)

K jk(K* x, K y)
Tags: c.o own

Appends another K object to a mixed list. Takes ownership of a reference to its argument y.

Returns a pointer to the (potentially reallocated) K object.

js (join string)

K js(K* x, S s)
Tags: c.o

Appends an interned string s to a symbol list.

Returns a pointer to the (potentially reallocated) K object.

jv (join K lists)

K jv(K* x, K y)
Tags: c.o

Append a K list y to K list x. Both lists must be of the same type.

Returns a pointer to the (potentially reallocated) K object.

k (evaluate)

K k(I handle, const S s, …)
Tags: own

Evaluates s. Optional parameters are either local (shared library only) or remote. The last argument must be NULL.

Takes ownership of references to its arguments.

Behavior depends on the value of handle.

  • handle>0, sends sync message to handle, to evaluate a string or function with parameters, and then blocks until a message of any type is received on handle. It can return NULL (indicating a network error) or a pointer to a K object. k(handle,(S)NULL) does not send a message, and blocks until a message of any type is received on handle. The handle should have been previously returned from this API's family of connect functions e.g. khp.

    If that object has type -128, it indicates an error, accessible as a null-terminated string in r->s. When you have finished using this object, it should be freed by calling r0(r).

  • handle<0, this is for async messaging, and the return value can be either 0 (network error) or non-zero (success). This result should not be passed to r0. The handle should have been previously returned from this API's family of connect functions e.g. khp.

  • handle==0 is valid only for a plugin, and executes against the kdb+ process in which it is loaded.

See more on message types. Note that a k() call will block until a message is completely sent/received (handle!=0) or evaluated (handle=0). This is true for both sync and async message types, although only the former will wait on a response from the peer socket. One should not confuse the qIPC async message type with async I/O.

Blocking sockets

As the C API does not perform any buffering, it does not support sending or reception of partial messages. Hence qIPC sockets must remain in blocking mode regardless of the message type used.

ka (create atom)

K ka(I t)
Tags: c.o

Creates an atom of type t.

kb (create boolean)

K kb(I)
Tags: c.o

kc (create char)

K kc(I)
Tags: c.o

Null: kc(" ")

kclose (disconnect)

V kclose(I)

With the release of c.o with V2.6, c.o now tracks the connection type (pre V2.6, or V2.6+). Hence, to close the connection, you must call kclose (instead of close or closeSocket): this will clean up the connection tracking and close the socket.

Standalone apps only. Available only from the c/e libs and not as a shared library loaded into kdb+.

kd (create date)

K kd(I)
Tags: c.o

Null: kd(ni)

ke (create real)

K ke(F)
Tags: c.o

Null: ke(nf)

kf (create float)

K kf(F)
Tags: c.o

Null: kf(nf)

kg (create byte)

K kg(I)
Tags: c.o

kh (create short)

K kh(I)
Tags: c.o

Null: kh(nh)

khp (connect anonymously)

I khp(const S hostname, I port)

Standalone apps only. Available only from the c/e libs and not as a shared library loaded into kdb+.

khpu(hostname, port, "")

khpu (connect, no timeout)

I khpu(const S hostname, I port, const S credentials)

Standalone apps only. Available only from the c/e libs and not as a shared library loaded into kdb+.

khpun(hostname, port, credentials, 0)

khpun (connect)

I khpun(const S hostname, I port, const S credentials, I timeout)

Establish a connection to hostname on port providing credentials (username:password format) with timeout.

On success, returns positive file descriptor for established connection. On error, 0 or a negative value is returned.

 0   Authentication error
-1   Connection error
-2   Timeout error

Standalone apps only. Available only from the c/e libs and not as a shared library loaded into kdb+.

khpunc (connect with capability)

I khpunc(S hostname, I port, S credentials, I timeout, I capability)

Standalone apps only. Available only from the c/e libs and not as a shared library loaded into kdb+.

capability is a bit field:

1    1 TB limit
2    use TLS

Messages larger than 2GB

During the initial handshake of a connection, each side’s capability is exchanged, and the common maximum is chosen for the connection. By setting the capability parameter for khpunc, the default message-size limit for this connection can be raised from 2GB to 1TB. e.g.

int handle=khpunc("hostname",5000,"user:password",timeout,1);

A TLS-enabled connection supporting upto 1TB messages can be achieved via bit-or of the TLS and 1TB bits, e.g.

int handle=khpunc("hostname",5000,"user:password",timeout,1|2);

A return value of -3 indicates the OpenSSL initialization failed.

 0   Authentication error
-1   Connection error
-2   Timeout error
-3   OpenSSL initialization failed


Unix domain socket

For khp, khpu, khpun, and khpunc a Unix domain socket may be requested via the IP address, e.g.

int handle=khpu("",5000,"user:password");

ki (create int)

K ki(I)
Tags: c.o

Null: ki(ni)

kj (create long)

K kj(J)
Tags: c.o

Null: kj(nj)

knk (create list)

K knk(I n, …)
Tags: c.o

Create a mixed list.

Takes ownership of references to arguments.

knt (create keyed table)

K knt(J n, K x)
Tags: c.o ee

Create a table keyed by n first columns if number of columns exceeds n.

Returns null if the argument x is not a table.

kp (create string)

K kp(S x)
Tags: c.o

Create a char array from a string.

kpn (create fixed-length string)

K kpn(S x, J n)
Tags: c.o

Create a char array from a string of length n.

krr (signal C error)

K krr(const S)
Tags: c.o

kdb+ recognizes an error returned from a C function via the function’s return value being 0, combined with the value of a global error indicator that can be set by calling krr with a null-terminated string. As krr records only the passed pointer, you should ensure that the string remains valid after the return from your code into kdb+ – typically you should use static storage for the string. (Thread-local if you expect to amend the error string from multiple threads.) The strings "stop", "abort" and "stack" are reserved values and krr must not be called with those.

Do not call krr() and then return a valid pointer! For convenience, krr returns 0, so it can be used directly as

K f(K x){
  K r=someFn();
  if(some error)
    return krr("an error message"); // preferred style
  return r;

or a style more prone to mismatch, decoupled as

K f(K x){
  I f=0;
  K r=someFn();
  if(some error){
    krr("an error message"); // set the message string
    return 0; // combined with string set via krr(), this return value of 0 indicates an error 
    return r;

Error signaling and catching

ks (create symbol)

K ks(S x)
Tags: c.o

Null: ks("")

kt (create time)

K kt(I x)
Tags: c.o

Create a time from a number of milliseconds since midnight.

Null: ki(ni)

ktd (create simple table)

K ktd(K x)
Tags: c.o ee own

Create a simple table from a keyed table.

Takes ownership of a reference to its argument x.

ktj (create timestamp)

K ktj(-KP, x)
Tags: c.o

Create a timestamp from a number of nanos since 2000.01.01.

Null: ktj(-KP, nj)

ktj (create timespan)

K ktj(-KN, x)
Tags: c.o

Create a timespan from a number of nanos since the beginning of the interval: midnight in the case of .z.n.

Null: ktj(-KN, nj)

ktn (create vector)

K ktn(I type, J length)
Tags: c.o

ku (create guid)

K ku(U)
Tags: c.o

Null: U g={0};ku(g)

kz (create datetime)

K kz(F)
Tags: c.o

Create a datetime from the number of days since 2000.01.01. The fractional part is the time.

Null: kz(nf)

m4 (stats)

K m4(I)

Provides memory statistics. Standalone apps only.

With parameter value 0, returns current memory usage for the current thread, as a list of 3 long integers:

0 number of bytes allocated

1 bytes available in heap

2 maximum heap size so far

With parameter value 1, returns symbol stats as a pair of longs:

0 number of internalized symbols (or null value if not main thread)

1 corresponding memory usage (or null value if not main thread)

m9 (release memory)

V m9(V)

Release the memory allocated for the thread’s pool.

Call m9() when the thread is about to complete, releasing the memory allocated for that thread’s pool.

okx (verify IPC message)

I okx(K x)
Tags: c.o

Verify that the byte vector x is a valid IPC message.

Decompressed data only. x is not modified.

Returns 0 if not valid.

orr (signal system error)

K orr(const S)
Tags: c.o

Similar to krr, this appends a system-error message to string S before passing it to krr.

The system error message looks at errno/GetLastError and, if set, will format using strerror/FormatMessage.

The user error string is copied to a static, thread-local buffer and, as such, is valid until the next call to orr from that thread. However, the total message size (including both user and system error) is limited to 255 characters and is truncated if it exceeds this limit.

r0 (decrement refcount)

V r0(K)
Tags: c.o

Decrement an object‘s reference count.

If x->r is 0, x is unusable after the r0(x) call, and the memory pointed to by it may have been freed.

Reference counting starts and ends with 0, not 1.

r1 (increment refcount)

K r1(K)
Tags: c.o

Increment an object‘s reference count.

sd0 (remove callback)

V sd0(I d)

Remove the callback on d and call kclose.

Shared library only.

sd0x (remove callback conditional)

V sd0x(I d, I f)

Remove the callback on d and call kclose on d if f is 1.

Shared library only. Since V3.0 2013.04.04.

sd1 (set function on loop)

K sd1(I d, f)

Put the function K f(I d){…} on the q main event loop given a socket d.

If d is negative, the socket is switched to non-blocking.

The function f should return NULL or a pointer to a K object, and its reference count will be decremented. (It is the return value of f that will be r0’d – and only if not null.)

Shared library only.

On success, returns int K object containing d. On error, NULL is returned, d is closed.

Since 4.1t 2023.09.15, sd1 no longer imposes a limit of 1023 on the value of the descriptor submitted.


setm (toggle symbol lock)

I setm(I m)

Set whether interning symbols uses a lock: m is either 0 or 1.

Returns the previously set value.

sn (intern chars)

S sn(S, J n)
Tags: c.o

Intern n chars from a string.

Returns an interned string and should be used to store the string in a symbol vector.

ss (intern string)

S ss(S)
Tags: c.o

Intern a null-terminated string.

Returns an interned string and should be used to store the string in a symbol vector.

sslInfo (SSL info)

K sslInfo(K x)

A dictionary of settings similar to -26!x, or an error if SSL initialization failed.

extern I khpunc(S hostname,I port,S usernamepassword,I timeout,I capability);
int handle=khpunc("remote host",5000,"user:password",timeout,2);
extern K sslInfo(K x);
    K x=ee(sslInfo((K)0));
    printf("Init error %s\n",xt==-128?x->s:"unknown");

Returns null if there was an error initializing the OpenSSL lib.

vak, vaknk (va_list versions of k, knk)

K vak(I,const S,va_list)
K vaknk(I,va_list)

where va_list is as defined in stdarg.h, included by k.h

These are va_list versions of the K k(I,const S,…) and K knk(I,…) functions, useful for writing variadic utility functions that can forward the K objects.

comp.lang.c: How can I write a function which takes a variable number of arguments and passes them to some other function (which takes a variable number of arguments)?

ver (release date)

I ver()

Returns an int as yyyymmdd.

vi (vector at index)

K vi(K x,UJ j)
Access elements of the types 77..97 inclusive (anymap and nested homogenous vectors), akin to the macro usage kK(x)[j] for x of type 0. Increments the reference count of the object at x[j], and hence the result should be freed via r0(result) when it is no longer needed. If j is out of bounds, i.e. j>=xn, a null object for the first element's type is returned. Available within shared library only.

vk (collapse homogeneous list)

K vk(K)
Tags: own

Tries to collapse a general list of homogeneous elements into a simple list, or conforming dictionaries into a table. Takes ownership of its argument.

K f(){J i;K x=ktn(0,0);for(i=0;i<10;i++)jk(&x,g(i));return vk(x);} // g(i) could return different types

xD (create dictionary)

K xD(K x, K y)
Tags: c.o own

Create a dictionary from two K objects.

Takes ownership of references to the arguments.

If y is null, will r0(x) and return null.

xT (table from dictionary)

K xT(K x)
Tags: c.o ee own

Create a table from a dictionary object.

Will r0(x) and return null if it is unable to form a valid table from x.

Takes ownership of a reference to its argument x.

ymd (numbers to date)

I ymd(year, month, day)
Tags: c.o

Encode a year/month/day as a q date, e.g. 0==ymd(2000, 1, 1)

dj – date to number