KSQL_OPEN(3)

NAME
ksql_open - open a ksql database connection

LIBRARY
ksql

SYNOPSIS
#include <sys/types.h>
#include <stdint.h>
#include <ksql.h>
enum ksqlc
ksql_open(struct ksql *sql, const char *dbfile);

DESCRIPTION
The ksql_open function opens a database connection to dbfile (which must exist) on a handle allocated with ksql_alloc(3). If the handle was allocated with KSQL_FOREIGN_KEYS, a successful open will be followed by a ksql_exec(3) call to enable foreign keys. If the current role does not permit opening databases, an error message is emitted on stderr and the program is immediately terminated.

The ksql_open function handles a locked database (specifically, SQLITE_BUSY, SQLITE_LOCKED, or SQLITE_PROTOCOL) by sleeping for a random interval, then trying again infinitely.

RETURN VALUES
This returns KSQL_ALREADYOPEN if a database connection is already open, KSQL_MEM if memory allocation failed, KSQL_DB if the sqlite3_open(3) function failed, the exit code of ksql_exec(3) if it failed to enable foreign keys, or otherwise KSQL_OK on success.

EXAMPLES
The following opens a database test.db in split-process mode. For illustrative purpose, it uses pledge(2) to sandbox the controlling parent process. (This security feature is only available on OpenBSD.) For brevity, this does not report an errors.

    struct ksql *sql;
    sql = ksql_alloc_child(NULL, NULL, NULL);
    pledge("stdio", NULL);
    ksql_open(sql, "test.db");
    /* Do stuff  */
    ksql_close(sql);

SEE ALSO
sqlite3_exec(3), sqlite3_open(3)