NAME

sqlbox_alloc — allocate sqlbox context

LIBRARY

library “sqlbox”

SYNOPSIS

#include <stdint.h>
#include <sqlbox.h>

struct sqlbox *
sqlbox_alloc(struct sqlbox_cfg *cfg);

DESCRIPTION

Creates an sqlbox context: verifies cfg, then forks a child "database" process, then returns. cfg is inherited by the database process but never freed, so it may either be constructed statically or allocated and freed by the caller. It has the following fields:

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

Returns the allocated context or NULL if cfg is invalid, memory allocation failed, or the fork(2) or socketpair(2) functions failed.

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

EXAMPLES

This allocates a simple memory-only database source and sets the warning channel to warnx(3).

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

sqlbox_free(3), sqlbox_open(3)