|
libfossil
|
Go to the source code of this file.
Data Structures | |
| struct | fsl_db |
| Db handle wrapper class. More... | |
| struct | fsl_db_event |
| An "event" message type for use with fsl_db. More... | |
| struct | fsl_stmt |
| Represents a prepared statement handle. More... | |
Macros | |
| #define | E(X, V) |
| #define | fsl_db_empty_m |
| Empty-initialized fsl_db structure, intended for const-copy initialization. | |
| #define | fsl_db_event_map(E) |
| A map of fsl_db_event types. | |
| #define | fsl_db_txn_end(DB, DOROLLBACK) |
| Equivalent to fsl_db_txn_end_v2(DB, !DOROLLBACK, ! | |
| #define | fsl_stmt_empty_m |
| Empty-initialized fsl_stmt instance, intended for use as an in-struct initializer. | |
Typedefs | |
| typedef struct fsl_db_event | fsl_db_event |
| typedef enum fsl_db_event_e | fsl_db_event_e |
| typedef int(* | fsl_db_event_f) (fsl_db_event const *e) |
| An event callback for fsl_db objects, primarily for communicating on-transaction-start/end. | |
| typedef sqlite3 | fsl_db_t |
| A level of indirection to "hide" the actual db driver implementation from the public API. | |
| typedef int(* | fsl_stmt_each_f) (fsl_stmt *stmt, void *state) |
| A callback interface for use with fsl_stmt_each() and fsl_db_each(). | |
| typedef sqlite3_stmt | fsl_stmt_t |
Enumerations | |
| enum | fsl_db_event_e { fsl_db_event_map =(E) } |
| A flag type for use with fsl_db_event_f() implementations. More... | |
| enum | fsl_db_event_mask2_e { FSL_DB_EVENT_group_txn , FSL_DB_EVENT_group_sql_trace } |
| Convenience FSL_DB_EVENT_... entries which cannot be defined until after fsl_db_event_e is. More... | |
| enum | fsl_db_event_mask_e { FSL_DB_EVENT_mask_reserved = 0x7ffff000 , FSL_DB_EVENT_mask_payload = 0x00000f00 , FSL_DB_EVENT_payload_buffer = 0x00000100 , FSL_DB_EVENT_mask_id = 0x000000ff , FSL_DB_EVENT_listen_all = FSL_DB_EVENT_mask_id } |
| Bitmasks for use with fsl_db_event_e. More... | |
| enum | fsl_db_open_flags_e { FSL_DB_OPEN_NONE = 0 , FSL_DB_OPEN_RO = 0x01 , FSL_DB_OPEN_RW = 0x02 , FSL_DB_OPEN_CREATE = 0x04 , FSL_DB_OPEN_RWC = FSL_DB_OPEN_RW | FSL_DB_OPEN_CREATE , FSL_DB_OPEN_SCHEMA_VALIDATE = 0x20 , FSL_DB_OPEN_TRACE_SQL = 0x40 } |
| Flags for use with fsl_db_open() and friends. More... | |
Functions | |
| FSL_EXPORT int | fsl_db_attach (fsl_db *db, const char *zDbName, const char *zLabel) |
| ATTACHes the file zDbName to db using the database name zLabel (which gets quoted as an SQL identifier). | |
| FSL_EXPORT int | fsl_db_changes_recent (fsl_db *db) |
| Returns the "number of database rows that were changed or inserted
or deleted by the most recently completed SQL statement" (to quote the underlying APIs). | |
| FSL_EXPORT int | fsl_db_changes_total (fsl_db *db) |
| Returns "the number of row changes caused by INSERT, UPDATE or
DELETE statements since the database connection was opened" (to quote the underlying APIs). | |
| FSL_EXPORT void | fsl_db_close (fsl_db *db) |
| Closes the given db handle and frees any resources owned by db. | |
| FSL_EXPORT int | fsl_db_detach (fsl_db *db, const char *zLabel) |
| The converse of fsl_db_detach(). | |
| FSL_EXPORT int | fsl_db_each (fsl_db *db, fsl_stmt_each_f callback, void *callbackState, char const *sql,...) |
| Expects sql to be a SELECT-style query which (potentially) returns a result set. | |
| FSL_EXPORT int | fsl_db_eachv (fsl_db *db, fsl_stmt_each_f callback, void *callbackState, char const *sql, va_list args) |
| va_list counterpart to fsl_db_each(). | |
| FSL_EXPORT int | fsl_db_err_get (fsl_db const *db, char const **msg, fsl_size_t *len) |
| Behaves like fsl_error_get(), using the db's underlying error state. | |
| FSL_EXPORT void | fsl_db_err_reset (fsl_db *db) |
| Resets any error state in db, but might keep the string memory allocated for later use. | |
| FSL_EXPORT void | fsl_db_event_listener (fsl_db *db, fsl_db_event_f f, void *pState, fsl_flag32_t mask) |
| Sets the on-transaction hook for the given db, overwriting any prior one. | |
| FSL_EXPORT int | fsl_db_exec (fsl_db *db, char const *sql,...) |
| Executes a single SQL statement, skipping over any results it may have. | |
| FSL_EXPORT int | fsl_db_exec_multi (fsl_db *db, const char *sql,...) |
| Executes multiple SQL statements, ignoring any results they might collect. | |
| FSL_EXPORT int | fsl_db_exec_multiv (fsl_db *db, const char *sql, va_list args) |
| va_list counterpart of db_exec_multi(). | |
| FSL_EXPORT int | fsl_db_execv (fsl_db *db, char const *sql, va_list args) |
| va_list counterpart of fs_db_exec(). | |
| FSL_EXPORT bool | fsl_db_exists (fsl_db *db, char const *sql,...) |
| Runs the given SQL query on the given db and returns true if the query returns any rows, else false. | |
| FSL_EXPORT bool | fsl_db_existsv (fsl_db *db, char const *sql, va_list args) |
| va_list counterpart of fsl_db_exists(). | |
| FSL_EXPORT char const * | fsl_db_filename (fsl_db const *db, fsl_size_t *len) |
| If db is not NULL then this function returns its name (the one used to fsl_db_open() it). | |
| FSL_EXPORT void * | fsl_db_g_blob (fsl_db *db, fsl_size_t *len, char const *sql,...) |
| Convenience form of fsl_db_get_blob() which returns the value directly but provides no way of checking for errors. | |
| FSL_EXPORT double | fsl_db_g_double (fsl_db *db, double defaultValue, char const *sql,...) |
| Convenience form of fsl_db_get_double() which returns the value directly but provides no way of checking for errors. | |
| FSL_EXPORT fsl_id_t | fsl_db_g_id (fsl_db *db, fsl_id_t defaultValue, char const *sql,...) |
| Convenience form of fsl_db_get_id() which returns the value directly but provides no way of checking for errors. | |
| FSL_EXPORT int32_t | fsl_db_g_int32 (fsl_db *db, int32_t defaultValue, char const *sql,...) |
| Convenience form of fsl_db_get_int32() which returns the value directly but provides no way of checking for errors. | |
| FSL_EXPORT int64_t | fsl_db_g_int64 (fsl_db *db, int64_t defaultValue, char const *sql,...) |
| Convenience form of fsl_db_get_int64() which returns the value directly but provides no way of checking for errors. | |
| FSL_EXPORT fsl_size_t | fsl_db_g_size (fsl_db *db, fsl_size_t defaultValue, char const *sql,...) |
| Convenience form of fsl_db_get_size() which returns the value directly but provides no way of checking for errors. | |
| FSL_EXPORT char * | fsl_db_g_text (fsl_db *db, fsl_size_t *len, char const *sql,...) |
| Convenience form of fsl_db_get_text() which returns the value directly but provides no way of checking for errors. | |
| FSL_EXPORT int | fsl_db_get_blob (fsl_db *db, void **rv, fsl_size_t *len, char const *sql,...) |
| The Blob counterpart of fsl_db_get_text(). | |
| FSL_EXPORT int | fsl_db_get_blobv (fsl_db *db, void **rv, fsl_size_t *stmtLen, char const *sql, va_list args) |
| va_list counterpart of fsl_db_get_blob(). | |
| FSL_EXPORT int | fsl_db_get_buffer (fsl_db *db, fsl_buffer *tgt, bool asBlob, char const *sql,...) |
| Similar to fsl_db_get_text() and fsl_db_get_blob(), but writes its result to tgt, appending its results to the given buffer. | |
| FSL_EXPORT int | fsl_db_get_bufferv (fsl_db *db, fsl_buffer *tgt, bool asBlob, char const *sql, va_list args) |
| va_list counterpart of fsl_db_get_buffer(). | |
| FSL_EXPORT int | fsl_db_get_double (fsl_db *db, double *rv, char const *sql,...) |
| The double counterpart of fsl_db_get_int32(). | |
| FSL_EXPORT int | fsl_db_get_doublev (fsl_db *db, double *rv, char const *sql, va_list args) |
| va_list counterpart of fsl_db_get_double(). | |
| FSL_EXPORT int | fsl_db_get_id (fsl_db *db, fsl_id_t *rv, char const *sql,...) |
| The fsl_id_t counterpart of fsl_db_get_int32(). | |
| FSL_EXPORT int | fsl_db_get_idv (fsl_db *db, fsl_id_t *rv, char const *sql, va_list args) |
| va_list counterpart of fsl_db_get_id(). | |
| FSL_EXPORT int | fsl_db_get_int32 (fsl_db *db, int32_t *rv, char const *sql,...) |
| Runs a fetch-style SQL query against DB and returns the first column of the first result row via *rv. | |
| FSL_EXPORT int | fsl_db_get_int32v (fsl_db *db, int32_t *rv, char const *sql, va_list args) |
| va_list counterpart of fsl_db_get_int32(). | |
| FSL_EXPORT int | fsl_db_get_int64 (fsl_db *db, int64_t *rv, char const *sql,...) |
| The int64 counterpart of fsl_db_get_int32(). | |
| FSL_EXPORT int | fsl_db_get_int64v (fsl_db *db, int64_t *rv, char const *sql, va_list args) |
| va_list counterpart of fsl_db_get_int64(). | |
| FSL_EXPORT int | fsl_db_get_size (fsl_db *db, fsl_size_t *rv, char const *sql,...) |
| The fsl_size_t counterpart of fsl_db_get_int32(). | |
| FSL_EXPORT int | fsl_db_get_sizev (fsl_db *db, fsl_size_t *rv, char const *sql, va_list args) |
| va_list counterpart of fsl_db_get_size(). | |
| FSL_EXPORT int | fsl_db_get_text (fsl_db *db, char **rv, fsl_size_t *rvLen, char const *sql,...) |
| The C-string counterpart of fsl_db_get_int32(). | |
| FSL_EXPORT int | fsl_db_get_textv (fsl_db *db, char **rv, fsl_size_t *rvLen, char const *sql, va_list args) |
| va_list counterpart of fsl_db_get_text(). | |
| FSL_EXPORT int | fsl_db_init (fsl_error *err, char const *zFilename, char const *zSchema,...) |
| Initializes the given database file. | |
| FSL_EXPORT bool | fsl_db_is_writeable (fsl_db *db, char const *zSchema) |
| Returns true if db is opened and sqlite3_db_readonly() returns 0 for it, else returns false. | |
| FSL_EXPORT double | fsl_db_julian_now (fsl_db *db) |
| Returns the current time in Julian Date format. | |
| FSL_EXPORT char * | fsl_db_julian_to_iso8601 (fsl_db *db, double j, bool msPrecision, bool localTime) |
| Returns the given Julian date value formatted as an ISO8601 string (with a fractional seconds part if msPrecision is true, else without it). | |
| FSL_EXPORT fsl_id_t | fsl_db_last_insert_id (fsl_db *db) |
| Returns the row ID of the most recent insertion, or -1 if !db, db is not connected, or 0 if no inserts have been performed. | |
| FSL_EXPORT fsl_db * | fsl_db_malloc (void) |
| Allocates a new fsl_db instance(). | |
| FSL_EXPORT char const * | fsl_db_name (fsl_db const *db) |
| If a db name has been associated with db then it is returned, otherwise NULL is returned. | |
| FSL_EXPORT int | fsl_db_open (fsl_db *db, char const *dbFile, fsl_flag32_t openFlags) |
| Opens the given db file and populates db with its handle. | |
| FSL_EXPORT int | fsl_db_prepare (fsl_db *db, fsl_stmt *tgt, char const *sql,...) |
| Prepares an SQL statement for execution. | |
| FSL_EXPORT int | fsl_db_prepare_cached (fsl_db *db, fsl_stmt **st, char const *sql,...) |
| A special-purpose variant of fsl_db_prepare() which caches statements based on their SQL code. | |
| FSL_EXPORT int | fsl_db_preparev (fsl_db *db, fsl_stmt *tgt, char const *sql, va_list args) |
| va_list counterpart of fsl_db_prepare(). | |
| FSL_EXPORT int | fsl_db_preparev_cached (fsl_db *db, fsl_stmt **st, char const *sql, va_list args) |
| The va_list counterpart of fsl_db_prepare_cached(). | |
| FSL_EXPORT char * | fsl_db_random_hex (fsl_db *db, fsl_size_t n) |
| Returns n bytes of random lower-case hexidecimal characters using the given db as its data source, plus a terminating NUL byte. | |
| FSL_EXPORT const char * | fsl_db_role_name (enum fsl_dbrole_e r) |
| Returns a db name string for the given fsl_db_role value. | |
| FSL_EXPORT int | fsl_db_select_slist (fsl_db *db, fsl_list *tgt, char const *fmt,...) |
| Expects fmt to be a SELECT-style query. | |
| FSL_EXPORT int | fsl_db_select_slistv (fsl_db *db, fsl_list *tgt, char const *fmt, va_list args) |
| The va_list counterpart of fsl_db_select_slist(). | |
| FSL_EXPORT void | fsl_db_sqltrace_enable (fsl_db *db, FILE *outStream, bool expandSql) |
| If db is an opened db handle, this registers a debugging function with the db which traces all SQL to the given FILE handle. | |
| FSL_EXPORT double | fsl_db_string_to_julian (fsl_db *db, char const *str) |
| Uses the given db to convert the given time string to Julian Day format. | |
| FSL_EXPORT bool | fsl_db_table_exists (fsl_db *db, fsl_dbrole_e whichDb, const char *zTable) |
| Returns true if the table name specified by the final argument exists in the fossil database specified by the 2nd argument on the db connection specified by the first argument, else returns false. | |
| FSL_EXPORT bool | fsl_db_table_has_column (fsl_db *db, char const *zTableName, char const *zColName) |
| Returns non-0 (true) if the database (which must be open) table identified by zTableName has a column named zColName (case-sensitive), else returns 0. | |
| FSL_EXPORT int | fsl_db_txn_begin (fsl_db *db) |
| Begins a transaction on the given db. | |
| FSL_EXPORT int | fsl_db_txn_commit (fsl_db *db) |
| Equivalent to fsl_db_txn_end_v2(db, true, false). | |
| FSL_EXPORT int | fsl_db_txn_end_v2 (fsl_db *db, bool keepSavepoint, bool bubbleRollback) |
| Decrements the transaction counter incremented by fsl_db_txn_begin() and commits or rolls back the savepoint if the counter goes to 0. | |
| FSL_EXPORT int | fsl_db_txn_level (fsl_db *db) |
| Returns the given db's current transaction depth. | |
| FSL_EXPORT int | fsl_db_txn_rollback (fsl_db *db) |
| Equivalent to fsl_db_txn_end_v2(db, false, true), noting that the final value of true there is for historical API compatibility and will be changed to false if we can get away with it elsewhere. | |
| FSL_EXPORT char * | fsl_db_unix_to_iso8601 (fsl_db *db, fsl_time_t j, bool localTime) |
| Returns the given Julian date value formatted as an ISO8601 string (with a fractional seconds part if msPrecision is true, else without it). | |
| FSL_EXPORT int | fsl_stmt_bind_blob (fsl_stmt *stmt, int index, void const *v, fsl_size_t len, bool makeCopy) |
| Binds the first n bytes of v as a blob to the given 1-based bound parameter column in the given statement. | |
| FSL_EXPORT int | fsl_stmt_bind_blob_name (fsl_stmt *stmt, char const *param, void const *v, fsl_int_t len, bool makeCopy) |
| Equivalent to fsl_stmt_bind_blob() but binds to a named parameter. | |
| FSL_EXPORT int | fsl_stmt_bind_double (fsl_stmt *stmt, int index, double v) |
| Binds v to the given 1-based parameter index. | |
| FSL_EXPORT int | fsl_stmt_bind_double_name (fsl_stmt *stmt, char const *param, double v) |
| Equivalent to fsl_stmt_bind_double() but binds to a named parameter. | |
| FSL_EXPORT int | fsl_stmt_bind_fmt (fsl_stmt *st, char const *fmt,...) |
| The elipsis counterpart of fsl_stmt_bind_fmtv(). | |
| FSL_EXPORT int | fsl_stmt_bind_fmtv (fsl_stmt *st, char const *fmt, va_list args) |
| Binds a series of values using a formatting string. | |
| FSL_EXPORT int | fsl_stmt_bind_id (fsl_stmt *stmt, int index, fsl_id_t v) |
| Binds v to the given 1-based parameter index. | |
| FSL_EXPORT int | fsl_stmt_bind_id_name (fsl_stmt *stmt, char const *param, fsl_id_t v) |
| Equivalent to fsl_stmt_bind_id() but binds to a named parameter. | |
| FSL_EXPORT int | fsl_stmt_bind_int32 (fsl_stmt *stmt, int index, int32_t v) |
| Binds v to the given 1-based parameter index. | |
| FSL_EXPORT int | fsl_stmt_bind_int32_name (fsl_stmt *stmt, char const *param, int32_t v) |
| Equivalent to fsl_stmt_bind_int32() but binds to a named parameter. | |
| FSL_EXPORT int | fsl_stmt_bind_int64 (fsl_stmt *stmt, int index, int64_t v) |
| Binds v to the given 1-based parameter index. | |
| FSL_EXPORT int | fsl_stmt_bind_int64_name (fsl_stmt *stmt, char const *param, int64_t v) |
| Equivalent to fsl_stmt_bind_int64() but binds to a named parameter. | |
| FSL_EXPORT int | fsl_stmt_bind_null (fsl_stmt *stmt, int index) |
| Binds NULL to the given 1-based parameter index. | |
| FSL_EXPORT int | fsl_stmt_bind_null_name (fsl_stmt *stmt, char const *param) |
| Equivalent to fsl_stmt_bind_null_name() but binds to a named parameter. | |
| FSL_EXPORT int | fsl_stmt_bind_step (fsl_stmt *st, char const *fmt,...) |
| The elipsis counterpart of fsl_stmt_bind_step(). | |
| FSL_EXPORT int | fsl_stmt_bind_step_v2 (fsl_stmt *st, char const *fmt,...) |
| The elipsis counterpart of fsl_stmt_bind_step_v2(). | |
| FSL_EXPORT int | fsl_stmt_bind_stepv (fsl_stmt *st, char const *fmt, va_list args) |
| Works exactly like fsl_stmt_bind_stepv_v2() except that it returns 0 if stepping results in FSL_RC_STEP_DONE. | |
| FSL_EXPORT int | fsl_stmt_bind_stepv_v2 (fsl_stmt *st, char const *fmt, va_list args) |
| Works like fsl_stmt_bind_fmt() but: | |
| FSL_EXPORT int | fsl_stmt_bind_text (fsl_stmt *stmt, int index, char const *v, fsl_int_t n, bool makeCopy) |
| Binds the first n bytes of v as text to the given 1-based bound parameter column in the given statement. | |
| FSL_EXPORT int | fsl_stmt_bind_text_name (fsl_stmt *stmt, char const *param, char const *v, fsl_int_t n, bool makeCopy) |
| Equivalent to fsl_stmt_bind_text() but binds to a named parameter. | |
| FSL_EXPORT int | fsl_stmt_cached_yield (fsl_stmt *st) |
| "Yields" a statement which was prepared with fsl_db_prepare_cached(), such that that routine can once again use/re-issue that statement. | |
| FSL_EXPORT void | fsl_stmt_clear_bindings (fsl_stmt *stmt) |
| Clears memory associtated with any bindings on this statement. | |
| FSL_EXPORT int | fsl_stmt_col_count (fsl_stmt const *stmt) |
| Returns the result column count for the given statement, or -1 if !stmt or it has not been prepared. | |
| FSL_EXPORT char const * | fsl_stmt_col_name (fsl_stmt *stmt, int index) |
| Returns the name of the given 0-based result column index, or NULL if !stmt, stmt is not prepared, or index is out out of range. | |
| FSL_EXPORT fsl_db * | fsl_stmt_db (fsl_stmt *stmt) |
| Returns the db handle which prepared the given statement, or NULL if stmt has not been prepared. | |
| FSL_EXPORT int | fsl_stmt_each (fsl_stmt *stmt, fsl_stmt_each_f callback, void *callbackState) |
| Calls the given callback one time for each result row in the given statement, iterating over stmt using fsl_stmt_step(). | |
| FSL_EXPORT int | fsl_stmt_each_f_dump (fsl_stmt *stmt, void *state) |
| A fsl_stmt_each_f() impl, intended primarily for debugging, which simply outputs row data in tabular form via fsl_output(). | |
| FSL_EXPORT int | fsl_stmt_finalize (fsl_stmt *stmt) |
| Frees memory associated with stmt but does not free stmt unless it was allocated by fsl_stmt_malloc() (these objects are normally stack-allocated, and such object must be initialized by copying fsl_stmt_empty so that this function knows whether or not to fsl_free() them). | |
| FSL_EXPORT double | fsl_stmt_g_double (fsl_stmt *stmt, int index) |
| Convenience form of fsl_stmt_get_double() which returns the value directly but cannot report errors. | |
| FSL_EXPORT fsl_id_t | fsl_stmt_g_id (fsl_stmt *stmt, int index) |
| Convenience form of fsl_stmt_get_id() which returns the value directly but cannot report errors. | |
| FSL_EXPORT int32_t | fsl_stmt_g_int32 (fsl_stmt *stmt, int index) |
| Convenience form of fsl_stmt_get_int32() which returns the value directly but cannot report errors. | |
| FSL_EXPORT int64_t | fsl_stmt_g_int64 (fsl_stmt *stmt, int index) |
| Convenience form of fsl_stmt_get_int64() which returns the value directly but cannot report errors. | |
| FSL_EXPORT char const * | fsl_stmt_g_text (fsl_stmt *stmt, int index, fsl_size_t *outLen) |
| Convenience form of fsl_stmt_get_text() which returns the value directly but cannot report errors. | |
| FSL_EXPORT int | fsl_stmt_get_blob (fsl_stmt *stmt, int index, void const **out, fsl_size_t *outLen) |
| The Blob counterpart of fsl_stmt_get_text(). | |
| FSL_EXPORT int | fsl_stmt_get_double (fsl_stmt *stmt, int index, double *v) |
| Gets double value from the given 0-based result set column, assigns *v to that value, and returns 0 on success. | |
| FSL_EXPORT int | fsl_stmt_get_id (fsl_stmt *stmt, int index, fsl_id_t *v) |
| The fsl_id_t counterpart of fsl_stmt_get_int32(). | |
| FSL_EXPORT int | fsl_stmt_get_int32 (fsl_stmt *stmt, int index, int32_t *v) |
| Gets an integer value from the given 0-based result set column, assigns *v to that value, and returns 0 on success. | |
| FSL_EXPORT int | fsl_stmt_get_int64 (fsl_stmt *stmt, int index, int64_t *v) |
| Gets an integer value from the given 0-based result set column, assigns *v to that value, and returns 0 on success. | |
| FSL_EXPORT int | fsl_stmt_get_text (fsl_stmt *stmt, int index, char const **out, fsl_size_t *outLen) |
| Gets a string value from the given 0-based result set column, assigns *out (if out is not NULL) to that value, assigns *outLen (if outLen is not NULL) to *out's length in bytes, and returns 0 on success. | |
| FSL_EXPORT fsl_stmt * | fsl_stmt_malloc (void) |
| Allocates a new, cleanly-initialized fsl_stmt instance using fsl_malloc(). | |
| FSL_EXPORT int | fsl_stmt_param_count (fsl_stmt const *stmt) |
| Returns the bound parameter count for the given statement, or -1 if !stmt or it has not been prepared. | |
| FSL_EXPORT int | fsl_stmt_param_index (fsl_stmt *stmt, char const *param) |
| Returns the index of the given named parameter for the given statement, or -1 if !stmt or stmt is not prepared. | |
| FSL_EXPORT int | fsl_stmt_reset (fsl_stmt *stmt) |
| Equivalent to fsl_stmt_reset2(stmt, false). | |
| FSL_EXPORT int | fsl_stmt_reset2 (fsl_stmt *stmt, bool resetRowCounter) |
| Resets the given statement, analog to sqlite3_reset(). | |
| FSL_EXPORT char const * | fsl_stmt_sql (fsl_stmt *stmt, fsl_size_t *len) |
| Returns the SQL string used to prepare the given statement, or NULL if stmt has not been prepared. | |
| FSL_EXPORT int | fsl_stmt_step (fsl_stmt *stmt) |
| "Steps" the given SQL cursor one time. | |
Variables | |
| FSL_EXPORT const fsl_db | fsl_db_empty |
| Empty-initialized fsl_db structure, intended for copy initialization. | |
| FSL_EXPORT const fsl_stmt | fsl_stmt_empty |
| Empty-initialized fsl_stmt instance, intended for copy-constructing. | |
| #define fsl_db_empty_m |
Empty-initialized fsl_db structure, intended for const-copy initialization.
| #define fsl_db_event_map | ( | E | ) |
A map of fsl_db_event types.
| #define fsl_db_txn_end | ( | DB, | |
| DOROLLBACK ) |
Equivalent to fsl_db_txn_end_v2(DB, !DOROLLBACK, !
!DOROLLBACK), which mimics the historical behavior of this API.
| #define fsl_stmt_empty_m |
Empty-initialized fsl_stmt instance, intended for use as an in-struct initializer.
| typedef enum fsl_db_event_e fsl_db_event_e |
| typedef int(* fsl_db_event_f) (fsl_db_event const *e) |
An event callback for fsl_db objects, primarily for communicating on-transaction-start/end.
Each fsl_db instance may have a single one of these installed and it gets called via at various points to fire well-defined events.
When the docs below refer to BEGIN and COMMIT, they're actually referring to their SAVEPOINT counterparts. That's partly historical, from a time when this API uses BEGIN/COMMIT, but it's also thought to be clearer terminology here.
Doc references below to fsl_db_txn_begin() and fsl_db_txn_end() also imply their v2 variants.
ev->state holds the state registered with the callback in fsl_db_event_listener().
ev->type explains the nature of the event:
To summarize, priority of determining which error code to return from fsl_db_txn_end(), in combination with the potential for errors when submitting the resulting SQL to commit/roll back, are:
This hook is NOT called for IMPLICIT transactions. It is only called for explicit calls to fsl_db_txn_begin(), fsl_db_txn_end(), and fsl_db_rollback_force(). Clients must never execute SQL-level (BEGIN, COMMIT, ROLLBACK, SAVEPOINT) calls on fsl_db instances or they risk getting it out of sync. There are exceptions where they're safe but, generically speaking, they're not.
| typedef sqlite3 fsl_db_t |
A level of indirection to "hide" the actual db driver implementation from the public API.
It uses SQLite3 but this gives us a comforting level of abstraction.
Sidebar: at the time this code was originally written, sqlite4 was in an experimental stage to explore a new storage engine which, it was hoped, would speed up sqlite considerably. It ended up never leaving that stage because the performance gains of the storage engine did not justify such a significant upheaval. Even so, sqlite4 "might" come around sometime within the lifetime of this project, so it behooves us to abstract away this type from the public API.
| typedef int(* fsl_stmt_each_f) (fsl_stmt *stmt, void *state) |
A callback interface for use with fsl_stmt_each() and fsl_db_each().
It will be called one time for each row fetched, passed the statement object and the state parameter passed to fsl_stmt_each() resp. fsl_db_each(). If it returns non-0 then iteration stops and that code is returned UNLESS it returns FSL_RC_BREAK, in which case fsl_stmt_each() stops iteration and returns 0. i.e. implementations may return FSL_RC_BREAK to prematurly end iteration without causing an error.
This callback is not called for non-fetching queries or queries which return no results, though it might (or might not) be interesting for it to do so, passing a NULL stmt for that case.
stmt->rowCount can be used to determine how many times the statement has called this function. Its counting starts at 1.
It is strictly illegal for a callback to pass stmt to fsl_stmt_step(), fsl_stmt_reset(), fsl_stmt_finalize(), or any similar routine which modifies its state. It must only read the current column data (or similar metatdata, e.g. column names) from the statement, e.g. using fsl_stmt_g_int32(), fsl_stmt_get_text(), or similar.
| typedef sqlite3_stmt fsl_stmt_t |
| enum fsl_db_event_e |
A flag type for use with fsl_db_event_f() implementations.
| Enumerator | |
|---|---|
| fsl_db_event_map | |
| enum fsl_db_event_mask2_e |
Convenience FSL_DB_EVENT_... entries which cannot be defined until after fsl_db_event_e is.
| Enumerator | |
|---|---|
| FSL_DB_EVENT_group_txn | Mask of the IDs of transaction-specific events. |
| FSL_DB_EVENT_group_sql_trace | Mask of the IDs of SQL tracing events. |
| enum fsl_db_event_mask_e |
Bitmasks for use with fsl_db_event_e.
| Enumerator | |
|---|---|
| FSL_DB_EVENT_mask_reserved | |
| FSL_DB_EVENT_mask_payload | Describes a data type for fsl_db_event::payload. |
| FSL_DB_EVENT_payload_buffer | (fsl_buffer const *) payload. |
| FSL_DB_EVENT_mask_id | All concrete message IDs are masked with this. |
| FSL_DB_EVENT_listen_all | Convenience entry for use with fsl_db_event_listener(). |
| enum fsl_db_open_flags_e |
Flags for use with fsl_db_open() and friends.
| Enumerator | |
|---|---|
| FSL_DB_OPEN_NONE | The "no flags" value. |
| FSL_DB_OPEN_RO | Flag for fsl_db_open() specifying that the db should be opened in read-only mode. |
| FSL_DB_OPEN_RW | Flag for fsl_db_open() specifying that the db should be opened in read-write mode, but should not create the db if it does not already exist. |
| FSL_DB_OPEN_CREATE | Flag for fsl_db_open() specifying that the db should be opened in read-write mode, creating the db if it does not already exist. ACHTUNG: this flag propagates from an OPEN'd db handle to the ATTACH SQL command run via that handle, such that ATTACHing a non-existing db file will fail if the FSL_DB_OPEN_CREATE flag is not used. Historically (prior to 2022-01-01), fsl_db_open() would automatically apply this flag to DBs named ":memory:" or "" (unnamed temp dbs), but that ended up causing a full day of confusion, hair-pulling, and bug-hunting when lib-level code was migrated from an anonymous temp db to a "real" db and ATTACH suddenly failed. As of 2022-01-01, fsl_db_open() always takes the open-mode flags as provided by the client, regardless of the DB name, and never automatically rewrites them to include FSL_DB_OPEN_CREATE. |
| FSL_DB_OPEN_RWC | Shorthand for RW+CREATE flags. |
| FSL_DB_OPEN_SCHEMA_VALIDATE | Currently unused. It "should" be used to tell fsl_repo_open_xxx() to confirm that the db is a repository, but how to propagate that through the corresponding APIs is not currently clear. |
| FSL_DB_OPEN_TRACE_SQL | Used by fsl_db_open() to to tell the underlying db connection to trace all SQL to stdout. This is often useful for testing, debugging, and learning about what's going on behind the scenes. |
| FSL_EXPORT int fsl_db_attach | ( | fsl_db * | db, |
| const char * | zDbName, | ||
| const char * | zLabel ) |
ATTACHes the file zDbName to db using the database name zLabel (which gets quoted as an SQL identifier).
Returns 0 on success. Returns FSL_RC_MISUSE if any argument is NULL or any string argument starts with a NUL byte, else it returns the result of fsl_db_exec() which attaches the db. On db-level errors db's error state will be updated.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_changes_recent | ( | fsl_db * | db | ) |
Returns the "number of database rows that were changed or inserted or deleted by the most recently completed SQL statement" (to quote the underlying APIs).
Returns 0 if db is not opened.
See: https://sqlite.org/c3ref/changes.html
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_changes_total | ( | fsl_db * | db | ) |
Returns "the number of row changes caused by INSERT, UPDATE or DELETE statements since the database connection was opened" (to quote the underlying APIs).
Returns 0 if db is not opened.
See; https://sqlite.org/c3ref/total_changes.html
References FSL_EXPORT.
| FSL_EXPORT void fsl_db_close | ( | fsl_db * | db | ) |
Closes the given db handle and frees any resources owned by db.
This function is a no-op if db is NULL.
If db was allocated using fsl_db_malloc() (as determined by examining db->allocStamp) then this routine also fsl_free()s it, otherwise it is assumed to either be on the stack or part of a larger struct and is not freed, but any resources it allocated are freed.
If db has any pending transactions, they are rolled back by this function before a FSL_DB_EVENT_CLOSING event is fired.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_detach | ( | fsl_db * | db, |
| const char * | zLabel ) |
The converse of fsl_db_detach().
Must be passed the same arguments which were passed as the 1st and 3rd arguments to fsl_db_attach(). Returns 0 on success, FSL_RC_MISUSE if !db, !zLabel, or !*zLabel, else it returns the result of the underlying fsl_db_exec() call.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_each | ( | fsl_db * | db, |
| fsl_stmt_each_f | callback, | ||
| void * | callbackState, | ||
| char const * | sql, | ||
| ... ) |
Expects sql to be a SELECT-style query which (potentially) returns a result set.
For each row in the set callback() is called, as described for fsl_stmt_each(). Returns 0 on success. The callback is not called for queries which return no rows. If clients need to know if rows were returned, they can add a counter to their callbackState and increment it from the callback.
Returns FSL_RC_MISUSE if db is not opened, !callback, !sql. Returns FSL_RC_RANGE if !*sql.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_eachv | ( | fsl_db * | db, |
| fsl_stmt_each_f | callback, | ||
| void * | callbackState, | ||
| char const * | sql, | ||
| va_list | args ) |
va_list counterpart to fsl_db_each().
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_err_get | ( | fsl_db const * | db, |
| char const ** | msg, | ||
| fsl_size_t * | len ) |
Behaves like fsl_error_get(), using the db's underlying error state.
Results are undefined if !db.
References FSL_EXPORT.
| FSL_EXPORT void fsl_db_err_reset | ( | fsl_db * | db | ) |
Resets any error state in db, but might keep the string memory allocated for later use.
References FSL_EXPORT.
| FSL_EXPORT void fsl_db_event_listener | ( | fsl_db * | db, |
| fsl_db_event_f | f, | ||
| void * | pState, | ||
| fsl_flag32_t | mask ) |
Sets the on-transaction hook for the given db, overwriting any prior one.
To clear the hook, pass NULL for the 2nd and 3rd arguments.
The final argument specifies what events type to look for. It may be an OR of any FSL_DB_EVENT_... events. Use FSL_DB_EVENT_listen_all to listen to all events. The stored mask is bitwise ANDed against FSL_DB_EVENT_mask_id, so only the concrete message IDs are recorded here.
Achtung: fsl_cx instances install this hook on database handles they manage, so never call this on such a handle.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_exec | ( | fsl_db * | db, |
| char const * | sql, | ||
| ... ) |
Executes a single SQL statement, skipping over any results it may have.
Returns 0 on success. On error db's error state may be updated. Note that this function translates FSL_RC_STEP_DONE and FSL_RC_STEP_ROW to 0. For cases where those particular result codes are significant, use fsl_db_prepare() and fsl_stmt_step() (for which this function is just a proxy).
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_exec_multi | ( | fsl_db * | db, |
| const char * | sql, | ||
| ... ) |
Executes multiple SQL statements, ignoring any results they might collect.
Returns 0 on success, non-0 on error. On error db->error might be updated to report the problem.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_exec_multiv | ( | fsl_db * | db, |
| const char * | sql, | ||
| va_list | args ) |
va_list counterpart of db_exec_multi().
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_execv | ( | fsl_db * | db, |
| char const * | sql, | ||
| va_list | args ) |
va_list counterpart of fs_db_exec().
References FSL_EXPORT.
| FSL_EXPORT bool fsl_db_exists | ( | fsl_db * | db, |
| char const * | sql, | ||
| ... ) |
Runs the given SQL query on the given db and returns true if the query returns any rows, else false.
Returns 0 for any error as well.
References FSL_EXPORT.
| FSL_EXPORT bool fsl_db_existsv | ( | fsl_db * | db, |
| char const * | sql, | ||
| va_list | args ) |
va_list counterpart of fsl_db_exists().
References FSL_EXPORT.
| FSL_EXPORT char const * fsl_db_filename | ( | fsl_db const * | db, |
| fsl_size_t * | len ) |
If db is not NULL then this function returns its name (the one used to fsl_db_open() it).
The bytes are valid until the db connection is closed or until someone mucks with db->filename. If len is not NULL then *len is (on success) assigned to the length of the returned string, in bytes. The string is NUL-terminated, so fetching the length (by passing a non-NULL 2nd parameter) is optional but sometimes useful to eliminate a downstream call to fsl_strlen().
Results are undefined if db is NULL or was improperly initialized. Will return NULL if db was properly initialized (via copying fsl_db_empty) but has not yet been opened.
References FSL_EXPORT.
| FSL_EXPORT void * fsl_db_g_blob | ( | fsl_db * | db, |
| fsl_size_t * | len, | ||
| char const * | sql, | ||
| ... ) |
Convenience form of fsl_db_get_blob() which returns the value directly but provides no way of checking for errors.
On error, or if no result is found, NULL is returned.
References FSL_EXPORT.
| FSL_EXPORT double fsl_db_g_double | ( | fsl_db * | db, |
| double | defaultValue, | ||
| char const * | sql, | ||
| ... ) |
Convenience form of fsl_db_get_double() which returns the value directly but provides no way of checking for errors.
On error, or if no result is found, defaultValue is returned.
References FSL_EXPORT.
| FSL_EXPORT fsl_id_t fsl_db_g_id | ( | fsl_db * | db, |
| fsl_id_t | defaultValue, | ||
| char const * | sql, | ||
| ... ) |
Convenience form of fsl_db_get_id() which returns the value directly but provides no way of checking for errors.
On error, or if no result is found, defaultValue is returned.
References FSL_EXPORT.
| FSL_EXPORT int32_t fsl_db_g_int32 | ( | fsl_db * | db, |
| int32_t | defaultValue, | ||
| char const * | sql, | ||
| ... ) |
Convenience form of fsl_db_get_int32() which returns the value directly but provides no way of checking for errors.
On error, or if no result is found, defaultValue is returned.
References FSL_EXPORT.
| FSL_EXPORT int64_t fsl_db_g_int64 | ( | fsl_db * | db, |
| int64_t | defaultValue, | ||
| char const * | sql, | ||
| ... ) |
Convenience form of fsl_db_get_int64() which returns the value directly but provides no way of checking for errors.
On error, or if no result is found, defaultValue is returned.
References FSL_EXPORT.
| FSL_EXPORT fsl_size_t fsl_db_g_size | ( | fsl_db * | db, |
| fsl_size_t | defaultValue, | ||
| char const * | sql, | ||
| ... ) |
Convenience form of fsl_db_get_size() which returns the value directly but provides no way of checking for errors.
On error, or if no result is found, defaultValue is returned.
References FSL_EXPORT.
| FSL_EXPORT char * fsl_db_g_text | ( | fsl_db * | db, |
| fsl_size_t * | len, | ||
| char const * | sql, | ||
| ... ) |
Convenience form of fsl_db_get_text() which returns the value directly but provides no way of checking for errors.
On error, or if no result is found, NULL is returned. The returned string must eventually be passed to fsl_free() to free it. If len is not NULL then if non-NULL is returned, *len will be assigned the byte-length of the returned string.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_blob | ( | fsl_db * | db, |
| void ** | rv, | ||
| fsl_size_t * | len, | ||
| char const * | sql, | ||
| ... ) |
The Blob counterpart of fsl_db_get_text().
Identical to that function except that its output result (2nd paramter) type differs, and it fetches the data as a raw blob, without any sort of string interpretation. The returned *rv memory must eventually be passed to fsl_free() to free it. If len is not NULL then on success *len will be set to the byte length of the returned blob. If no row is found, *rv is set to NULL and *rvLen (if not NULL) is set to 0, and 0 is returned. Note that NULL is also a legal result (an SQL NULL translates as a NULL string),
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_blobv | ( | fsl_db * | db, |
| void ** | rv, | ||
| fsl_size_t * | stmtLen, | ||
| char const * | sql, | ||
| va_list | args ) |
va_list counterpart of fsl_db_get_blob().
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_buffer | ( | fsl_db * | db, |
| fsl_buffer * | tgt, | ||
| bool | asBlob, | ||
| char const * | sql, | ||
| ... ) |
Similar to fsl_db_get_text() and fsl_db_get_blob(), but writes its result to tgt, appending its results to the given buffer.
If asBlob is true then the underlying BLOB API is used to populate the buffer, else the underlying STRING/TEXT API is used. For many purposes there will be no difference, but if you know you might have binary data, be sure to pass a true value for asBlob to avoid any potential encoding-related problems.
Results are undefined if any pointer argument is NULL. Returns FSL_RC_MISUSE if the SQL is an empty string.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_bufferv | ( | fsl_db * | db, |
| fsl_buffer * | tgt, | ||
| bool | asBlob, | ||
| char const * | sql, | ||
| va_list | args ) |
va_list counterpart of fsl_db_get_buffer().
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_double | ( | fsl_db * | db, |
| double * | rv, | ||
| char const * | sql, | ||
| ... ) |
The double counterpart of fsl_db_get_int32().
See that function for the semantics.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_doublev | ( | fsl_db * | db, |
| double * | rv, | ||
| char const * | sql, | ||
| va_list | args ) |
va_list counterpart of fsl_db_get_double().
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_id | ( | fsl_db * | db, |
| fsl_id_t * | rv, | ||
| char const * | sql, | ||
| ... ) |
The fsl_id_t counterpart of fsl_db_get_int32().
See that function for the semantics.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_idv | ( | fsl_db * | db, |
| fsl_id_t * | rv, | ||
| char const * | sql, | ||
| va_list | args ) |
va_list counterpart of fsl_db_get_id().
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_int32 | ( | fsl_db * | db, |
| int32_t * | rv, | ||
| char const * | sql, | ||
| ... ) |
Runs a fetch-style SQL query against DB and returns the first column of the first result row via *rv.
If the query returns no rows, *rv is not modified. The intention is that the caller sets rv to his preferred default (or sentinel) value before calling this.
The format string (the sql parameter) accepts all formatting options supported by fsl_appendf().
Returns 0 on success. On error db's error state is updated and rv is not modified.
Returns FSL_RC_MISUSE without side effects if !db, !rv, !sql, or !*sql.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_int32v | ( | fsl_db * | db, |
| int32_t * | rv, | ||
| char const * | sql, | ||
| va_list | args ) |
va_list counterpart of fsl_db_get_int32().
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_int64 | ( | fsl_db * | db, |
| int64_t * | rv, | ||
| char const * | sql, | ||
| ... ) |
The int64 counterpart of fsl_db_get_int32().
See that function for the semantics.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_int64v | ( | fsl_db * | db, |
| int64_t * | rv, | ||
| char const * | sql, | ||
| va_list | args ) |
va_list counterpart of fsl_db_get_int64().
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_size | ( | fsl_db * | db, |
| fsl_size_t * | rv, | ||
| char const * | sql, | ||
| ... ) |
The fsl_size_t counterpart of fsl_db_get_int32().
See that function for the semantics. If this function would fetch a negative value, it returns FSL_RC_RANGE and *rv is not modified.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_sizev | ( | fsl_db * | db, |
| fsl_size_t * | rv, | ||
| char const * | sql, | ||
| va_list | args ) |
va_list counterpart of fsl_db_get_size().
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_text | ( | fsl_db * | db, |
| char ** | rv, | ||
| fsl_size_t * | rvLen, | ||
| char const * | sql, | ||
| ... ) |
The C-string counterpart of fsl_db_get_int32().
On success *rv will be set to a dynamically allocated string copied from the first column of the first result row. If rvLen is not NULL then rvLen will be assigned the byte-length of that string. If no row is found, *rv is set to NULL and *rvLen (if not NULL) is set to 0, and 0 is returned. Note that NULL is also a legal result (an SQL NULL translates as a NULL string), The caller must eventually free the returned string value using fsl_free().
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_get_textv | ( | fsl_db * | db, |
| char ** | rv, | ||
| fsl_size_t * | rvLen, | ||
| char const * | sql, | ||
| va_list | args ) |
va_list counterpart of fsl_db_get_text().
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_init | ( | fsl_error * | err, |
| char const * | zFilename, | ||
| char const * | zSchema, | ||
| ... ) |
Initializes the given database file.
zFilename is the name of the db file. It is created if needed, but any directory components are not created. zSchema is the base schema to install. The following arguments may be (char const *) SQL code, each of which gets run against the db after the main schema is called. The variadic argument list MUST end with NULL (0), even if there are no non-NULL entries.
Returns 0 on success.
On error, if err is not NULL then it is populated with any error state from the underlying (temporary) db handle.
References FSL_EXPORT.
| FSL_EXPORT bool fsl_db_is_writeable | ( | fsl_db * | db, |
| char const * | zSchema ) |
Returns true if db is opened and sqlite3_db_readonly() returns 0 for it, else returns false.
If zSchema is NULL then "main" is assumed.
References FSL_EXPORT.
| FSL_EXPORT double fsl_db_julian_now | ( | fsl_db * | db | ) |
Returns the current time in Julian Date format.
Returns a negative value if !db or db is not opened.
References FSL_EXPORT.
| FSL_EXPORT char * fsl_db_julian_to_iso8601 | ( | fsl_db * | db, |
| double | j, | ||
| bool | msPrecision, | ||
| bool | localTime ) |
Returns the given Julian date value formatted as an ISO8601 string (with a fractional seconds part if msPrecision is true, else without it).
Returns NULL if !db, db is not connected, j is less than 0, or on allocation error. The returned memory must eventually be freed using fsl_free().
If localTime is true then the value is converted to the local time, otherwise it is not.
References FSL_EXPORT.
| FSL_EXPORT fsl_id_t fsl_db_last_insert_id | ( | fsl_db * | db | ) |
Returns the row ID of the most recent insertion, or -1 if !db, db is not connected, or 0 if no inserts have been performed.
References FSL_EXPORT.
| FSL_EXPORT fsl_db * fsl_db_malloc | ( | void | ) |
Allocates a new fsl_db instance().
Returns NULL on allocation error. Note that fsl_db instances can often be used from the stack - allocating them dynamically is an uncommon case necessary for script bindings.
Achtung: the returned value's allocStamp member is used for determining if fsl_db_close() should free the value or not. Thus if clients copy over this value without adjusting allocStamp back to its original value, the library will likely leak the instance. Been there, done that.
References FSL_EXPORT.
| FSL_EXPORT char const * fsl_db_name | ( | fsl_db const * | db | ) |
If a db name has been associated with db then it is returned, otherwise NULL is returned.
A db has no name by default, but fsl_cx-used ones get their database name assigned to them (e.g. "main" for the main db).
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_open | ( | fsl_db * | db, |
| char const * | dbFile, | ||
| fsl_flag32_t | openFlags ) |
Opens the given db file and populates db with its handle.
db must have been cleanly initialized by copy-initializing it from fsl_db_empty (or fsl_db_empty_m) or by allocating it using fsl_db_malloc(). Failure to do so will lead to undefined behaviour.
openFlags may be a mask of FSL_DB_OPEN_xxx values, but not all are used/supported here. If FSL_DB_OPEN_CREATE is not set in openFlags and dbFile does not exist, it will return FSL_RC_NOT_FOUND. The existence of FSL_DB_OPEN_CREATE in the flags will cause this routine to try to create the file if needed. If conflicting flags are specified (e.g. FSL_DB_OPEN_RO and FSL_DB_OPEN_RWC) then which one takes precedence is unspecified and possibly unpredictable. If openFlags is 0 then FSL_DB_OPEN_RO is assumed.
This routine normally looks for the given file before attempting to open it and will update db's error state if the file cannot be found. Those checks are skipped if (1) openFlags has the FSL_DB_OPEN_CREATE bit set, (2) dbName is empty (indicating a nameless temporary database), (3) the string contains a ":" in any byte position, in which case it is assumed to be a URL-style name or ":memory:". The exception to (3) is on Windows platforms, where it recognize drive letter prefixes in the form "X:".
See this page for the differences between ":memory:" and "":
https://www.sqlite.org/inmemorydb.html
This routine does not handle URL-style file names.
Returns FSL_RC_MISUSE if !db, !dbFile, or if db->dbh is not NULL (i.e. if it is already opened or its memory was default-initialized (use fsl_db_empty to cleanly copy-initialize new stack-allocated instances).
On error db->dbh will be NULL, but db->error might contain error details.
Regardless of success or failure, db should be passed to fsl_db_close() to free up all memory associated with it. It is not closed automatically by this function because doing so cleans up the error state, which the caller will presumably want to have.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_prepare | ( | fsl_db * | db, |
| fsl_stmt * | tgt, | ||
| char const * | sql, | ||
| ... ) |
Prepares an SQL statement for execution.
On success it returns 0, populates tgt with the statement's state, and the caller is obligated to eventually pass tgt to fsl_stmt_finalize(). tgt must have been cleanly initialized, either via allocation via fsl_stmt_malloc() or by copy-constructing fsl_stmt_empty resp. fsl_stmt_empty_m (depending on the context).
On error non-0 is returned and tgt is not modified. If preparation of the statement fails at the db level then FSL_RC_DB is returned f's error state (fsl_cx_err_get()) "should" contain more details about the problem. Returns FSL_RC_MISUSE if !db, !callback, or !sql. Returns FSL_RC_NOT_FOUND if db is not opened. Returns FSL_RC_RANGE if !*sql.
The sql string and the following arguments get routed through fsl_appendf(), so any formatting options supported by that routine may be used here. In particular, the %q and %Q formatting options are intended for use in escaping SQL for routines such as this one.
Compatibility note: in sqlite, empty SQL code evaluates successfully but with a NULL statement. This API disallows empty SQL because it uses NULL as a "no statement" marker and because empty SQL is arguably not a query at all.
Tips:
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_prepare_cached | ( | fsl_db * | db, |
| fsl_stmt ** | st, | ||
| char const * | sql, | ||
| ... ) |
A special-purpose variant of fsl_db_prepare() which caches statements based on their SQL code.
This works very much like fsl_db_prepare() and friends except that it can return the same statement (via *st) multiple times (statements with identical SQL are considered equivalent for caching purposes). Clients need not explicitly pass the returned statement to fsl_stmt_finalize() - the db holds these statements and will finalize them when it is closed. It is legal to pass them to finalize, in which case they will be cleaned up immediately but that also invalidates all pointers to the shared instances.
If client code does not call fsl_stmt_finalize(), it MUST pass the statement pointer to fsl_stmt_cached_yield(st) after is done with it. That makes the query available for use again with this routine. If a cached query is not yielded via fsl_stmt_cached_yield() then this routine will return FSL_RC_ACCESS on subsequent requests for that SQL to prevent that recursive (mis)use of the statement causes problems.
This routine is intended to be used in oft-called routines where the cost of re-creating statements on each execution could be prohibitive (or at least a bummer).
Returns 0 on success, FSL_RC_MISUSE if any arguments are invalid. On error, *st is not written to. On other errors db->error might be updated with more useful information. See the Caveats section below for more details.
Its intended usage looks like:
Though this function allows a formatted SQL string, caching is generally only useful with statements which have "static" SQL, i.e. no call-dependent values embedded within the SQL. It can, however, contain bind() placeholders which get reset for each use. Note that fsl_stmt_cached_yield() resets the statement, so most uses of cached statements do not require that the client explicitly reset cached statements (doing so is harmless, however).
Caveats:
Cached queries must not be used in contexts where recursion might cause the same query to be returned from this function while it is being processed at another level in the execution stack. Results would be undefined. Caching is primarily intended for often-used routines which bind and fetch simple values, and not for queries which bind large inlined values or might invoke recursion. Because of the potential for recursive breakage, this function flags queries it doles out and requires that clients call fsl_stmt_cached_yield() to un-flag them for re-use. It will return FSL_RC_ACCESS if an attempt is made to (re)prepare a statement for which a fsl_stmt_cached_yield() is pending, and db->error will be populated with a (long) error string describing the problem and listing the SQL which caused the collision/misuse. Such SQL can often be disambiguated by adding a %s, wrapped in a C-style comment, to the end and passing __func__ as its value (which is also useful for debugging in conjunction with SQL tracing).
Design note: for the recursion/parallel use case we "could" reimplement this to dole out a new statement (e.g. by appending " -- a_number" to the SQL to bypass the collision) and free it in fsl_stmt_cached_yield(), but that (A) gets uglier than it needs to be and (B) is not needed unless/until we really need cached queries in spots which would normally break them. The whole recursion problem is still theoretical at this point but could easily affect small, often-used queries without recursion.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_preparev | ( | fsl_db * | db, |
| fsl_stmt * | tgt, | ||
| char const * | sql, | ||
| va_list | args ) |
va_list counterpart of fsl_db_prepare().
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_preparev_cached | ( | fsl_db * | db, |
| fsl_stmt ** | st, | ||
| char const * | sql, | ||
| va_list | args ) |
The va_list counterpart of fsl_db_prepare_cached().
References FSL_EXPORT.
| FSL_EXPORT char * fsl_db_random_hex | ( | fsl_db * | db, |
| fsl_size_t | n ) |
Returns n bytes of random lower-case hexidecimal characters using the given db as its data source, plus a terminating NUL byte.
The returned memory must eventually be freed using fsl_free(). Returns NULL if !n, db is not opened, or on a db-level error.
References FSL_EXPORT.
| FSL_EXPORT const char * fsl_db_role_name | ( | enum fsl_dbrole_e | r | ) |
Returns a db name string for the given fsl_db_role value.
The string is static, guaranteed to live as long as the app. It returns NULL if passed FSL_DBROLE_NONE or some value out of range for the enum.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_select_slist | ( | fsl_db * | db, |
| fsl_list * | tgt, | ||
| char const * | fmt, | ||
| ... ) |
Expects fmt to be a SELECT-style query.
For each row in the query, the first column is fetched as a string and appended to the tgt list.
Returns 0 on success, FSL_RC_MISUSE if !fmt or fmt is empty, or any number of potential FSL_RC_OOM or db-related errors.
Results rows with a NULL value (resulting from an SQL NULL) are added to the list as NULL entries.
Each entry appended to the list is a (char *) which must be freed using fsl_free(). To easiest way to clean up the list and its contents is:
On error the list may be partially populated.
Complete example:
Of course fsl_list_visit() may be used to traverse the list as well, as long as the visitor expects (char [const]*) list elements.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_select_slistv | ( | fsl_db * | db, |
| fsl_list * | tgt, | ||
| char const * | fmt, | ||
| va_list | args ) |
The va_list counterpart of fsl_db_select_slist().
References FSL_EXPORT.
| FSL_EXPORT void fsl_db_sqltrace_enable | ( | fsl_db * | db, |
| FILE * | outStream, | ||
| bool | expandSql ) |
If db is an opened db handle, this registers a debugging function with the db which traces all SQL to the given FILE handle.
If outStream is NULL then tracing events will be emitted via FSL_DB_EVENT_TRACE_SQLX instead.
If expandedSql is true then it uses sqlite3_expanded_sql() to expand each traced statement, else it uses unexpanded SQL (which is much faster).
If outStream is not NULL then tracing will go there, otherwise it will go out via a FSL_DB_EVENT_TRACE_SQL or FSL_DB_EVENT_TRACE_SQLX event (depending on the value of expandedSql). Ownership of outStream is not modified by this call and outStream must outlive its association with db.
This is a no-op if db is closed.
This mechanism is only intended for debugging and exploration of how Fossil works. Tracing is often as easy way to ensure that a given code block is getting run.
TODOs:
References FSL_EXPORT.
| FSL_EXPORT double fsl_db_string_to_julian | ( | fsl_db * | db, |
| char const * | str ) |
Uses the given db to convert the given time string to Julian Day format.
If it cannot be converted, a negative value is returned. The str parameter can be anything suitable for passing to sqlite's:
SELECT julianday(str)
Note that this routine will escape str for use with SQL - the caller must not do so.
References FSL_EXPORT.
| FSL_EXPORT bool fsl_db_table_exists | ( | fsl_db * | db, |
| fsl_dbrole_e | whichDb, | ||
| const char * | zTable ) |
Returns true if the table name specified by the final argument exists in the fossil database specified by the 2nd argument on the db connection specified by the first argument, else returns false.
Trivia: this is one of the few libfossil APIs which makes use of FSL_DBROLE_TEMP.
Potential TODO: this is a bit of a wonky interface. Consider changing it to eliminate the role argument, which is only really needed if we have duplicate table names across attached dbs or if we internally mess up and write a table to the wrong db.
References FSL_EXPORT.
| FSL_EXPORT bool fsl_db_table_has_column | ( | fsl_db * | db, |
| char const * | zTableName, | ||
| char const * | zColName ) |
Returns non-0 (true) if the database (which must be open) table identified by zTableName has a column named zColName (case-sensitive), else returns 0.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_txn_begin | ( | fsl_db * | db | ) |
Begins a transaction on the given db.
This API historically used pseudo-nested transactions based off of BEGIN/COMMIT. As of 2025-08-09 it uses SAVEPOINTs instead. The difference is subtle but was a necessary change for the libfossil SCM pieces to be able to behave sensibly in some cases. These docs use the term "transaction" to mean "savepoint".
Returns FSL_RC_MISUSE if !db or the db is not connected, else the result of the underlying db call(s).
Transactions are an easy way to implement "dry-run" mode for some types of applications. For example:
Here's a tip for propagating error codes when using transactions:
That ensures that we propagate rc in the face of a rollback but we also capture the rc for a commit (which might yet fail).
Sidebar: this API, prior to 2025-08, used pseudo-nested transactions directly ported from fossil(1) (essentially a reference-counted BEGIN/END block, with each level representing one reference count point). As of 2025-08 it exclusively uses sqlite3's SAVEPOINT^1 feature, which is essentially nested transactions. This change enables better support for dry-run modes and more flexible non-fatal-to-the-transaction error handling. e.g. we can fail certain opertations, e.g. lookup of a resources, without inherently invalidating the whole transaction stack.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_txn_commit | ( | fsl_db * | db | ) |
Equivalent to fsl_db_txn_end_v2(db, true, false).
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_txn_end_v2 | ( | fsl_db * | db, |
| bool | keepSavepoint, | ||
| bool | bubbleRollback ) |
Decrements the transaction counter incremented by fsl_db_txn_begin() and commits or rolls back the savepoint if the counter goes to 0.
The behavior of keepSavepoint depends on the transaction depth:
If bubbleRollback is true, or any call to this function within the same top-level savepoint passed true as the bubbleRollback argument, the transaction is put into a persistent will-rollback mode. In this mode, individual savepoints can still be applied by passing true as the second argument, but when the final one is popped, the whole thing will be rolled back instead of applied.
To reiterate: if db fsl_db_txn_begin() is used in a nested manner and bubbleRollback is true for any one of the nested calls, then that value will be remembered, such that the downstream calls to this function within the same transaction will behave as if bubbleRollback were true even if they pass false for the third argument.
Achtung: the bubbleRollback==true behavior is, as of 2025-08, considered "legacy" and should no longer be used, but much code still currently expects that behavior.
The distinction been whether retaining a savepoint should put the transaction into a persistent rollback state is primarily of interest to operations which implement "dry-run" mode. For dry-run, keepSavepoint should always ben false, while bubbleRollback should be true if the operation failed in a way which could impact further operations in the same transaction.
Returns FSL_RC_MISUSE if db is not opened, 0 if the transaction counter is above 0, else the result of the (potentially many) underlying database operations.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_txn_level | ( | fsl_db * | db | ) |
Returns the given db's current transaction depth.
If the value is negative, its absolute value represents the depth but indicates that a rollback is pending. If it is positive, the transaction is still in a "good" state. If it is 0, no transaction is active.
References FSL_EXPORT.
| FSL_EXPORT int fsl_db_txn_rollback | ( | fsl_db * | db | ) |
Equivalent to fsl_db_txn_end_v2(db, false, true), noting that the final value of true there is for historical API compatibility and will be changed to false if we can get away with it elsewhere.
References FSL_EXPORT.
| FSL_EXPORT char * fsl_db_unix_to_iso8601 | ( | fsl_db * | db, |
| fsl_time_t | j, | ||
| bool | localTime ) |
Returns the given Julian date value formatted as an ISO8601 string (with a fractional seconds part if msPrecision is true, else without it).
Returns NULL if !db, db is not connected, j is less than 0, or on allocation error. The returned memory must eventually be freed using fsl_free().
If localTime is true then the value is converted to the local time, otherwise it is not.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_blob | ( | fsl_stmt * | stmt, |
| int | index, | ||
| void const * | v, | ||
| fsl_size_t | len, | ||
| bool | makeCopy ) |
Binds the first n bytes of v as a blob to the given 1-based bound parameter column in the given statement.
See fsl_stmt_bind_text() for the semantics of the makeCopy parameter and return value.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_blob_name | ( | fsl_stmt * | stmt, |
| char const * | param, | ||
| void const * | v, | ||
| fsl_int_t | len, | ||
| bool | makeCopy ) |
Equivalent to fsl_stmt_bind_blob() but binds to a named parameter.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_double | ( | fsl_stmt * | stmt, |
| int | index, | ||
| double | v ) |
Binds v to the given 1-based parameter index.
Returns 0 on succcess. Sets the Fossil context's error state on error.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_double_name | ( | fsl_stmt * | stmt, |
| char const * | param, | ||
| double | v ) |
Equivalent to fsl_stmt_bind_double() but binds to a named parameter.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_fmt | ( | fsl_stmt * | st, |
| char const * | fmt, | ||
| ... ) |
The elipsis counterpart of fsl_stmt_bind_fmtv().
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_fmtv | ( | fsl_stmt * | st, |
| char const * | fmt, | ||
| va_list | args ) |
Binds a series of values using a formatting string.
The string may contain the following characters, each of which refers to the next argument in the args list:
'-': binds a NULL and expects a NULL placeholder in the argument list (for consistency's sake).
'i': binds an int32
'I': binds an int64
'R': binds a fsl_id_t ('R' as in 'RID' or 'ROWID')
'f': binds a double
's': binds a (char const *) as text or NULL. See below.
'S': binds a (char const *) as a blob or NULL. See below.
'b': binds a (fsl_buffer const *) as text or NULL. See below.
'B': binds a (fsl_buffer const *) as a blob or NULL. See below.
' ': spaces are allowed for readability and are ignored.
'^': An optional modifier for "sSbB". See below.
Returns 0 on success, any number of other FSL_RC_xxx codes on error.
About the sSbB bindings:
Example:
Note the cast on the final argument to ensure that it's of the proper size for the 'i' type.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_id | ( | fsl_stmt * | stmt, |
| int | index, | ||
| fsl_id_t | v ) |
Binds v to the given 1-based parameter index.
Returns 0 on succcess. Sets the DB's error state on error.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_id_name | ( | fsl_stmt * | stmt, |
| char const * | param, | ||
| fsl_id_t | v ) |
Equivalent to fsl_stmt_bind_id() but binds to a named parameter.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_int32 | ( | fsl_stmt * | stmt, |
| int | index, | ||
| int32_t | v ) |
Binds v to the given 1-based parameter index.
Returns 0 on succcess. Sets the DB's error state on error.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_int32_name | ( | fsl_stmt * | stmt, |
| char const * | param, | ||
| int32_t | v ) |
Equivalent to fsl_stmt_bind_int32() but binds to a named parameter.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_int64 | ( | fsl_stmt * | stmt, |
| int | index, | ||
| int64_t | v ) |
Binds v to the given 1-based parameter index.
Returns 0 on succcess. Sets the DB's error state on error.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_int64_name | ( | fsl_stmt * | stmt, |
| char const * | param, | ||
| int64_t | v ) |
Equivalent to fsl_stmt_bind_int64() but binds to a named parameter.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_null | ( | fsl_stmt * | stmt, |
| int | index ) |
Binds NULL to the given 1-based parameter index.
Returns 0 on succcess. Sets the DB's error state on error.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_null_name | ( | fsl_stmt * | stmt, |
| char const * | param ) |
Equivalent to fsl_stmt_bind_null_name() but binds to a named parameter.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_step | ( | fsl_stmt * | st, |
| char const * | fmt, | ||
| ... ) |
The elipsis counterpart of fsl_stmt_bind_step().
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_step_v2 | ( | fsl_stmt * | st, |
| char const * | fmt, | ||
| ... ) |
The elipsis counterpart of fsl_stmt_bind_step_v2().
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_stepv | ( | fsl_stmt * | st, |
| char const * | fmt, | ||
| va_list | args ) |
Works exactly like fsl_stmt_bind_stepv_v2() except that it returns 0 if stepping results in FSL_RC_STEP_DONE.
That behavior is legacy and now consider to have been a poor design decision, but those semantics are currently heavily relied on throughout the library.
To re-iterate: this routine NEVER returns FSL_RC_STEP_DONE. We say that because some folks (🙋♂️) keep breaking things by checking for that code instead of 0. That's why fsl_stmt_bind_step_v2() was introduced.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_stepv_v2 | ( | fsl_stmt * | st, |
| char const * | fmt, | ||
| va_list | args ) |
Works like fsl_stmt_bind_fmt() but:
1) It calls fsl_stmt_reset() before binding the arguments.
2) If binding succeeds then it steps the given statement a single time.
3) If the result is NOT FSL_RC_STEP_ROW then it also resets the statement before returning. It does not do so for FSL_RC_STEP_ROW because doing so would make it impossible to fetch the current row's data.
Returns the result of the underlying step() call. It never returns 0.
Design note: the return value for FSL_RC_STEP_ROW, as opposed to returning 0, is necessary for proper statement use if the client wants to fetch any result data from the statement afterwards (which is only legal if FSL_RC_STEP_ROW was the result). This is also why it cannot reset the statement if that result is returned.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_text | ( | fsl_stmt * | stmt, |
| int | index, | ||
| char const * | v, | ||
| fsl_int_t | n, | ||
| bool | makeCopy ) |
Binds the first n bytes of v as text to the given 1-based bound parameter column in the given statement.
If makeCopy is true then the binding makes an copy of the data. Set makeCopy to false ONLY if you KNOW that the bytes will outlive the binding.
Returns 0 on success. On error stmt's underlying db's error state is updated, hopefully with a useful error message.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_bind_text_name | ( | fsl_stmt * | stmt, |
| char const * | param, | ||
| char const * | v, | ||
| fsl_int_t | n, | ||
| bool | makeCopy ) |
Equivalent to fsl_stmt_bind_text() but binds to a named parameter.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_cached_yield | ( | fsl_stmt * | st | ) |
"Yields" a statement which was prepared with fsl_db_prepare_cached(), such that that routine can once again use/re-issue that statement.
Statements prepared this way must be yielded in order to prevent that recursion causes difficult-to-track errors when a given cached statement is used concurrently in different code contexts.
If st is not NULL then this also calls fsl_stmt_reset() and fsl_stmt_clear_bindings() on the statement.
Returns 0 on success, FSL_RC_MISUSE if !st or if st does not appear to have been doled out from fsl_db_prepare_cached().
References FSL_EXPORT.
| FSL_EXPORT void fsl_stmt_clear_bindings | ( | fsl_stmt * | stmt | ) |
Clears memory associtated with any bindings on this statement.
This is a no-op if stmt is not prepared.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_col_count | ( | fsl_stmt const * | stmt | ) |
Returns the result column count for the given statement, or -1 if !stmt or it has not been prepared.
Note that this value is cached when the statement is created. Note that non-fetching queries (e.g. INSERT and UPDATE) have a column count of 0 unless they have a RETURNING clause. Some non-SELECT constructs, e.g. PRAGMA table_info(tname) and INSERT/UPDATE/DELETE with a RETURNING clause, behave like a SELECT and have a positive column count.
References FSL_EXPORT.
| FSL_EXPORT char const * fsl_stmt_col_name | ( | fsl_stmt * | stmt, |
| int | index ) |
Returns the name of the given 0-based result column index, or NULL if !stmt, stmt is not prepared, or index is out out of range.
The returned bytes are owned by the statement object and may be invalidated shortly after this is called, so the caller must copy the returned value if it needs to have any useful lifetime guarantees. It's a bit more complicated than this, but assume that any API calls involving the statement handle might invalidate the column name bytes.
The API guarantees that the returned value is either NULL or NUL-terminated.
References FSL_EXPORT.
| FSL_EXPORT fsl_db * fsl_stmt_db | ( | fsl_stmt * | stmt | ) |
Returns the db handle which prepared the given statement, or NULL if stmt has not been prepared.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_each | ( | fsl_stmt * | stmt, |
| fsl_stmt_each_f | callback, | ||
| void * | callbackState ) |
Calls the given callback one time for each result row in the given statement, iterating over stmt using fsl_stmt_step().
It applies no meaning to the callbackState parameter, which gets passed as-is to the callback. See fsl_stmt_each_f() for the semantics of the callback.
Returns 0 on success. Returns FSL_RC_MISUSE if !stmt or !callback.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_each_f_dump | ( | fsl_stmt * | stmt, |
| void * | state ) |
A fsl_stmt_each_f() impl, intended primarily for debugging, which simply outputs row data in tabular form via fsl_output().
The state argument must be a valid fsl_cx pointer. On the first row, the column names are output.
Achtung: this function's expectations were changed on 2024-09-16: prior to this, stmt's db handle had access to a fsl_cx instance, but that was factored out. It now requires the state argument to be a fsl_cx.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_finalize | ( | fsl_stmt * | stmt | ) |
Frees memory associated with stmt but does not free stmt unless it was allocated by fsl_stmt_malloc() (these objects are normally stack-allocated, and such object must be initialized by copying fsl_stmt_empty so that this function knows whether or not to fsl_free() them).
Returns FSL_RC_MISUSE if !stmt or it has already been finalized (but was not freed).
References FSL_EXPORT.
| FSL_EXPORT double fsl_stmt_g_double | ( | fsl_stmt * | stmt, |
| int | index ) |
Convenience form of fsl_stmt_get_double() which returns the value directly but cannot report errors.
It returns 0 on error, but that is not unambiguously an error.
References FSL_EXPORT.
| FSL_EXPORT fsl_id_t fsl_stmt_g_id | ( | fsl_stmt * | stmt, |
| int | index ) |
Convenience form of fsl_stmt_get_id() which returns the value directly but cannot report errors.
It returns -1 on error, but that is not unambiguously an error value.
References FSL_EXPORT.
| FSL_EXPORT int32_t fsl_stmt_g_int32 | ( | fsl_stmt * | stmt, |
| int | index ) |
Convenience form of fsl_stmt_get_int32() which returns the value directly but cannot report errors.
It returns 0 on error, but that is not unambiguously an error.
References FSL_EXPORT.
| FSL_EXPORT int64_t fsl_stmt_g_int64 | ( | fsl_stmt * | stmt, |
| int | index ) |
Convenience form of fsl_stmt_get_int64() which returns the value directly but cannot report errors.
It returns 0 on error, but that is not unambiguously an error.
References FSL_EXPORT.
| FSL_EXPORT char const * fsl_stmt_g_text | ( | fsl_stmt * | stmt, |
| int | index, | ||
| fsl_size_t * | outLen ) |
Convenience form of fsl_stmt_get_text() which returns the value directly but cannot report errors.
It returns NULL on error, but that is not unambiguously an error because it also returns NULL if the column contains an SQL NULL value. If outLen is not NULL then it is set to the byte length of the returned string.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_get_blob | ( | fsl_stmt * | stmt, |
| int | index, | ||
| void const ** | out, | ||
| fsl_size_t * | outLen ) |
The Blob counterpart of fsl_stmt_get_text().
Identical to that function except that its output result (3rd paramter) type differs, and it fetches the data as a raw blob, without any sort of string interpretation.
Returns FSL_RC_RANGE if index is out of range for stmt, FSL_RC_MISUSE if stmt has no result columns. Returns FSL_RC_OOM if fetching the text from the underlying statement handle fails due to an allocation error.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_get_double | ( | fsl_stmt * | stmt, |
| int | index, | ||
| double * | v ) |
Gets double value from the given 0-based result set column, assigns *v to that value, and returns 0 on success.
Returns FSL_RC_RANGE if index is out of range for stmt, FSL_RC_MISUSE if stmt has no result columns.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_get_id | ( | fsl_stmt * | stmt, |
| int | index, | ||
| fsl_id_t * | v ) |
The fsl_id_t counterpart of fsl_stmt_get_int32().
Depending on the sizeof(fsl_id_t), it behaves as one of fsl_stmt_get_int32() or fsl_stmt_get_int64().
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_get_int32 | ( | fsl_stmt * | stmt, |
| int | index, | ||
| int32_t * | v ) |
Gets an integer value from the given 0-based result set column, assigns *v to that value, and returns 0 on success.
Returns FSL_RC_RANGE if index is out of range for stmt, FSL_RC_MISUSE if stmt has no result columns.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_get_int64 | ( | fsl_stmt * | stmt, |
| int | index, | ||
| int64_t * | v ) |
Gets an integer value from the given 0-based result set column, assigns *v to that value, and returns 0 on success.
Returns FSL_RC_RANGE if index is out of range for stmt, FSL_RC_MISUSE if stmt has no result columns.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_get_text | ( | fsl_stmt * | stmt, |
| int | index, | ||
| char const ** | out, | ||
| fsl_size_t * | outLen ) |
Gets a string value from the given 0-based result set column, assigns *out (if out is not NULL) to that value, assigns *outLen (if outLen is not NULL) to *out's length in bytes, and returns 0 on success.
Ownership of the string memory is unchanged - it is owned by the statement and the caller should immediately copy it if it will be needed for much longer.
Returns FSL_RC_RANGE if index is out of range for stmt, FSL_RC_MISUSE if stmt has no result columns. Returns FSL_RC_OOM if fetching the text from the underlying statement handle fails due to an allocation error.
References FSL_EXPORT.
| FSL_EXPORT fsl_stmt * fsl_stmt_malloc | ( | void | ) |
Allocates a new, cleanly-initialized fsl_stmt instance using fsl_malloc().
The fsl_stmt counterpart of fsl_db_malloc().
The returned pointer must eventually be passed to fsl_stmt_finalize() to free it (whether or not it is ever passed to fsl_db_prepare()).
Returns NULL on allocation error.
See that function for when you might want to use this and a caveat involving the allocStamp member of the returned value. fsl_stmt_finalize() will free statements created with this function.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_param_count | ( | fsl_stmt const * | stmt | ) |
Returns the bound parameter count for the given statement, or -1 if !stmt or it has not been prepared.
Note that this value is cached when the statement is created.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_param_index | ( | fsl_stmt * | stmt, |
| char const * | param ) |
Returns the index of the given named parameter for the given statement, or -1 if !stmt or stmt is not prepared.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_reset | ( | fsl_stmt * | stmt | ) |
Equivalent to fsl_stmt_reset2(stmt, false).
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_reset2 | ( | fsl_stmt * | stmt, |
| bool | resetRowCounter ) |
Resets the given statement, analog to sqlite3_reset().
Should be called one time between fsl_stmt_step() iterations when running multiple INSERTS, UPDATES, etc. via the same statement. If resetRowCounter is true then the statement's row counter (st->rowCount) is also reset to 0, else it is left unmodified. (Most use cases don't use the row counter.)
Returns 0 on success, FSL_RC_MISUSE if stmt has not been prepared or has not been cleanly initialized via copying from fsl_stmt_empty or fsl_stmt_empty_m, FSL_RC_DB if the underlying reset fails (in which case the error state of the stmt->db handle is updated to contain the error information).
References FSL_EXPORT.
| FSL_EXPORT char const * fsl_stmt_sql | ( | fsl_stmt * | stmt, |
| fsl_size_t * | len ) |
Returns the SQL string used to prepare the given statement, or NULL if stmt has not been prepared.
If len is not NULL then *len is set to the length of the returned string (which is NUL-terminated). The returned bytes are owned by stmt and are invalidated when it is finalized.
References FSL_EXPORT.
| FSL_EXPORT int fsl_stmt_step | ( | fsl_stmt * | stmt | ) |
"Steps" the given SQL cursor one time.
The return values FSL_RC_STEP_ROW and FSL_RC_STEP_DONE are both success cases, the former indicating that one row has been fetched and the latter indicating that either no rows are left to fetch or the statement is a non-fetching query. On error some other non-zero code will be returned. On a db error this will update the underlying db's error state. This function increments stmt->rowCount by 1 if it returns FSL_RC_STEP_ROW.
Returns FSL_RC_MISUSE if !stmt or stmt has not been prepared.
It is only legal to call the fsl_stmt_g_xxx() and fsl_stmt_get_xxx() functions if this functon returns FSL_RC_STEP_ROW. FSL_RC_STEP_DONE is returned upon successfully ending iteration or if there is no iteration to perform (e.g. typically an UPDATE or INSERT, but see the next paragraph).
Though the historical definition of non-fetching query was pretty clear, the addition of the RETURNING keyword to sqlite3's dialect means that even an INSERT or DELETE can return data.
References FSL_EXPORT.
| FSL_EXPORT const fsl_db fsl_db_empty |
| FSL_EXPORT const fsl_stmt fsl_stmt_empty |