SQLBOX_ROLE(3)

NAME
sqlbox_role - change role of sqlbox context

LIBRARY
sqlbox

SYNOPSIS
#include <stdint.h>
#include <sqlbox.h>
void
sqlbox_role(struct sqlbox *box, size_t role);

DESCRIPTION
Change the active role of box to role. Changing to the current role has no effect.

Roles are defined in struct sqlbox_roles as passed to sqlbox_alloc(3). It has the following fields:

roles
    An array of roles, each role being identified by its index. For example, if rolesz is 2, the first role (index 0) is role 0, the second role (index 1) is role 1.

rolesz
    The number of roles. If zero, there are no roles and defrole is ignored.

defrole
    The default role if and only if rolesz is non-zero, in which case it must be less than rolesz.

The resources available to each role are defined in struct sqlbox_role, which has the following fields:

roles
    Which roles the given role may transition into. For example, an array of size 2 with values 0 and 1 would mean that the current role may transition into roles 0 and 1. The value for self-transition is ignored: self-transition is always allowed.

rolesz
    Number of elements in roles.

stmts
    Which statement indices the given role may execute or prepare with sqlbox_exec(3) and sqlbox_prepare_bind(3), respectively.

stmtsz
    Number of elements in stmts.

srcs
    Which source indices the given role may open or close with sqlbox_open(3) and sqlbox_close(3), respectively.

srcsz
    Number of elements in srcs.

RETURN VALUES
Returns zero if communication with box fails. Otherwise, returns non-zero.

If role is not a valid role, no roles have been configured, or the current role does not have permission to transition to it, subsequent box access will fail. Use sqlbox_ping(3) to check explicitly.

If sqlbox_role() fails, box is no longer accessible beyond sqlbox_ping(3) and sqlbox_free(3).

EXAMPLES
To transition from one "privileged" role into another "unprivileged" role (which cannot further transition nor open a database):

    struct sqlbox *p;
    struct sqlbox_cfg cfg;
    struct sqlbox_src srcs[] = {
      { .fname = (char *)":memory:",
        .mode = SQLBOX_SRC_RWC },
    };
    struct sqlbox_role roles[] = {
      { .rolesz = 2,
        .roles = (size_t[]){ 1, 0 },
        .stmtsz = 0,
        .srcsz = 1,
        .srcs = (size_t[]){ 0 } },
      { .rolesz = 0,
        .stmtsz = 0,
        .srcsz = 0 }
    };
    memset(&cfg, 0, sizeof(struct sqlbox_cfg));
    cfg.msg.func_short = warnx;
    cfg.roles.rolesz = 2;
    cfg.roles.roles = roles;
    cfg.roles.rolesz = 1;
    cfg.roles.roles = srcs;
    cfg.roles.defrole = 0;
    if ((p = sqlbox_alloc(&cfg)) == NULL)
      errx(EXIT_FAILURE, "sqlbox_alloc");
    if (!(id = sqlbox_open(p, 0)))
      errx(EXIT_FAILURE, "sqlbox_open");
    if (!sqlbox_role(p, 1))
      errx(EXIT_FAILURE, "sqlbox_role");
    /* Now operate as the "unprivileged" role. */
    /* The database will be closed out automatically. */
    sqlbox_free(p);

SEE ALSO
sqlbox_ping(3)