KSQL_ALLOC_CHILD(3)

NAME
ksql_alloc_child - allocate a ksql database handle in split-process mode

LIBRARY
ksql

SYNOPSIS
#include <stdint.h>
#include <ksql.h>
struct ksql *
ksql_alloc_child(const struct ksqlconfig *cfg, void (*onfork)(void *arg), void *arg);

DESCRIPTION
The ksql_alloc_child function creates a SQLite database handle. It must be matched by a call to ksql_free(3) unless KSQL_SAFE_EXIT is specified, in which case it will be freed on exit. (It is still good practise to manually free.) It is usually followed by ksql_open(3).

The ksql_alloc_child function differs from ksql_alloc(3) in that the database is opened in a child process instead of within the current process, with all database queries running over a communication socket. This way, the caller can safely sandbox after the function returns.

If cfg is NULL, useful defaults are used. The onfork function, if specified, is invoked by the child after a successful fork(2) with the arg variable. Note: the process environment within which onfork is invoked is prior to its being sandboxed.

The defaults on cfg are that the KSQL_EXIT_ON_ERR and KSQL_SAFE_EXIT flags are set, which means that any errors in using database routines will trigger an exit; and upon exiting in such a state, the database will be properly cleaned up. Moreover, a simple message will be written to stderr with the full error message and error code for both regular and database errors.

The struct ksqlconfig structure is documented in ksql_alloc(3).

RETURN VALUES
This returns the allocated database handle or NULL if memory allocations failed.

SEE ALSO
ksql_alloc(3), ksql_free(3)