KSQL_ALLOC(3)

NAME
ksql_alloc - allocate a ksql database handle

LIBRARY
ksql

SYNOPSIS
#include <stdint.h>
#include <ksql.h>
struct ksql *
ksql_alloc(const struct ksqlconfig *cfg);

DESCRIPTION
The ksql_alloc function creates a SQLite database handle. This 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 database is opened within the calling process. For a split-process model, see ksql_alloc_child(3).

If cfg is NULL, useful defaults are used. 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 consists of the following:

unsigned int flags
    A bit-field which may consists of KSQL_EXIT_ON_ERR, which causes the system to exit(3) if any database errors occur; KSQL_FOREIGN_KEYS, which causes the database to be subsequently opened with foreign key support; and KSQL_SAFE_EXIT, which causes the library to register an atexit(3) hook to free the database if it hasn't be freed prior to exit. The KSQL_SAFE_EXIT flag will also cause the SIGABRT and SIGSEGV signals to be caught and siglongjmp(3) into an exit handler, which will then close out open databases.

ksqlmsg err
    Supply a function that will be invoked upon a non-database error, for example, memory allocation.

ksqldbmsg dberr
    A function that will be invoked upon a database error, for example, if sqlite3_step(3) does not return an SQLITE_DONE or SQLITE_ROW code.

arg The private argument passed to err and dberr.

The ksqlmsg function is invoked as void ksqlmsg(void *arg, enum ksqlc code, const char *file, const char *msg), with arg being the private argument, argc being the error code in question, the database file (which may be NULL), and msg being an ASCII string describing the error (in English).

The ksqldbmsg function is void ksqldbmsg(void *arg, int sqlerr, int sqlexterr, const char *file, const char *msg), which also has the sqlerr and sqlexterr SQLite error and extended error code, and and the SQLite string error message msg. The library exports two functions, ksqlitemsg() and ksqlitedbmsg(), which are used as the defaults.

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

SEE ALSO
ksql_alloc_child(3), ksql_free(3)