1.\" $Id: ksql.3,v 1.12 2018/04/20 21:52:27 kristaps Exp $ 2.\" 3.\" Copyright (c) 2016--2017 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: April 20 2018 $ 18.Dt KSQL 3 19.Os 20.Sh NAME 21.Nm ksql 22.Nd yet another SQLite wrapper 23.Sh LIBRARY 24.Lb ksql 25.Sh SYNOPSIS 26.In sys/types.h 27.In stdint.h 28.In ksql.h 29.Fd #define KSQL_VMAJOR x 30.Fd #define KSQL_VMINOR y 31.Fd #define KSQL_VBUILD z 32.Fd #define KSQL_VERSION "x.y.z" 33.Fd #define KSQL_VSTAMP xxxyyyzzz 34.Sh DESCRIPTION 35The 36.Nm ksql 37library is a 38.Dq lazy man's 39wrapper of a minimal subset of the SQLite C API. 40It makes interfacing with SQLite easy and fast for you, and safe for 41your database. 42.Pp 43The typical usage scenario is as follows: 44.Bl -enum 45.It 46assign configuration defaults with 47.Xr ksql_cfg_defaults 3 48and pre-set SQL statements in the 49.Fa stmts 50array; 51.It 52allocate a handle with 53.Xr ksql_alloc_child 3 54or, for reduced security, 55.Xr ksql_alloc 3 ; 56.It 57open a database connection on that handle with 58.Xr ksql_open 3 ; 59.It 60create statements with 61.Xr ksql_stmt_alloc 3 62and use them with 63.Xr ksql_bind_double 3 , 64.Xr ksql_stmt_double 3 , 65and 66.Xr ksql_stmt_free 3 ; 67or 68.It 69execute statements with 70.Xr ksql_exec 3 ; 71.It 72close and free with 73.Xr ksql_free 3 . 74.El 75.Pp 76There's also support for maintaining transactional consistency with 77.Xr ksql_trans_open 3 78and 79.Xr ksql_trans_commit 3 . 80Invoke 81.Dq apropos ksql 82to see all functions. 83.Pp 84The current version of the database is defined in 85.Dv KSQL_VERSION 86as a string of major number, minor number, and build. 87These values are available seperately as 88.Dv KSQL_VMAJOR , 89.Dv KSQL_VMINOR , 90and 91.Dv KSQL_VBUILD , 92respectively. 93A numeric concatenation of the version is defined as 94.Dv KSQL_VSTAMP , 95which may be used to test for version number applicability. 96.Ss Database safety 97By default (see 98.Xr ksql_alloc 3 99and 100.Xr ksql_alloc_child 3 ) , 101the library will invoke 102.Xr exit 3 103if any of the database functions fail. 104.Dq Failure 105means that any SQLite function (for example, stepping for result rows or 106binding parameters) that fails will trigger exit. 107.Pp 108It will also register an 109.Xr atexit 3 110hook that will clean up any open database connections, transactions, and 111open statements. 112.Pp 113Lastly, it will intercept the 114.Dv SIGABRT 115and 116.Dv SIGSEGV 117and trigger a controlled exit. 118Thus, if your program is signalled while performing (say) transactions, 119or any sort of open database, you won't corrupt the data. 120.Pp 121All of these safety measures can be disabled by providing the 122appropriate flags to 123.Xr ksql_alloc 3 124or 125.Xr ksql_alloc_child 3 . 126.Ss Compiling and linking 127To compile with 128.Nm ksql , 129use the header file 130.In ksql.h . 131For linking, use 132.Fl l Ns Ar ksql 133.Fl l Ns Ar sqlite3 . 134.Ss Access protocol 135Since SQLite uses a busy-wait approach, 136.Nm 137will sleep for random intervals between attempts returning 138.Dv SQLITE_BUSY 139or 140.Dv SQLITE_LOCKED . 141Within the first 10 attempts, the random interval is within 1/4 second. 142Within the 10\(en100 attempts, within 1/10 second. 143Greater than 100 attempts, 1/100 second. 144This scheme benefits longer waiters. 145.Pp 146Functions using this algorithm are 147.Xr ksql_exec 3 , 148.Xr ksql_stmt_step 3 149and 150.Xr ksql_stmt_cstep 3 , 151and 152.Xr ksql_stmt_alloc 3 . 153.Ss Pledge Promises 154The 155.Nm ksql 156library is built to operate in security-sensitive environments, including 157.Xr pledge 2 158on 159.Ox . 160.Pp 161If running in single-process mode (i.e., with 162.Xr ksql_alloc 3 ) , 163the 164.Va stdio rpath cpath wpath flock fattr 165pledges are required for all functions. 166.Pp 167If in split-process mode (with 168.Xr ksql_alloc_child 3 ) , 169then 170.Va stdio rpath cpath wpath flock proc fattr 171is required for 172.Xr ksql_alloc_child 3 , 173and only 174.Va stdio 175otherwise. 176.\" .Sh CONTEXT 177.\" For section 9 functions only. 178.\" .Sh IMPLEMENTATION NOTES 179.\" Not used in OpenBSD. 180.\" .Sh RETURN VALUES 181.\" For sections 2, 3, and 9 function return values only. 182.\" .Sh ENVIRONMENT 183.\" For sections 1, 6, 7, and 8 only. 184.\" .Sh FILES 185.\" .Sh EXIT STATUS 186.\" For sections 1, 6, and 8 only. 187.\" .Sh EXAMPLES 188.\" .Sh DIAGNOSTICS 189.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. 190.\" .Sh ERRORS 191.\" For sections 2, 3, 4, and 9 errno settings only. 192.Sh SEE ALSO 193.Xr ksql_alloc 3 , 194.Xr ksql_alloc_child 3 , 195.Xr ksql_bind_blob 3 , 196.Xr ksql_bind_bytes 3 , 197.Xr ksql_bind_double 3 , 198.Xr ksql_bind_int 3 , 199.Xr ksql_bind_str 3 , 200.Xr ksql_bind_zblob 3 , 201.Xr ksql_cfg_defaults 3 , 202.Xr ksql_close 3 , 203.Xr ksql_exec 3 , 204.Xr ksql_free 3 , 205.Xr ksql_lastid 3 , 206.Xr ksql_open 3 , 207.Xr ksql_role 3 , 208.Xr ksql_stmt_alloc 3 , 209.Xr ksql_stmt_blob 3 , 210.Xr ksql_stmt_bytes 3 , 211.Xr ksql_stmt_cstep 3 , 212.Xr ksql_stmt_double 3 , 213.Xr ksql_stmt_free 3 , 214.Xr ksql_stmt_int 3 , 215.Xr ksql_stmt_isnull 3 , 216.Xr ksql_stmt_reset 3 , 217.Xr ksql_stmt_step 3 , 218.Xr ksql_stmt_str 3 , 219.Xr ksql_trans_commit 3 , 220.Xr ksql_trans_exclopen 3 , 221.Xr ksql_trans_functions 3 , 222.Xr ksql_trans_open 3 , 223.Xr ksql_trans_rollback 3 , 224.Xr sqlite3 3 225.\" .Xr foobar 1 226.\" .Sh STANDARDS 227.\" .Sh HISTORY 228.\" .Sh AUTHORS 229.Sh CAVEATS 230This library is not thread-safe and does not plan to be. 231.\" .Sh BUGS 232.\" .Sh SECURITY CONSIDERATIONS 233.\" Not used in OpenBSD. 234