KSQL_CFG_DEFAULTS(3)

NAME
ksql_cfg_defaults - set defaults for a ksql configuration

LIBRARY
ksql

SYNOPSIS
#include <sys/types.h>
#include <stdint.h>
#include <ksql.h>
void
ksql_cfg_defaults(struct ksqlcfg *cfg);

DESCRIPTION
The ksql_cfg_defaults function initialises cfg with useful defaults: 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. The ksqlitemsg() and ksqlitedbmsg() functions are set as error message loggers. These output to stderr the full error message and error code for both regular and database errors.

The struct ksqlcfg structure consists of the following:

void *arg
    The private argument passed to err and dberr.

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.

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

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.

struct ksqlroles roles
    Role-based access control configuration. Roles map a caller role to stored statements in stmts and set the availability of further role transition with ksql_role(3).

struct ksqlstmts stmts
    Structure containing stored statement information. If stored statements are provided, ksql_stmt_alloc(3) and ksql_exec(3) will only draw from the stored statements.

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 stmts variable configures stored statements. These provide an extra measure of security for ksql_alloc_child(3) contexts where the protected child process manages pre-set SQL statements that cannot be changed by the caller. It contains the following:

const char *const *stmts
    An array of SQL statement strings, none of which may be NULL.

size_t stmtsz
    The number of entries in stmts.

The roles variable configures role-based access control mapping roles to stored statements set in stmts. Stored statements may be used without roles, but roles require stored statements. The structure consists of the following:

struct ksqlrole *roles
    The role array. Each struct ksqlrole entry consists of roles, a list of possible roles that may be subsequently set with ksql_role(3) from the current role; flags, a bit-field consisting only of KSQLROLE_OPEN, which indicates that the role may open databases; and stmts, a list of all possible statements. The index of a statement in stmts and the role in roles corresponds to the id passed to ksql_stmt_alloc(3) and ksql_exec(3). If it zero if false (the role may not execute the statement, or the role may not be entered from the given role), non-zero if it may.

size_t rolesz
    The length of roles.

size_t defrole
    The index of the default role set upon ksql_alloc(3) or ksql_alloc_child(3).

EXAMPLES
In this simple example, a default configuration is extended with stored statements, then the connection is started in split-process mode and the caller sandboxes. (The sandboxing is only available on OpenBSD.) For brevity, no error checking is performed.

    struct ksqlcfg cfg;
    struct ksql *sql;
    const char *const stmts[] = {
      "INSERT INTO test (foo) VALUES (?)",
      "SELECT foo FROM test"
    };
    ksql_cfg_defaults(&cfg);
    cfg.stmts.stmts = stmts;
    cfg.stmts.stmtsz = 2;
    sql = ksql_alloc_child(&cfg, NULL, NULL);
    pledge("stdio", NULL);

SEE ALSO
ksql_alloc(3), ksql_alloc_child(3), ksql_exec(3), ksql_stmt_alloc(3)