SQLBOX_PING(3)

NAME
sqlbox_ping - test whether sqlbox context is active

LIBRARY
sqlbox

SYNOPSIS
#include <stdint.h>
#include <sqlbox.h>
void
sqlbox_ping(struct sqlbox *box);

DESCRIPTION
Tests whether box is active. This is useful for checking whether operations that do not report an error (e.g., sqlbox_finalise(3)) have failed before the next operation of interest.

RETURN VALUES
Returns non-zero on success or zero if communication with box fails.

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

EXAMPLES
To check whether sqlbox_close(3) failed:

    struct sqlbox *p;
    struct sqlbox_src srcs[] = {
      { .fname = (char *)":memory:",
        .mode = SQLBOX_SRC_RWC },
    };
    struct sqlbox_cfg cfg;
    size_t id;
    memset(&cfg, 0, sizeof(struct sqlbox_cfg));
    cfg.msg.func_short = warnx;
    cfg.srcs.srcsz = 1;
    cfg.srcs.srcs = srcs;
    if ((p = sqlbox_alloc(&cfg)) == NULL)
      errx(EXIT_FAILURE, "sqlbox_alloc");
    if (!(id = sqlbox_open(p, 0)))
      errx(EXIT_FAILURE, "sqlbox_open");
    if (!sqlbox_close(p, id))
      errx(EXIT_FAILURE, "sqlbox_close");
    if (!sqlbox_ping(p))
      errx(EXIT_FAILURE, "sqlbox_ping");
    /* Success! Do other stuff... */
    sqlbox_free(p);