NAME

sqlbox_parm_float, sqlbox_parm_int, sqlbox_parm_string_alloc — convert sqlbox results

LIBRARY

library “sqlbox”

SYNOPSIS

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

int
sqlbox_parm_blob(const struct sqlbox_parm *p, void *v, size_t insz, size_t *outsz);

int
sqlbox_parm_blob_alloc(const struct sqlbox_parm *p, void **v, size_t *outsz);

int
sqlbox_parm_float(const struct sqlbox_parm *p, double *v);

int
sqlbox_parm_int(const struct sqlbox_parm *p, int64_t *v);

int
sqlbox_parm_string(const struct sqlbox_parm *p, char *v, size_t insz, size_t *outsz);

int
sqlbox_parm_string_alloc(const struct sqlbox_parm *p, char **v, size_t *outsz);

DESCRIPTION

Convert between result types as returned from sqlbox_step(3). They use the following conversion matrix, with the type-from specified on the left-most column, and the type-to on corresponding columns of the same row.

For example, an integer is cast into a string by way of the "%PRId64" modifier to the applicable function of the printf(3) family.

The "cast" means a native cast and "self" simply means a non-conversion. Values starting with "%" (the percent sign) are as passed to asprintf(3) or snprintf(3) depending upon whether the function allocates memory. The "bcopy" are binary copies. A dash (“-”) means that conversion is not possible. The remainder are functions.

sqlbox_parm_string() and sqlbox_parm_string_alloc() additionally accept the optional outsz parameter, which is set to the size (not including the trailing NUL terminator) of the allocated string for sqlbox_parm_string_alloc() or for how many bytes would be written into sqlbox_parm_string(), again not including the trailing NUL terminator. The outsz is thus equivalent to the return value of strlcpy(3), asprintf(3), or snprintf(3). If passed as NULL, it is not set.

sqlbox_parm_string() also accepts the size of v as insz, which is the full buffer size including where the NUL terminator will be written. If the resulting string isn't large enough for insz, it is truncated and the NUL terminator always written.

sqlbox_parm_blob() and sqlbox_parm_blob_alloc() behave similarly except for with strings, where the NUL terminator is considered part of the buffer size.

RETURN VALUES

These functions return -1 on failure, 0 if no conversion occurred (the requested type is the input type), and 1 if a conversion occurred. Failure occurs in memory allocation failure or sqlbox_parm_string() was given a zero-sized buffer, underflow or overflow occurs, or the conversion was not possible according to the above table.

SEE ALSO

sqlbox_step(3)

CAVEATS

Native casts between un-representable values is not well defined. For example, casting DBL_MAX into an integer differs in result between platforms.