NAME

LIBRARY

SYNOPSIS

struct sqlbox *
sqlbox_alloc(struct sqlbox_cfg *cfg);

DESCRIPTION

filts

Filters for opaquely generating or manipulating data instead of drawing directly from a database. Described in sqlbox_step(3).

msg

Error and debug logging. Described in sqlbox_msg_set_dat(3).

roles

Roles and role assignment to statements, sources, and role transition. Described in sqlbox_role(3).

srcs

Database sources (in-memory and on-disc). Described in sqlbox_open(3).

stmts

All SQL statements required by all sources.

sqlbox_alloc() performs the following validity checks on cfg, if not NULL, before forking:

• source filenames may not be NULL
• statements may not be NULL or empty strings
• the default role must be zero or a valid role index
• each role statement must be a valid index
• each role transition role must be a valid index
• each role database must be a valid index
• filters refer to valid statements (since columns are not known beforehand, invalid columns are simply ignored)
• filter callback functions may not be NULL

After successful return, a suggested idiom is for callers to reduce system resources to just the communciation socket with the context. This may be affected with pledge(2) if on OpenBSD.

It is usually followed by calls to sqlbox_open(3).

RETURN VALUES

On success, the pointer must be freed with sqlbox_free(3).

EXAMPLES

struct sqlbox *p;
struct sqlbox_cfg cfg;
struct sqlbox_src srcs[] = {
  { .fname = (char *)":memory:",
    .mode = SQLBOX_SRC_RWC }
};

memset(&cfg, 0, sizeof(struct sqlbox_cfg));
cfg.msg.func_short = warnx;
cfg.srcs.srcs = srcs;
cfg.srcs.srcsz = 1;

if ((p = sqlbox_alloc(&cfg)) == NULL)
  errx(EXIT_FAILURE, "sqlbox_alloc");

/* Do work. */

sqlbox_free(p);

The following does the same, but with RBAC for the source. In this example, arrays in struct sqlbox_role are not set to NULL if they have an associated length as in the case of rolesz.

struct sqlbox *p;
struct sqlbox_cfg cfg;
struct sqlbox_role roles[] = {
  { .rolesz = 0,
    .stmtsz = 0,
    .srcs = (size_t[]){ 0 },
    .srcsz = 1 }
};
struct sqlbox_src srcs[] = {
  { .fname = (char *)":memory:",
    .mode = SQLBOX_SRC_RWC }
};

memset(&cfg, 0, sizeof(struct sqlbox_cfg));
cfg.srcs.srcs = srcs;
cfg.srcs.srcsz = 1;
cfg.roles.roles = roles;
cfg.roles.rolesz = 1;
cfg.roles.defrole = 0;

if ((p = sqlbox_alloc(&cfg)) == NULL)
  errx(EXIT_FAILURE, "sqlbox_alloc");

/* Do work. */

sqlbox_free(p);

SEE ALSO