1 /*

     2 ** 2001 September 15

     3 **

     4 ** The author disclaims copyright to this source code.  In place of

     5 ** a legal notice, here is a blessing:

     6 **

     7 **    May you do good and not evil.

     8 **    May you find forgiveness for yourself and forgive others.

     9 **    May you share freely, never taking more than you give.

    10 **

    11 *************************************************************************

    12 ** This header file defines the interface that the SQLite library

    13 ** presents to client programs.  If a C-function, structure, datatype,

    14 ** or constant definition does not appear in this file, then it is

    15 ** not a published API of SQLite, is subject to change without

    16 ** notice, and should not be referenced by programs that use SQLite.

    17 **

    18 ** Some of the definitions that are in this file are marked as

    19 ** "experimental".  Experimental interfaces are normally new

    20 ** features recently added to SQLite.  We do not anticipate changes

    21 ** to experimental interfaces but reserve to make minor changes if

    22 ** experience from use "in the wild" suggest such changes are prudent.

    23 **

    24 ** The official C-language API documentation for SQLite is derived

    25 ** from comments in this file.  This file is the authoritative source

    26 ** on how SQLite interfaces are suppose to operate.

    27 **

    28 ** The name of this file under configuration management is "sqlite.h.in".

    29 ** The makefile makes some minor changes to this file (such as inserting

    30 ** the version number) and changes its name to "sqlite3.h" as

    31 ** part of the build process.

    32 **

    33 ** @(#) $Id: sqlite.h.in,v 1.387 2008/08/05 17:53:23 drh Exp $

    34 */

    35 #ifndef _SQLITE3_H_

    36 #define _SQLITE3_H_

    37 #include <stdarg.h>     /* Needed for the definition of va_list */

    38 

    39 /*

    40 ** Make sure we can call this stuff from C++.

    41 */

    42 #ifdef __cplusplus

    43 extern "C" {

    44 #endif

    45 

    46 

    47 /*

    48 ** Add the ability to override 'extern'

    49 */

    50 #ifndef SQLITE_EXTERN

    51 # define SQLITE_EXTERN extern

    52 #endif

    53 

    54 /*

    55 ** Ensure these symbols were not defined by some previous header file.

    56 */

    57 #ifdef SQLITE_VERSION

    58 # undef SQLITE_VERSION

    59 #endif

    60 #ifdef SQLITE_VERSION_NUMBER

    61 # undef SQLITE_VERSION_NUMBER

    62 #endif

    63 

    64 /*

    65 ** CAPI3REF: Compile-Time Library Version Numbers {H10010} <S60100>

    66 **

    67 ** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in

    68 ** the sqlite3.h file specify the version of SQLite with which

    69 ** that header file is associated.

    70 **

    71 ** The "version" of SQLite is a string of the form "X.Y.Z".

    72 ** The phrase "alpha" or "beta" might be appended after the Z.

    73 ** The X value is major version number always 3 in SQLite3.

    74 ** The X value only changes when backwards compatibility is

    75 ** broken and we intend to never break backwards compatibility.

    76 ** The Y value is the minor version number and only changes when

    77 ** there are major feature enhancements that are forwards compatible

    78 ** but not backwards compatible.

    79 ** The Z value is the release number and is incremented with

    80 ** each release but resets back to 0 whenever Y is incremented.

    81 **

    82 ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].

    83 **

    84 ** INVARIANTS:

    85 **

    86 ** {H10011} The SQLITE_VERSION #define in the sqlite3.h header file shall

    87 **          evaluate to a string literal that is the SQLite version

    88 **          with which the header file is associated.

    89 **

    90 ** {H10014} The SQLITE_VERSION_NUMBER #define shall resolve to an integer

    91 **          with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z

    92 **          are the major version, minor version, and release number.

    93 */

    94 #define SQLITE_VERSION         "3.6.1"

    95 #define SQLITE_VERSION_NUMBER  3006001

    96 

    97 /*

    98 ** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100>

    99 ** KEYWORDS: sqlite3_version

   100 **

   101 ** These features provide the same information as the [SQLITE_VERSION]

   102 ** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated

   103 ** with the library instead of the header file.  Cautious programmers might

   104 ** include a check in their application to verify that

   105 ** sqlite3_libversion_number() always returns the value

   106 ** [SQLITE_VERSION_NUMBER].

   107 **

   108 ** The sqlite3_libversion() function returns the same information as is

   109 ** in the sqlite3_version[] string constant.  The function is provided

   110 ** for use in DLLs since DLL users usually do not have direct access to string

   111 ** constants within the DLL.

   112 **

   113 ** INVARIANTS:

   114 **

   115 ** {H10021} The [sqlite3_libversion_number()] interface shall return

   116 **          an integer equal to [SQLITE_VERSION_NUMBER].

   117 **

   118 ** {H10022} The [sqlite3_version] string constant shall contain

   119 **          the text of the [SQLITE_VERSION] string.

   120 **

   121 ** {H10023} The [sqlite3_libversion()] function shall return

   122 **          a pointer to the [sqlite3_version] string constant.

   123 */

   124 SQLITE_EXTERN const char sqlite3_version[];

   125 const char *sqlite3_libversion(void);

   126 int sqlite3_libversion_number(void);

   127 

   128 /*

   129 ** CAPI3REF: Test To See If The Library Is Threadsafe {H10100} <S60100>

   130 **

   131 ** SQLite can be compiled with or without mutexes.  When

   132 ** the [SQLITE_THREADSAFE] C preprocessor macro is true, mutexes

   133 ** are enabled and SQLite is threadsafe.  When that macro is false,

   134 ** the mutexes are omitted.  Without the mutexes, it is not safe

   135 ** to use SQLite concurrently from more than one thread.

   136 **

   137 ** Enabling mutexes incurs a measurable performance penalty.

   138 ** So if speed is of utmost importance, it makes sense to disable

   139 ** the mutexes.  But for maximum safety, mutexes should be enabled.

   140 ** The default behavior is for mutexes to be enabled.

   141 **

   142 ** This interface can be used by a program to make sure that the

   143 ** version of SQLite that it is linking against was compiled with

   144 ** the desired setting of the [SQLITE_THREADSAFE] macro.

   145 **

   146 ** This interface only reports on the compile-time mutex setting

   147 ** of the [SQLITE_THREADSAFE] flag.  If SQLite is compiled with

   148 ** SQLITE_THREADSAFE=1 then mutexes are enabled by default but

   149 ** can be fully or partially disabled using a call to [sqlite3_config()]

   150 ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],

   151 ** or [SQLITE_CONFIG_MUTEX].  The return value of this function shows

   152 ** only the default compile-time setting, not any run-time changes

   153 ** to that setting.

   154 **

   155 ** INVARIANTS:

   156 **

   157 ** {H10101} The [sqlite3_threadsafe()] function shall return nonzero if

   158 **          SQLite was compiled with the its mutexes enabled by default

   159 **          or zero if SQLite was compiled such that mutexes are

   160 **          permanently disabled.

   161 **

   162 ** {H10102} The value returned by the [sqlite3_threadsafe()] function

   163 **          shall not change when mutex setting are modified at

   164 **          runtime using the [sqlite3_config()] interface and 

   165 **          especially the [SQLITE_CONFIG_SINGLETHREAD],

   166 **          [SQLITE_CONFIG_MULTITHREAD], [SQLITE_CONFIG_SERIALIZED],

   167 **          and [SQLITE_CONFIG_MUTEX] verbs.

   168 */

   169 int sqlite3_threadsafe(void);

   170 

   171 /*

   172 ** CAPI3REF: Database Connection Handle {H12000} <S40200>

   173 ** KEYWORDS: {database connection} {database connections}

   174 **

   175 ** Each open SQLite database is represented by a pointer to an instance of

   176 ** the opaque structure named "sqlite3".  It is useful to think of an sqlite3

   177 ** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and

   178 ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]

   179 ** is its destructor.  There are many other interfaces (such as

   180 ** [sqlite3_prepare_v2()], [sqlite3_create_function()], and

   181 ** [sqlite3_busy_timeout()] to name but three) that are methods on an

   182 ** sqlite3 object.

   183 */

   184 typedef struct sqlite3 sqlite3;

   185 

   186 /*

   187 ** CAPI3REF: 64-Bit Integer Types {H10200} <S10110>

   188 ** KEYWORDS: sqlite_int64 sqlite_uint64

   189 **

   190 ** Because there is no cross-platform way to specify 64-bit integer types

   191 ** SQLite includes typedefs for 64-bit signed and unsigned integers.

   192 **

   193 ** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.

   194 ** The sqlite_int64 and sqlite_uint64 types are supported for backwards

   195 ** compatibility only.

   196 **

   197 ** INVARIANTS:

   198 **

   199 ** {H10201} The [sqlite_int64] and [sqlite3_int64] type shall specify

   200 **          a 64-bit signed integer.

   201 **

   202 ** {H10202} The [sqlite_uint64] and [sqlite3_uint64] type shall specify

   203 **          a 64-bit unsigned integer.

   204 */

   205 #ifdef SQLITE_INT64_TYPE

   206   typedef SQLITE_INT64_TYPE sqlite_int64;

   207   typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;

   208 #elif defined(_MSC_VER) || defined(__BORLANDC__)

   209   typedef __int64 sqlite_int64;

   210   typedef unsigned __int64 sqlite_uint64;

   211 #else

   212   typedef long long int sqlite_int64;

   213   typedef unsigned long long int sqlite_uint64;

   214 #endif

   215 typedef sqlite_int64 sqlite3_int64;

   216 typedef sqlite_uint64 sqlite3_uint64;

   217 

   218 /*

   219 ** If compiling for a processor that lacks floating point support,

   220 ** substitute integer for floating-point.

   221 */

   222 #ifdef SQLITE_OMIT_FLOATING_POINT

   223 # define double sqlite3_int64

   224 #endif

   225 

   226 /*

   227 ** CAPI3REF: Closing A Database Connection {H12010} <S30100><S40200>

   228 **

   229 ** This routine is the destructor for the [sqlite3] object.

   230 **

   231 ** Applications should [sqlite3_finalize | finalize] all [prepared statements]

   232 ** and [sqlite3_blob_close | close] all [BLOB handles] associated with

   233 ** the [sqlite3] object prior to attempting to close the object.

   234 ** The [sqlite3_next_stmt()] interface can be used to locate all

   235 ** [prepared statements] associated with a [database connection] if desired.

   236 ** Typical code might look like this:

   237 **

   238 ** <blockquote><pre>

   239 ** sqlite3_stmt *pStmt;

   240 ** while( (pStmt = sqlite3_next_stmt(db, 0))!=0 ){

   241 **     sqlite3_finalize(pStmt);

   242 ** }

   243 ** </pre></blockquote>

   244 **

   245 ** If [sqlite3_close()] is invoked while a transaction is open,

   246 ** the transaction is automatically rolled back.

   247 **

   248 ** INVARIANTS:

   249 **

   250 ** {H12011} A successful call to [sqlite3_close(C)] shall destroy the

   251 **          [database connection] object C.

   252 **

   253 ** {H12012} A successful call to [sqlite3_close(C)] shall return SQLITE_OK.

   254 **

   255 ** {H12013} A successful call to [sqlite3_close(C)] shall release all

   256 **          memory and system resources associated with [database connection]

   257 **          C.

   258 **

   259 ** {H12014} A call to [sqlite3_close(C)] on a [database connection] C that

   260 **          has one or more open [prepared statements] shall fail with

   261 **          an [SQLITE_BUSY] error code.

   262 **

   263 ** {H12015} A call to [sqlite3_close(C)] where C is a NULL pointer shall

   264 **          return SQLITE_OK.

   265 **

   266 ** {H12019} When [sqlite3_close(C)] is invoked on a [database connection] C

   267 **          that has a pending transaction, the transaction shall be

   268 **          rolled back.

   269 **

   270 ** ASSUMPTIONS:

   271 **

   272 ** {A12016} The C parameter to [sqlite3_close(C)] must be either a NULL

   273 **          pointer or an [sqlite3] object pointer obtained

   274 **          from [sqlite3_open()], [sqlite3_open16()], or

   275 **          [sqlite3_open_v2()], and not previously closed.

   276 */

   277 int sqlite3_close(sqlite3 *);

   278 

   279 /*

   280 ** The type for a callback function.

   281 ** This is legacy and deprecated.  It is included for historical

   282 ** compatibility and is not documented.

   283 */

   284 typedef int (*sqlite3_callback)(void*,int,char**, char**);

   285 

   286 /*

   287 ** CAPI3REF: One-Step Query Execution Interface {H12100} <S10000>

   288 **

   289 ** The sqlite3_exec() interface is a convenient way of running one or more

   290 ** SQL statements without having to write a lot of C code.  The UTF-8 encoded

   291 ** SQL statements are passed in as the second parameter to sqlite3_exec().

   292 ** The statements are evaluated one by one until either an error or

   293 ** an interrupt is encountered, or until they are all done.  The 3rd parameter

   294 ** is an optional callback that is invoked once for each row of any query

   295 ** results produced by the SQL statements.  The 5th parameter tells where

   296 ** to write any error messages.

   297 **

   298 ** The error message passed back through the 5th parameter is held

   299 ** in memory obtained from [sqlite3_malloc()].  To avoid a memory leak,

   300 ** the calling application should call [sqlite3_free()] on any error

   301 ** message returned through the 5th parameter when it has finished using

   302 ** the error message.

   303 **

   304 ** If the SQL statement in the 2nd parameter is NULL or an empty string

   305 ** or a string containing only whitespace and comments, then no SQL

   306 ** statements are evaluated and the database is not changed.

   307 **

   308 ** The sqlite3_exec() interface is implemented in terms of

   309 ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].

   310 ** The sqlite3_exec() routine does nothing to the database that cannot be done

   311 ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].

   312 **

   313 ** INVARIANTS:

   314 **

   315 ** {H12101} A successful invocation of [sqlite3_exec(D,S,C,A,E)]

   316 **          shall sequentially evaluate all of the UTF-8 encoded,

   317 **          semicolon-separated SQL statements in the zero-terminated

   318 **          string S within the context of the [database connection] D.

   319 **

   320 ** {H12102} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL then

   321 **          the actions of the interface shall be the same as if the

   322 **          S parameter were an empty string.

   323 **

   324 ** {H12104} The return value of [sqlite3_exec()] shall be [SQLITE_OK] if all

   325 **          SQL statements run successfully and to completion.

   326 **

   327 ** {H12105} The return value of [sqlite3_exec()] shall be an appropriate

   328 **          non-zero [error code] if any SQL statement fails.

   329 **

   330 ** {H12107} If one or more of the SQL statements handed to [sqlite3_exec()]

   331 **          return results and the 3rd parameter is not NULL, then

   332 **          the callback function specified by the 3rd parameter shall be

   333 **          invoked once for each row of result.

   334 **

   335 ** {H12110} If the callback returns a non-zero value then [sqlite3_exec()]

   336 **          shall abort the SQL statement it is currently evaluating,

   337 **          skip all subsequent SQL statements, and return [SQLITE_ABORT].

   338 **

   339 ** {H12113} The [sqlite3_exec()] routine shall pass its 4th parameter through

   340 **          as the 1st parameter of the callback.

   341 **

   342 ** {H12116} The [sqlite3_exec()] routine shall set the 2nd parameter of its

   343 **          callback to be the number of columns in the current row of

   344 **          result.

   345 **

   346 ** {H12119} The [sqlite3_exec()] routine shall set the 3rd parameter of its

   347 **          callback to be an array of pointers to strings holding the

   348 **          values for each column in the current result set row as

   349 **          obtained from [sqlite3_column_text()].

   350 **

   351 ** {H12122} The [sqlite3_exec()] routine shall set the 4th parameter of its

   352 **          callback to be an array of pointers to strings holding the

   353 **          names of result columns as obtained from [sqlite3_column_name()].

   354 **

   355 ** {H12125} If the 3rd parameter to [sqlite3_exec()] is NULL then

   356 **          [sqlite3_exec()] shall silently discard query results.

   357 **

   358 ** {H12131} If an error occurs while parsing or evaluating any of the SQL

   359 **          statements in the S parameter of [sqlite3_exec(D,S,C,A,E)] and if

   360 **          the E parameter is not NULL, then [sqlite3_exec()] shall store

   361 **          in *E an appropriate error message written into memory obtained

   362 **          from [sqlite3_malloc()].

   363 **

   364 ** {H12134} The [sqlite3_exec(D,S,C,A,E)] routine shall set the value of

   365 **          *E to NULL if E is not NULL and there are no errors.

   366 **

   367 ** {H12137} The [sqlite3_exec(D,S,C,A,E)] function shall set the [error code]

   368 **          and message accessible via [sqlite3_errcode()],

   369 **          [sqlite3_errmsg()], and [sqlite3_errmsg16()].

   370 **

   371 ** {H12138} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL or an

   372 **          empty string or contains nothing other than whitespace, comments,

   373 **          and/or semicolons, then results of [sqlite3_errcode()],

   374 **          [sqlite3_errmsg()], and [sqlite3_errmsg16()]

   375 **          shall reset to indicate no errors.

   376 **

   377 ** ASSUMPTIONS:

   378 **

   379 ** {A12141} The first parameter to [sqlite3_exec()] must be an valid and open

   380 **          [database connection].

   381 **

   382 ** {A12142} The database connection must not be closed while

   383 **          [sqlite3_exec()] is running.

   384 **

   385 ** {A12143} The calling function should use [sqlite3_free()] to free

   386 **          the memory that *errmsg is left pointing at once the error

   387 **          message is no longer needed.

   388 **

   389 ** {A12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()]

   390 **          must remain unchanged while [sqlite3_exec()] is running.

   391 */

   392 int sqlite3_exec(

   393   sqlite3*,                                  /* An open database */

   394   const char *sql,                           /* SQL to be evaluated */

   395   int (*callback)(void*,int,char**,char**),  /* Callback function */

   396   void *,                                    /* 1st argument to callback */

   397   char **errmsg                              /* Error msg written here */

   398 );

   399 

   400 /*

   401 ** CAPI3REF: Result Codes {H10210} <S10700>

   402 ** KEYWORDS: SQLITE_OK {error code} {error codes}

   403 ** KEYWORDS: {result code} {result codes}

   404 **

   405 ** Many SQLite functions return an integer result code from the set shown

   406 ** here in order to indicates success or failure.

   407 **

   408 ** New error codes may be added in future versions of SQLite.

   409 **

   410 ** See also: [SQLITE_IOERR_READ | extended result codes]

   411 */

   412 #define SQLITE_OK           0   /* Successful result */

   413 /* beginning-of-error-codes */

   414 #define SQLITE_ERROR        1   /* SQL error or missing database */

   415 #define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */

   416 #define SQLITE_PERM         3   /* Access permission denied */

   417 #define SQLITE_ABORT        4   /* Callback routine requested an abort */

   418 #define SQLITE_BUSY         5   /* The database file is locked */

   419 #define SQLITE_LOCKED       6   /* A table in the database is locked */

   420 #define SQLITE_NOMEM        7   /* A malloc() failed */

   421 #define SQLITE_READONLY     8   /* Attempt to write a readonly database */

   422 #define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/

   423 #define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */

   424 #define SQLITE_CORRUPT     11   /* The database disk image is malformed */

   425 #define SQLITE_NOTFOUND    12   /* NOT USED. Table or record not found */

   426 #define SQLITE_FULL        13   /* Insertion failed because database is full */

   427 #define SQLITE_CANTOPEN    14   /* Unable to open the database file */

   428 #define SQLITE_PROTOCOL    15   /* NOT USED. Database lock protocol error */

   429 #define SQLITE_EMPTY       16   /* Database is empty */

   430 #define SQLITE_SCHEMA      17   /* The database schema changed */

   431 #define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */

   432 #define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */

   433 #define SQLITE_MISMATCH    20   /* Data type mismatch */

   434 #define SQLITE_MISUSE      21   /* Library used incorrectly */

   435 #define SQLITE_NOLFS       22   /* Uses OS features not supported on host */

   436 #define SQLITE_AUTH        23   /* Authorization denied */

   437 #define SQLITE_FORMAT      24   /* Auxiliary database format error */

   438 #define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */

   439 #define SQLITE_NOTADB      26   /* File opened that is not a database file */

   440 #define SQLITE_ROW         100  /* sqlite3_step() has another row ready */

   441 #define SQLITE_DONE        101  /* sqlite3_step() has finished executing */

   442 /* end-of-error-codes */

   443 

   444 /*

   445 ** CAPI3REF: Extended Result Codes {H10220} <S10700>

   446 ** KEYWORDS: {extended error code} {extended error codes}

   447 ** KEYWORDS: {extended result code} {extended result codes}

   448 **

   449 ** In its default configuration, SQLite API routines return one of 26 integer

   450 ** [SQLITE_OK | result codes].  However, experience has shown that many of

   451 ** these result codes are too coarse-grained.  They do not provide as

   452 ** much information about problems as programmers might like.  In an effort to

   453 ** address this, newer versions of SQLite (version 3.3.8 and later) include

   454 ** support for additional result codes that provide more detailed information

   455 ** about errors. The extended result codes are enabled or disabled

   456 ** on a per database connection basis using the

   457 ** [sqlite3_extended_result_codes()] API.

   458 **

   459 ** Some of the available extended result codes are listed here.

   460 ** One may expect the number of extended result codes will be expand

   461 ** over time.  Software that uses extended result codes should expect

   462 ** to see new result codes in future releases of SQLite.

   463 **

   464 ** The SQLITE_OK result code will never be extended.  It will always

   465 ** be exactly zero.

   466 **

   467 ** INVARIANTS:

   468 **

   469 ** {H10223} The symbolic name for an extended result code shall contains

   470 **          a related primary result code as a prefix.

   471 **

   472 ** {H10224} Primary result code names shall contain a single "_" character.

   473 **

   474 ** {H10225} Extended result code names shall contain two or more "_" characters.

   475 **

   476 ** {H10226} The numeric value of an extended result code shall contain the

   477 **          numeric value of its corresponding primary result code in

   478 **          its least significant 8 bits.

   479 */

   480 #define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))

   481 #define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))

   482 #define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))

   483 #define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))

   484 #define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))

   485 #define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))

   486 #define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))

   487 #define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))

   488 #define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))

   489 #define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))

   490 #define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))

   491 #define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))

   492 #define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))

   493 #define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))

   494 

   495 /*

   496 ** CAPI3REF: Flags For File Open Operations {H10230} <H11120> <H12700>

   497 **

   498 ** These bit values are intended for use in the

   499 ** 3rd parameter to the [sqlite3_open_v2()] interface and

   500 ** in the 4th parameter to the xOpen method of the

   501 ** [sqlite3_vfs] object.

   502 */

   503 #define SQLITE_OPEN_READONLY         0x00000001

   504 #define SQLITE_OPEN_READWRITE        0x00000002

   505 #define SQLITE_OPEN_CREATE           0x00000004

   506 #define SQLITE_OPEN_DELETEONCLOSE    0x00000008

   507 #define SQLITE_OPEN_EXCLUSIVE        0x00000010

   508 #define SQLITE_OPEN_MAIN_DB          0x00000100

   509 #define SQLITE_OPEN_TEMP_DB          0x00000200

   510 #define SQLITE_OPEN_TRANSIENT_DB     0x00000400

   511 #define SQLITE_OPEN_MAIN_JOURNAL     0x00000800

   512 #define SQLITE_OPEN_TEMP_JOURNAL     0x00001000

   513 #define SQLITE_OPEN_SUBJOURNAL       0x00002000

   514 #define SQLITE_OPEN_MASTER_JOURNAL   0x00004000

   515 #define SQLITE_OPEN_NOMUTEX          0x00008000

   516 

   517 /*

   518 ** CAPI3REF: Device Characteristics {H10240} <H11120>

   519 **

   520 ** The xDeviceCapabilities method of the [sqlite3_io_methods]

   521 ** object returns an integer which is a vector of the these

   522 ** bit values expressing I/O characteristics of the mass storage

   523 ** device that holds the file that the [sqlite3_io_methods]

   524 ** refers to.

   525 **

   526 ** The SQLITE_IOCAP_ATOMIC property means that all writes of

   527 ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values

   528 ** mean that writes of blocks that are nnn bytes in size and

   529 ** are aligned to an address which is an integer multiple of

   530 ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means

   531 ** that when data is appended to a file, the data is appended

   532 ** first then the size of the file is extended, never the other

   533 ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that

   534 ** information is written to disk in the same order as calls

   535 ** to xWrite().

   536 */

   537 #define SQLITE_IOCAP_ATOMIC          0x00000001

   538 #define SQLITE_IOCAP_ATOMIC512       0x00000002

   539 #define SQLITE_IOCAP_ATOMIC1K        0x00000004

   540 #define SQLITE_IOCAP_ATOMIC2K        0x00000008

   541 #define SQLITE_IOCAP_ATOMIC4K        0x00000010

   542 #define SQLITE_IOCAP_ATOMIC8K        0x00000020

   543 #define SQLITE_IOCAP_ATOMIC16K       0x00000040

   544 #define SQLITE_IOCAP_ATOMIC32K       0x00000080

   545 #define SQLITE_IOCAP_ATOMIC64K       0x00000100

   546 #define SQLITE_IOCAP_SAFE_APPEND     0x00000200

   547 #define SQLITE_IOCAP_SEQUENTIAL      0x00000400

   548 

   549 /*

   550 ** CAPI3REF: File Locking Levels {H10250} <H11120> <H11310>

   551 **

   552 ** SQLite uses one of these integer values as the second

   553 ** argument to calls it makes to the xLock() and xUnlock() methods

   554 ** of an [sqlite3_io_methods] object.

   555 */

   556 #define SQLITE_LOCK_NONE          0

   557 #define SQLITE_LOCK_SHARED        1

   558 #define SQLITE_LOCK_RESERVED      2

   559 #define SQLITE_LOCK_PENDING       3

   560 #define SQLITE_LOCK_EXCLUSIVE     4

   561 

   562 /*

   563 ** CAPI3REF: Synchronization Type Flags {H10260} <H11120>

   564 **

   565 ** When SQLite invokes the xSync() method of an

   566 ** [sqlite3_io_methods] object it uses a combination of

   567 ** these integer values as the second argument.

   568 **

   569 ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the

   570 ** sync operation only needs to flush data to mass storage.  Inode

   571 ** information need not be flushed. The SQLITE_SYNC_NORMAL flag means

   572 ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means

   573 ** to use Mac OS-X style fullsync instead of fsync().

   574 */

   575 #define SQLITE_SYNC_NORMAL        0x00002

   576 #define SQLITE_SYNC_FULL          0x00003

   577 #define SQLITE_SYNC_DATAONLY      0x00010

   578 

   579 /*

   580 ** CAPI3REF: OS Interface Open File Handle {H11110} <S20110>

   581 **

   582 ** An [sqlite3_file] object represents an open file in the OS

   583 ** interface layer.  Individual OS interface implementations will

   584 ** want to subclass this object by appending additional fields

   585 ** for their own use.  The pMethods entry is a pointer to an

   586 ** [sqlite3_io_methods] object that defines methods for performing

   587 ** I/O operations on the open file.

   588 */

   589 typedef struct sqlite3_file sqlite3_file;

   590 struct sqlite3_file {

   591   const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */

   592 };

   593 

   594 /*

   595 ** CAPI3REF: OS Interface File Virtual Methods Object {H11120} <S20110>

   596 **

   597 ** Every file opened by the [sqlite3_vfs] xOpen method populates an

   598 ** [sqlite3_file] object (or, more commonly, a subclass of the

   599 ** [sqlite3_file] object) with a pointer to an instance of this object.

   600 ** This object defines the methods used to perform various operations

   601 ** against the open file represented by the [sqlite3_file] object.

   602 **

   603 ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or

   604 ** [SQLITE_SYNC_FULL].  The first choice is the normal fsync().

   605 ** The second choice is a Mac OS-X style fullsync.  The [SQLITE_SYNC_DATAONLY]

   606 ** flag may be ORed in to indicate that only the data of the file

   607 ** and not its inode needs to be synced.

   608 **

   609 ** The integer values to xLock() and xUnlock() are one of

   610 ** <ul>

   611 ** <li> [SQLITE_LOCK_NONE],

   612 ** <li> [SQLITE_LOCK_SHARED],

   613 ** <li> [SQLITE_LOCK_RESERVED],

   614 ** <li> [SQLITE_LOCK_PENDING], or

   615 ** <li> [SQLITE_LOCK_EXCLUSIVE].

   616 ** </ul>

   617 ** xLock() increases the lock. xUnlock() decreases the lock.

   618 ** The xCheckReservedLock() method checks whether any database connection,

   619 ** either in this process or in some other process, is holding a RESERVED,

   620 ** PENDING, or EXCLUSIVE lock on the file.  It returns true

   621 ** if such a lock exists and false otherwise.

   622 **

   623 ** The xFileControl() method is a generic interface that allows custom

   624 ** VFS implementations to directly control an open file using the

   625 ** [sqlite3_file_control()] interface.  The second "op" argument is an

   626 ** integer opcode.  The third argument is a generic pointer intended to

   627 ** point to a structure that may contain arguments or space in which to

   628 ** write return values.  Potential uses for xFileControl() might be

   629 ** functions to enable blocking locks with timeouts, to change the

   630 ** locking strategy (for example to use dot-file locks), to inquire

   631 ** about the status of a lock, or to break stale locks.  The SQLite

   632 ** core reserves all opcodes less than 100 for its own use.

   633 ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.

   634 ** Applications that define a custom xFileControl method should use opcodes

   635 ** greater than 100 to avoid conflicts.

   636 **

   637 ** The xSectorSize() method returns the sector size of the

   638 ** device that underlies the file.  The sector size is the

   639 ** minimum write that can be performed without disturbing

   640 ** other bytes in the file.  The xDeviceCharacteristics()

   641 ** method returns a bit vector describing behaviors of the

   642 ** underlying device:

   643 **

   644 ** <ul>

   645 ** <li> [SQLITE_IOCAP_ATOMIC]

   646 ** <li> [SQLITE_IOCAP_ATOMIC512]

   647 ** <li> [SQLITE_IOCAP_ATOMIC1K]

   648 ** <li> [SQLITE_IOCAP_ATOMIC2K]

   649 ** <li> [SQLITE_IOCAP_ATOMIC4K]

   650 ** <li> [SQLITE_IOCAP_ATOMIC8K]

   651 ** <li> [SQLITE_IOCAP_ATOMIC16K]

   652 ** <li> [SQLITE_IOCAP_ATOMIC32K]

   653 ** <li> [SQLITE_IOCAP_ATOMIC64K]

   654 ** <li> [SQLITE_IOCAP_SAFE_APPEND]

   655 ** <li> [SQLITE_IOCAP_SEQUENTIAL]

   656 ** </ul>

   657 **

   658 ** The SQLITE_IOCAP_ATOMIC property means that all writes of

   659 ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values

   660 ** mean that writes of blocks that are nnn bytes in size and

   661 ** are aligned to an address which is an integer multiple of

   662 ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means

   663 ** that when data is appended to a file, the data is appended

   664 ** first then the size of the file is extended, never the other

   665 ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that

   666 ** information is written to disk in the same order as calls

   667 ** to xWrite().

   668 */

   669 typedef struct sqlite3_io_methods sqlite3_io_methods;

   670 struct sqlite3_io_methods {

   671   int iVersion;

   672   int (*xClose)(sqlite3_file*);

   673   int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);

   674   int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);

   675   int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);

   676   int (*xSync)(sqlite3_file*, int flags);

   677   int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);

   678   int (*xLock)(sqlite3_file*, int);

   679   int (*xUnlock)(sqlite3_file*, int);

   680   int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);

   681   int (*xFileControl)(sqlite3_file*, int op, void *pArg);

   682   int (*xSectorSize)(sqlite3_file*);

   683   int (*xDeviceCharacteristics)(sqlite3_file*);

   684   /* Additional methods may be added in future releases */

   685 };

   686 

   687 /*

   688 ** CAPI3REF: Standard File Control Opcodes {H11310} <S30800>

   689 **

   690 ** These integer constants are opcodes for the xFileControl method

   691 ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]

   692 ** interface.

   693 **

   694 ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This

   695 ** opcode causes the xFileControl method to write the current state of

   696 ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],

   697 ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])

   698 ** into an integer that the pArg argument points to. This capability

   699 ** is used during testing and only needs to be supported when SQLITE_TEST

   700 ** is defined.

   701 */

   702 #define SQLITE_FCNTL_LOCKSTATE        1

   703 

   704 /*

   705 ** CAPI3REF: Mutex Handle {H17110} <S20130>

   706 **

   707 ** The mutex module within SQLite defines [sqlite3_mutex] to be an

   708 ** abstract type for a mutex object.  The SQLite core never looks

   709 ** at the internal representation of an [sqlite3_mutex].  It only

   710 ** deals with pointers to the [sqlite3_mutex] object.

   711 **

   712 ** Mutexes are created using [sqlite3_mutex_alloc()].

   713 */

   714 typedef struct sqlite3_mutex sqlite3_mutex;

   715 

   716 /*

   717 ** CAPI3REF: OS Interface Object {H11140} <S20100>

   718 **

   719 ** An instance of the sqlite3_vfs object defines the interface between

   720 ** the SQLite core and the underlying operating system.  The "vfs"

   721 ** in the name of the object stands for "virtual file system".

   722 **

   723 ** The value of the iVersion field is initially 1 but may be larger in

   724 ** future versions of SQLite.  Additional fields may be appended to this

   725 ** object when the iVersion value is increased.  Note that the structure

   726 ** of the sqlite3_vfs object changes in the transaction between

   727 ** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not

   728 ** modified.

   729 **

   730 ** The szOsFile field is the size of the subclassed [sqlite3_file]

   731 ** structure used by this VFS.  mxPathname is the maximum length of

   732 ** a pathname in this VFS.

   733 **

   734 ** Registered sqlite3_vfs objects are kept on a linked list formed by

   735 ** the pNext pointer.  The [sqlite3_vfs_register()]

   736 ** and [sqlite3_vfs_unregister()] interfaces manage this list

   737 ** in a thread-safe way.  The [sqlite3_vfs_find()] interface

   738 ** searches the list.  Neither the application code nor the VFS

   739 ** implementation should use the pNext pointer.

   740 **

   741 ** The pNext field is the only field in the sqlite3_vfs

   742 ** structure that SQLite will ever modify.  SQLite will only access

   743 ** or modify this field while holding a particular static mutex.

   744 ** The application should never modify anything within the sqlite3_vfs

   745 ** object once the object has been registered.

   746 **

   747 ** The zName field holds the name of the VFS module.  The name must

   748 ** be unique across all VFS modules.

   749 **

   750 ** {H11141} SQLite will guarantee that the zFilename parameter to xOpen

   751 ** is either a NULL pointer or string obtained

   752 ** from xFullPathname().  SQLite further guarantees that

   753 ** the string will be valid and unchanged until xClose() is

   754 ** called. {END}  Because of the previous sentense,

   755 ** the [sqlite3_file] can safely store a pointer to the

   756 ** filename if it needs to remember the filename for some reason.

   757 ** If the zFilename parameter is xOpen is a NULL pointer then xOpen

   758 ** must invite its own temporary name for the file.  Whenever the 

   759 ** xFilename parameter is NULL it will also be the case that the

   760 ** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].

   761 **

   762 ** {H11142} The flags argument to xOpen() includes all bits set in

   763 ** the flags argument to [sqlite3_open_v2()].  Or if [sqlite3_open()]

   764 ** or [sqlite3_open16()] is used, then flags includes at least

   765 ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END}

   766 ** If xOpen() opens a file read-only then it sets *pOutFlags to

   767 ** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be set.

   768 **

   769 ** {H11143} SQLite will also add one of the following flags to the xOpen()

   770 ** call, depending on the object being opened:

   771 **

   772 ** <ul>

   773 ** <li>  [SQLITE_OPEN_MAIN_DB]

   774 ** <li>  [SQLITE_OPEN_MAIN_JOURNAL]

   775 ** <li>  [SQLITE_OPEN_TEMP_DB]

   776 ** <li>  [SQLITE_OPEN_TEMP_JOURNAL]

   777 ** <li>  [SQLITE_OPEN_TRANSIENT_DB]

   778 ** <li>  [SQLITE_OPEN_SUBJOURNAL]

   779 ** <li>  [SQLITE_OPEN_MASTER_JOURNAL]

   780 ** </ul> {END}

   781 **

   782 ** The file I/O implementation can use the object type flags to

   783 ** change the way it deals with files.  For example, an application

   784 ** that does not care about crash recovery or rollback might make

   785 ** the open of a journal file a no-op.  Writes to this journal would

   786 ** also be no-ops, and any attempt to read the journal would return

   787 ** SQLITE_IOERR.  Or the implementation might recognize that a database

   788 ** file will be doing page-aligned sector reads and writes in a random

   789 ** order and set up its I/O subsystem accordingly.

   790 **

   791 ** SQLite might also add one of the following flags to the xOpen method:

   792 **

   793 ** <ul>

   794 ** <li> [SQLITE_OPEN_DELETEONCLOSE]

   795 ** <li> [SQLITE_OPEN_EXCLUSIVE]

   796 ** </ul>

   797 **

   798 ** {H11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be

   799 ** deleted when it is closed.  {H11146} The [SQLITE_OPEN_DELETEONCLOSE]

   800 ** will be set for TEMP  databases, journals and for subjournals.

   801 **

   802 ** {H11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened

   803 ** for exclusive access.  This flag is set for all files except

   804 ** for the main database file.

   805 **

   806 ** {H11148} At least szOsFile bytes of memory are allocated by SQLite

   807 ** to hold the  [sqlite3_file] structure passed as the third

   808 ** argument to xOpen. {END}  The xOpen method does not have to

   809 ** allocate the structure; it should just fill it in.

   810 **

   811 ** {H11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]

   812 ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to

   813 ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]

   814 ** to test whether a file is at least readable. {END}  The file can be a

   815 ** directory.

   816 **

   817 ** {H11150} SQLite will always allocate at least mxPathname+1 bytes for the

   818 ** output buffer xFullPathname. {H11151} The exact size of the output buffer

   819 ** is also passed as a parameter to both  methods. {END}  If the output buffer

   820 ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is

   821 ** handled as a fatal error by SQLite, vfs implementations should endeavor

   822 ** to prevent this by setting mxPathname to a sufficiently large value.

   823 **

   824 ** The xRandomness(), xSleep(), and xCurrentTime() interfaces

   825 ** are not strictly a part of the filesystem, but they are

   826 ** included in the VFS structure for completeness.

   827 ** The xRandomness() function attempts to return nBytes bytes

   828 ** of good-quality randomness into zOut.  The return value is

   829 ** the actual number of bytes of randomness obtained.

   830 ** The xSleep() method causes the calling thread to sleep for at

   831 ** least the number of microseconds given.  The xCurrentTime()

   832 ** method returns a Julian Day Number for the current date and time.

   833 */

   834 typedef struct sqlite3_vfs sqlite3_vfs;

   835 struct sqlite3_vfs {

   836   int iVersion;            /* Structure version number */

   837   int szOsFile;            /* Size of subclassed sqlite3_file */

   838   int mxPathname;          /* Maximum file pathname length */

   839   sqlite3_vfs *pNext;      /* Next registered VFS */

   840   const char *zName;       /* Name of this virtual file system */

   841   void *pAppData;          /* Pointer to application-specific data */

   842   int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,

   843                int flags, int *pOutFlags);

   844   int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);

   845   int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);

   846   int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);

   847   void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);

   848   void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);

   849   void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);

   850   void (*xDlClose)(sqlite3_vfs*, void*);

   851   int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);

   852   int (*xSleep)(sqlite3_vfs*, int microseconds);

   853   int (*xCurrentTime)(sqlite3_vfs*, double*);

   854   int (*xGetLastError)(sqlite3_vfs*, int, char *);

   855   /* New fields may be appended in figure versions.  The iVersion

   856   ** value will increment whenever this happens. */

   857 };

   858 

   859 /*

   860 ** CAPI3REF: Flags for the xAccess VFS method {H11190} <H11140>

   861 **

   862 ** {H11191} These integer constants can be used as the third parameter to

   863 ** the xAccess method of an [sqlite3_vfs] object. {END}  They determine

   864 ** what kind of permissions the xAccess method is looking for.

   865 ** {H11192} With SQLITE_ACCESS_EXISTS, the xAccess method

   866 ** simply checks whether the file exists.

   867 ** {H11193} With SQLITE_ACCESS_READWRITE, the xAccess method

   868 ** checks whether the file is both readable and writable.

   869 ** {H11194} With SQLITE_ACCESS_READ, the xAccess method

   870 ** checks whether the file is readable.

   871 */

   872 #define SQLITE_ACCESS_EXISTS    0

   873 #define SQLITE_ACCESS_READWRITE 1

   874 #define SQLITE_ACCESS_READ      2

   875 

   876 /*

   877 ** CAPI3REF: Initialize The SQLite Library {H10130} <S20000><S30100>

   878 **

   879 ** The sqlite3_initialize() routine initializes the

   880 ** SQLite library.  The sqlite3_shutdown() routine

   881 ** deallocates any resources that were allocated by sqlite3_initialize().

   882 **

   883 ** A call to sqlite3_initialize() is an "effective" call if it is

   884 ** the first time sqlite3_initialize() is invoked during the lifetime of

   885 ** the process, or if it is the first time sqlite3_initialize() is invoked

   886 ** following a call to sqlite3_shutdown().  Only an effective call

   887 ** of sqlite3_initialize() does any initialization.  All other calls

   888 ** are harmless no-ops.

   889 **

   890 ** Among other things, sqlite3_initialize() shall invoke

   891 ** sqlite3_os_init().  Similarly, sqlite3_shutdown()

   892 ** shall invoke sqlite3_os_end().

   893 **

   894 ** The sqlite3_initialize() routine returns SQLITE_OK on success.

   895 ** If for some reason, sqlite3_initialize() is unable to initialize

   896 ** the library (perhaps it is unable to allocate a needed resource such

   897 ** as a mutex) it returns an [error code] other than SQLITE_OK.

   898 **

   899 ** The sqlite3_initialize() routine is called internally by many other

   900 ** SQLite interfaces so that an application usually does not need to

   901 ** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]

   902 ** calls sqlite3_initialize() so the SQLite library will be automatically

   903 ** initialized when [sqlite3_open()] is called if it has not be initialized

   904 ** already.  However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT

   905 ** compile-time option, then the automatic calls to sqlite3_initialize()

   906 ** are omitted and the application must call sqlite3_initialize() directly

   907 ** prior to using any other SQLite interface.  For maximum portability,

   908 ** it is recommended that applications always invoke sqlite3_initialize()

   909 ** directly prior to using any other SQLite interface.  Future releases

   910 ** of SQLite may require this.  In other words, the behavior exhibited

   911 ** when SQLite is compiled with SQLITE_OMIT_AUTOINIT might become the

   912 ** default behavior in some future release of SQLite.

   913 **

   914 ** The sqlite3_os_init() routine does operating-system specific

   915 ** initialization of the SQLite library.  The sqlite3_os_end()

   916 ** routine undoes the effect of sqlite3_os_init().  Typical tasks

   917 ** performed by these routines include allocation or deallocation

   918 ** of static resources, initialization of global variables,

   919 ** setting up a default [sqlite3_vfs] module, or setting up

   920 ** a default configuration using [sqlite3_config()].

   921 **

   922 ** The application should never invoke either sqlite3_os_init()

   923 ** or sqlite3_os_end() directly.  The application should only invoke

   924 ** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()

   925 ** interface is called automatically by sqlite3_initialize() and

   926 ** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate

   927 ** implementations for sqlite3_os_init() and sqlite3_os_end()

   928 ** are built into SQLite when it is compiled for unix, windows, or os/2.

   929 ** When built for other platforms (using the SQLITE_OS_OTHER=1 compile-time

   930 ** option) the application must supply a suitable implementation for

   931 ** sqlite3_os_init() and sqlite3_os_end().  An application-supplied

   932 ** implementation of sqlite3_os_init() or sqlite3_os_end()

   933 ** must return SQLITE_OK on success and some other [error code] upon

   934 ** failure.

   935 */

   936 int sqlite3_initialize(void);

   937 int sqlite3_shutdown(void);

   938 int sqlite3_os_init(void);

   939 int sqlite3_os_end(void);

   940 

   941 /*

   942 ** CAPI3REF: Configuring The SQLite Library {H10145} <S20000><S30200>

   943 ** EXPERIMENTAL

   944 **

   945 ** The sqlite3_config() interface is used to make global configuration

   946 ** changes to SQLite in order to tune SQLite to the specific needs of

   947 ** the application.  The default configuration is recommended for most

   948 ** applications and so this routine is usually not necessary.  It is

   949 ** provided to support rare applications with unusual needs.

   950 **

   951 ** The sqlite3_config() interface is not threadsafe.  The application

   952 ** must insure that no other SQLite interfaces are invoked by other

   953 ** threads while sqlite3_config() is running.  Furthermore, sqlite3_config()

   954 ** may only be invoked prior to library initialization using

   955 ** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].

   956 ** Note, however, that sqlite3_config() can be called as part of the

   957 ** implementation of an application-defined [sqlite3_os_init()].

   958 **

   959 ** The first argument to sqlite3_config() is an integer

   960 ** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines

   961 ** what property of SQLite is to be configured.  Subsequent arguments

   962 ** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option]

   963 ** in the first argument.

   964 **

   965 ** When a configuration option is set, sqlite3_config() returns SQLITE_OK.

   966 ** If the option is unknown or SQLite is unable to set the option

   967 ** then this routine returns a non-zero [error code].

   968 */

   969 int sqlite3_config(int, ...);

   970 

   971 /*

   972 ** CAPI3REF: Configure database connections  {H10180} <S20000>

   973 ** EXPERIMENTAL

   974 **

   975 ** The sqlite3_db_config() interface is used to make configuration

   976 ** changes to a [database connection].  The interface is similar to

   977 ** [sqlite3_config()] except that the changes apply to a single

   978 ** [database connection] (specified in the first argument).  The

   979 ** sqlite3_db_config() interface can only be used immediately after

   980 ** the database connection is created using [sqlite3_open()],

   981 ** [sqlite3_open16()], or [sqlite3_open_v2()].  

   982 **

   983 ** The second argument to sqlite3_db_config(D,V,...)  is the

   984 ** configuration verb - an integer code that indicates what

   985 ** aspect of the [database connection] is being configured.

   986 ** The only choice for this value is [SQLITE_DBCONFIG_LOOKASIDE].

   987 ** New verbs are likely to be added in future releases of SQLite.

   988 ** Additional arguments depend on the verb.

   989 */

   990 int sqlite3_db_config(sqlite3*, int op, ...);

   991 

   992 /*

   993 ** CAPI3REF: Memory Allocation Routines {H10155} <S20120>

   994 ** EXPERIMENTAL

   995 **

   996 ** An instance of this object defines the interface between SQLite

   997 ** and low-level memory allocation routines.

   998 **

   999 ** This object is used in only one place in the SQLite interface.

  1000 ** A pointer to an instance of this object is the argument to

  1001 ** [sqlite3_config()] when the configuration option is

  1002 ** [SQLITE_CONFIG_MALLOC].  By creating an instance of this object

  1003 ** and passing it to [sqlite3_config()] during configuration, an

  1004 ** application can specify an alternative memory allocation subsystem

  1005 ** for SQLite to use for all of its dynamic memory needs.

  1006 **

  1007 ** Note that SQLite comes with a built-in memory allocator that is

  1008 ** perfectly adequate for the overwhelming majority of applications

  1009 ** and that this object is only useful to a tiny minority of applications

  1010 ** with specialized memory allocation requirements.  This object is

  1011 ** also used during testing of SQLite in order to specify an alternative

  1012 ** memory allocator that simulates memory out-of-memory conditions in

  1013 ** order to verify that SQLite recovers gracefully from such

  1014 ** conditions.

  1015 **

  1016 ** The xMalloc, xFree, and xRealloc methods must work like the

  1017 ** malloc(), free(), and realloc() functions from the standard library.

  1018 **

  1019 ** xSize should return the allocated size of a memory allocation

  1020 ** previously obtained from xMalloc or xRealloc.  The allocated size

  1021 ** is always at least as big as the requested size but may be larger.

  1022 **

  1023 ** The xRoundup method returns what would be the allocated size of

  1024 ** a memory allocation given a particular requested size.  Most memory

  1025 ** allocators round up memory allocations at least to the next multiple

  1026 ** of 8.  Some allocators round up to a larger multiple or to a power of 2.

  1027 **

  1028 ** The xInit method initializes the memory allocator.  (For example,

  1029 ** it might allocate any require mutexes or initialize internal data

  1030 ** structures.  The xShutdown method is invoked (indirectly) by

  1031 ** [sqlite3_shutdown()] and should deallocate any resources acquired

  1032 ** by xInit.  The pAppData pointer is used as the only parameter to

  1033 ** xInit and xShutdown.

  1034 */

  1035 typedef struct sqlite3_mem_methods sqlite3_mem_methods;

  1036 struct sqlite3_mem_methods {

  1037   void *(*xMalloc)(int);         /* Memory allocation function */

  1038   void (*xFree)(void*);          /* Free a prior allocation */

  1039   void *(*xRealloc)(void*,int);  /* Resize an allocation */

  1040   int (*xSize)(void*);           /* Return the size of an allocation */

  1041   int (*xRoundup)(int);          /* Round up request size to allocation size */

  1042   int (*xInit)(void*);           /* Initialize the memory allocator */

  1043   void (*xShutdown)(void*);      /* Deinitialize the memory allocator */

  1044   void *pAppData;                /* Argument to xInit() and xShutdown() */

  1045 };

  1046 

  1047 /*

  1048 ** CAPI3REF: Configuration Options {H10160} <S20000>

  1049 ** EXPERIMENTAL

  1050 **

  1051 ** These constants are the available integer configuration options that

  1052 ** can be passed as the first argument to the [sqlite3_config()] interface.

  1053 **

  1054 ** New configuration options may be added in future releases of SQLite.

  1055 ** Existing configuration options might be discontinued.  Applications

  1056 ** should check the return code from [sqlite3_config()] to make sure that

  1057 ** the call worked.  The [sqlite3_config()] interface will return a

  1058 ** non-zero [error code] if a discontinued or unsupported configuration option

  1059 ** is invoked.

  1060 **

  1061 ** <dl>

  1062 ** <dt>SQLITE_CONFIG_SINGLETHREAD</dt>

  1063 ** <dd>There are no arguments to this option.  This option disables

  1064 ** all mutexing and puts SQLite into a mode where it can only be used

  1065 ** by a single thread.</dd>

  1066 **

  1067 ** <dt>SQLITE_CONFIG_MULTITHREAD</dt>

  1068 ** <dd>There are no arguments to this option.  This option disables

  1069 ** mutexing on [database connection] and [prepared statement] objects.

  1070 ** The application is responsible for serializing access to

  1071 ** [database connections] and [prepared statements].  But other mutexes

  1072 ** are enabled so that SQLite will be safe to use in a multi-threaded

  1073 ** environment.</dd>

  1074 **

  1075 ** <dt>SQLITE_CONFIG_SERIALIZED</dt>

  1076 ** <dd>There are no arguments to this option.  This option enables

  1077 ** all mutexes including the recursive

  1078 ** mutexes on [database connection] and [prepared statement] objects.

  1079 ** In this mode (which is the default when SQLite is compiled with

  1080 ** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access

  1081 ** to [database connections] and [prepared statements] so that the

  1082 ** application is free to use the same [database connection] or the

  1083 ** same [prepared statement] in different threads at the same time.

  1084 **

  1085 ** <p>This configuration option merely sets the default mutex 

  1086 ** behavior to serialize access to [database connections].  Individual

  1087 ** [database connections] can override this setting

  1088 ** using the [SQLITE_OPEN_NOMUTEX] flag to [sqlite3_open_v2()].</p></dd>

  1089 **

  1090 ** <dt>SQLITE_CONFIG_MALLOC</dt>

  1091 ** <dd>This option takes a single argument which is a pointer to an

  1092 ** instance of the [sqlite3_mem_methods] structure.  The argument specifies

  1093 ** alternative low-level memory allocation routines to be used in place of

  1094 ** the memory allocation routines built into SQLite.</dd>

  1095 **

  1096 ** <dt>SQLITE_CONFIG_GETMALLOC</dt>

  1097 ** <dd>This option takes a single argument which is a pointer to an

  1098 ** instance of the [sqlite3_mem_methods] structure.  The [sqlite3_mem_methods]

  1099 ** structure is filled with the currently defined memory allocation routines.

  1100 ** This option can be used to overload the default memory allocation

  1101 ** routines with a wrapper that simulations memory allocation failure or

  1102 ** tracks memory usage, for example.</dd>

  1103 **

  1104 ** <dt>SQLITE_CONFIG_MEMSTATUS</dt>

  1105 ** <dd>This option takes single argument of type int, interpreted as a 

  1106 ** boolean, which enables or disables the collection of memory allocation 

  1107 ** statistics. When disabled, the following SQLite interfaces become 

  1108 ** non-operational:

  1109 **   <ul>

  1110 **   <li> [sqlite3_memory_used()]

  1111 **   <li> [sqlite3_memory_highwater()]

  1112 **   <li> [sqlite3_soft_heap_limit()]

  1113 **   <li> [sqlite3_status()]

  1114 **   </ul>

  1115 ** </dd>

  1116 **

  1117 ** <dt>SQLITE_CONFIG_SCRATCH</dt>

  1118 ** <dd>This option specifies a static memory buffer that SQLite can use for

  1119 ** scratch memory.  There are three arguments:  A pointer to the memory, the

  1120 ** size of each scratch buffer (sz), and the number of buffers (N).  The sz

  1121 ** argument must be a multiple of 16. The sz parameter should be a few bytes

  1122 ** larger than the actual scratch space required due internal overhead.

  1123 ** The first

  1124 ** argument should point to an allocation of at least sz*N bytes of memory.

  1125 ** SQLite will use no more than one scratch buffer at once per thread, so

  1126 ** N should be set to the expected maximum number of threads.  The sz

  1127 ** parameter should be 6 times the size of the largest database page size.

  1128 ** Scratch buffers are used as part of the btree balance operation.  If

  1129 ** The btree balancer needs additional memory beyond what is provided by

  1130 ** scratch buffers or if no scratch buffer space is specified, then SQLite

  1131 ** goes to [sqlite3_malloc()] to obtain the memory it needs.</dd>

  1132 **

  1133 ** <dt>SQLITE_CONFIG_PAGECACHE</dt>

  1134 ** <dd>This option specifies a static memory buffer that SQLite can use for