C API reference

C client for kdb+

Overview

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.

type type letter
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:

accessor description
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] for keys and kK(x)[1] for values

Constants

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 floating point null
wf -log(0.0) in Windows or (1/0.0) on Linux floating point infinity

Functions

Constructors

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

Joins

function joins function joins
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

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

Standalone applications

function action
kclose disconnect from host
khp connect to host without credentials
khpu connect to host without timeout
khpun connect to host

No NULL

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

By name

b9 – serialize

Signature: K b9(I mode, K x)

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

value effect
-1 use within shared libraries from V3.0 onwards
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

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

d9 – deserialize

Signature: K d9(K x)

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

Signature: I dj(I date)

Converts a q date to a yyyymmdd integer.

Signature: K dl(V* f, I 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

Signature: K dot(K x, K y)

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

Signature: K ee(K)

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

ja – join value

Signature: K ja(K* x, V*)

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

Signature: K jk(K* x, K y)

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

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

js – join string

Signature: K js(K* x, S s)

Appends an interned string s to a symbol list.

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

jv – join K lists

Signature: K jv(K* x, K y)

Append a K list y to K list x.

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

k – evaluate

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

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

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. 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.

  • 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 sent/received (handle!=0) or evaluated (handle=0).

ka – create atom

Signature: K ka(I t)

Creates an atom of type t.

kb – create boolean

Signature: K kb(I)

kc – create char

Signature: K kc(I)

Null: kc(" ")

kclose – disconnect

Signature: 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.

kd – create date

Signature: K kd(I)

Null: kd(ni)

ke – create real

Signature: K ke(F)

Null: ke(nf)

kf – create float

Signature: K kf(F)

Null: kf(nf)

kg – create byte

Signature: K kg(I)

kh – create short

Signature: K kh(I)

Null: kh(nh)

khp – connect anonymously

Signature: I khp(const S h, I p)

khpu(h, p, "")

khpu – connect, no timeout

Signature: I khpu(const S h, I p, const S u)

khpun(h, p, u, 0)

khpun – connect

Signature: I khpun(const S h, I p, const S u, I n)

Establish a connection to host h on port p providing credentials ("username:password" format) u with timeout n.

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

code | error
-----|-------
  0  | Authentication error
 -1  | Connection error
 -2  | Time out error

ki – create int

Signature: K ki(I)

Null: ki(ni)

kj – create long

Signature: K kj(J)

Null: kj(nj)

knk – create list

Signature: K knk(I n, …)

Create a mixed list.

Takes ownership of arguments.

knt – create keyed table

Signature: K knt(J n, K x)

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

kp – create string

Signature: K kp(S x)

Create a char array from a string.

kpn – create fixed string

Signature: K kpn(S x, J n)

Create a char array from a string of length n.

krr – signal C error

Signature: K krr(const S)

Signal an error from your C code.

It is the user’s responsibility to ensure the string is valid for the expected lifetime of the error.

ks – create symbol

Signature: K ks(S)

Null: ks("")

kt – create time

Signature: K kt(I)

Create a time from a number of milliseconds since midnight.

Null: ki(ni)

ktd – create simple table

Signature: K ktd(K)

Create a simple table from a keyed table.

ktj – create timestamp

Signature: K ktj(-KP, x)

Create a timestamp from a number of nanos since 2000.01.01.

Null: ktj(-KP, nj)

ktj – create timespan

Signature: K ktj(-KN, x)

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

Signature: K ktn(I type, J length)

ku – create guid

Signature: K ku(U)

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

kz – create datetime

Signature: K kz(F)

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

Null: kz(nf)

m9 – release memory

Signature: 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

Signature: I okx(K x)

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

Signature: K orr(const S)

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

r0 – decrement refcount

Signature: V r0(K)

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.

Start from nothing

Reference counting starts (ends?) with 0, not 1.

r1 – increment refcount

Signature: K r1(K)

Increment an object‘s reference count.

sd0 – remove callback

Signature: V sd0(I d)

Remove the callback on d and call kclose.

Shared library only.

sd0x – remove callback conditional

Signature: 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

Signature: 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 and es will contain error string.

setm – toggle symbol lock

Signature: 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

Signature: S sn(S, J n)

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

Signature: S ss(S)

Intern a null-terminated string.

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

xD – create dictionary

Signature: K xD(K, K)

Create a dictionary from two K objects.

Takes ownership of the arguments; destroys the arguments on failure.

xT – table from dictionary

Signature: K xT(K)

ymd – numbers to date

Signature: I ymd(year, month, day)

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