Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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)

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>

home | help