NAME

ksql_open —

open a ksql database connection

LIBRARY

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);