ksql_cfg_defaults —
set defaults for a ksql configuration
library “ksql”
#include
<sys/types.h>
#include
<stdint.h>
#include
<ksql.h>
void
ksql_cfg_defaults(
struct
ksqlcfg *cfg);
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).
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);
ksql_alloc(3),
ksql_alloc_child(3),
ksql_exec(3),
ksql_stmt_alloc(3)