FreeBSD Manual Pages
KSQL(3) Library Functions Manual KSQL(3) NAME ksql -- yet another SQLite wrapper LIBRARY library "ksql" SYNOPSIS #include <sys/types.h> #include <stdint.h> #include <ksql.h> #define KSQL_VMAJOR x #define KSQL_VMINOR y #define KSQL_VBUILD z #define KSQL_VERSION x.y.z #define KSQL_VSTAMP xxxyyyzzz DESCRIPTION The ksql library is a "lazy man's" wrapper of a minimal subset of the SQLite C API. It makes interfacing with SQLite easy and fast for you, and safe for your database. The typical usage scenario is as follows: 1. assign configuration defaults with ksql_cfg_defaults(3) and pre- set SQL statements in the stmts array; 2. allocate a handle with ksql_alloc_child(3) or, for reduced secu- rity, ksql_alloc(3); 3. open a database connection on that handle with ksql_open(3); 4. create statements with ksql_stmt_alloc(3) and use them with ksql_bind_double(3), ksql_stmt_double(3), and ksql_stmt_free(3); or 5. execute statements with ksql_exec(3); 6. close and free with ksql_free(3). There's also support for maintaining transactional consistency with ksql_trans_open(3) and ksql_trans_commit(3). Invoke "apropos ksql" to see all functions. The current version of the database is defined in KSQL_VERSION as a string of major number, minor number, and build. These values are available seperately as KSQL_VMAJOR, KSQL_VMINOR, and KSQL_VBUILD, re- spectively. A numeric concatenation of the version is defined as KSQL_VSTAMP, which may be used to test for version number applicabil- ity. Database safety By default (see ksql_alloc(3) and ksql_alloc_child(3)), the library will invoke exit(3) if any of the database functions fail. "Failure" means that any SQLite function (for example, stepping for result rows or binding parameters) that fails will trigger exit. It will also register an atexit(3) hook that will clean up any open database connections, transactions, and open statements. Lastly, it will intercept the SIGABRT and SIGSEGV and trigger a con- trolled exit. Thus, if your program is signalled while performing (say) transactions, or any sort of open database, you won't corrupt the data. All of these safety measures can be disabled by providing the appropri- ate flags to ksql_alloc(3) or ksql_alloc_child(3). Compiling and linking To compile with ksql, use the header file <ksql.h>. For linking, use -lksql -lsqlite3. Access protocol Since SQLite uses a busy-wait approach, ksql will sleep for random in- tervals between attempts returning SQLITE_BUSY or SQLITE_LOCKED. Within the first 10 attempts, the random interval is within 1/4 second. Within the 10-100 attempts, within 1/10 second. Greater than 100 at- tempts, 1/100 second. This scheme benefits longer waiters. Functions using this algorithm are ksql_exec(3), ksql_stmt_step(3) and ksql_stmt_cstep(3), and ksql_stmt_alloc(3). Pledge Promises The ksql library is built to operate in security-sensitive environ- ments, including pledge(2) on OpenBSD. If running in single-process mode (i.e., with ksql_alloc(3)), the stdio rpath cpath wpath flock fattr pledges are required for all functions. If in split-process mode (with ksql_alloc_child(3)), then stdio rpath cpath wpath flock proc fattr is required for ksql_alloc_child(3), and only stdio otherwise. SEE ALSO ksql_alloc(3), ksql_alloc_child(3), ksql_bind_blob(3), ksql_bind_bytes(3), ksql_bind_double(3), ksql_bind_int(3), ksql_bind_str(3), ksql_bind_zblob(3), ksql_cfg_defaults(3), ksql_close(3), ksql_exec(3), ksql_free(3), ksql_lastid(3), ksql_open(3), ksql_role(3), ksql_stmt_alloc(3), ksql_stmt_blob(3), ksql_stmt_bytes(3), ksql_stmt_cstep(3), ksql_stmt_double(3), ksql_stmt_free(3), ksql_stmt_int(3), ksql_stmt_isnull(3), ksql_stmt_reset(3), ksql_stmt_step(3), ksql_stmt_str(3), ksql_trans_commit(3), ksql_trans_exclopen(3), ksql_trans_functions(3), ksql_trans_open(3), ksql_trans_rollback(3), sqlite3(3) CAVEATS This library is not thread-safe and does not plan to be. FreeBSD Ports 14.quarterly April 20, 2018 KSQL(3)
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | SEE ALSO | CAVEATS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ksql&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>