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 the right to make minor changes

    22 ** if 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 #ifndef _SQLITE3_H_

    34 #define _SQLITE3_H_

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

    36 

    37 /*

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

    39 */

    40 #ifdef __cplusplus

    41 extern "C" {

    42 #endif

    43 

    44 

    45 /*

    46 ** Add the ability to override 'extern'

    47 */

    48 #ifndef SQLITE_EXTERN

    49 # define SQLITE_EXTERN extern

    50 #endif

    51 

    52 #ifndef SQLITE_API

    53 # define SQLITE_API

    54 #endif

    55 

    56 

    57 /*

    58 ** These no-op macros are used in front of interfaces to mark those

    59 ** interfaces as either deprecated or experimental.  New applications

    60 ** should not use deprecated interfaces - they are support for backwards

    61 ** compatibility only.  Application writers should be aware that

    62 ** experimental interfaces are subject to change in point releases.

    63 **

    64 ** These macros used to resolve to various kinds of compiler magic that

    65 ** would generate warning messages when they were used.  But that

    66 ** compiler magic ended up generating such a flurry of bug reports

    67 ** that we have taken it all out and gone back to using simple

    68 ** noop macros.

    69 */

    70 #define SQLITE_DEPRECATED

    71 #define SQLITE_EXPERIMENTAL

    72 

    73 /*

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

    75 */

    76 #ifdef SQLITE_VERSION

    77 # undef SQLITE_VERSION

    78 #endif

    79 #ifdef SQLITE_VERSION_NUMBER

    80 # undef SQLITE_VERSION_NUMBER

    81 #endif

    82 

    83 /*

    84 ** CAPI3REF: Compile-Time Library Version Numbers

    85 **

    86 ** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header

    87 ** evaluates to a string literal that is the SQLite version in the

    88 ** format "X.Y.Z" where X is the major version number (always 3 for

    89 ** SQLite3) and Y is the minor version number and Z is the release number.)^

    90 ** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer

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

    92 ** numbers used in [SQLITE_VERSION].)^

    93 ** The SQLITE_VERSION_NUMBER for any given release of SQLite will also

    94 ** be larger than the release from which it is derived.  Either Y will

    95 ** be held constant and Z will be incremented or else Y will be incremented

    96 ** and Z will be reset to zero.

    97 **

    98 ** Since version 3.6.18, SQLite source code has been stored in the

    99 ** <a href="http://www.fossil-scm.org/">Fossil configuration management

   100 ** system</a>.  ^The SQLITE_SOURCE_ID macro evaluates to

   101 ** a string which identifies a particular check-in of SQLite

   102 ** within its configuration management system.  ^The SQLITE_SOURCE_ID

   103 ** string contains the date and time of the check-in (UTC) and an SHA1

   104 ** hash of the entire source tree.

   105 **

   106 ** See also: [sqlite3_libversion()],

   107 ** [sqlite3_libversion_number()], [sqlite3_sourceid()],

   108 ** [sqlite_version()] and [sqlite_source_id()].

   109 */

   110 #define SQLITE_VERSION        "3.7.8"

   111 #define SQLITE_VERSION_NUMBER 3007008

   112 #define SQLITE_SOURCE_ID      "2011-09-19 14:49:19 3e0da808d2f5b4d12046e05980ca04578f581177"

   113 

   114 /*

   115 ** CAPI3REF: Run-Time Library Version Numbers

   116 ** KEYWORDS: sqlite3_version, sqlite3_sourceid

   117 **

   118 ** These interfaces provide the same information as the [SQLITE_VERSION],

   119 ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros

   120 ** but are associated with the library instead of the header file.  ^(Cautious

   121 ** programmers might include assert() statements in their application to

   122 ** verify that values returned by these interfaces match the macros in

   123 ** the header, and thus insure that the application is

   124 ** compiled with matching library and header files.

   125 **

   126 ** <blockquote><pre>

   127 ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );

   128 ** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );

   129 ** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );

   130 ** </pre></blockquote>)^

   131 **

   132 ** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]

   133 ** macro.  ^The sqlite3_libversion() function returns a pointer to the

   134 ** to the sqlite3_version[] string constant.  The sqlite3_libversion()

   135 ** function is provided for use in DLLs since DLL users usually do not have

   136 ** direct access to string constants within the DLL.  ^The

   137 ** sqlite3_libversion_number() function returns an integer equal to

   138 ** [SQLITE_VERSION_NUMBER].  ^The sqlite3_sourceid() function returns 

   139 ** a pointer to a string constant whose value is the same as the 

   140 ** [SQLITE_SOURCE_ID] C preprocessor macro.

   141 **

   142 ** See also: [sqlite_version()] and [sqlite_source_id()].

   143 */

   144 SQLITE_API SQLITE_EXTERN const char sqlite3_version[];

   145 SQLITE_API const char *sqlite3_libversion(void);

   146 SQLITE_API const char *sqlite3_sourceid(void);

   147 SQLITE_API int sqlite3_libversion_number(void);

   148 

   149 /*

   150 ** CAPI3REF: Run-Time Library Compilation Options Diagnostics

   151 **

   152 ** ^The sqlite3_compileoption_used() function returns 0 or 1 

   153 ** indicating whether the specified option was defined at 

   154 ** compile time.  ^The SQLITE_ prefix may be omitted from the 

   155 ** option name passed to sqlite3_compileoption_used().  

   156 **

   157 ** ^The sqlite3_compileoption_get() function allows iterating

   158 ** over the list of options that were defined at compile time by

   159 ** returning the N-th compile time option string.  ^If N is out of range,

   160 ** sqlite3_compileoption_get() returns a NULL pointer.  ^The SQLITE_ 

   161 ** prefix is omitted from any strings returned by 

   162 ** sqlite3_compileoption_get().

   163 **

   164 ** ^Support for the diagnostic functions sqlite3_compileoption_used()

   165 ** and sqlite3_compileoption_get() may be omitted by specifying the 

   166 ** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.

   167 **

   168 ** See also: SQL functions [sqlite_compileoption_used()] and

   169 ** [sqlite_compileoption_get()] and the [compile_options pragma].

   170 */

   171 #ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS

   172 SQLITE_API int sqlite3_compileoption_used(const char *zOptName);

   173 SQLITE_API const char *sqlite3_compileoption_get(int N);

   174 #endif

   175 

   176 /*

   177 ** CAPI3REF: Test To See If The Library Is Threadsafe

   178 **

   179 ** ^The sqlite3_threadsafe() function returns zero if and only if

   180 ** SQLite was compiled mutexing code omitted due to the

   181 ** [SQLITE_THREADSAFE] compile-time option being set to 0.

   182 **

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

   184 ** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes

   185 ** are enabled and SQLite is threadsafe.  When the

   186 ** [SQLITE_THREADSAFE] macro is 0, 

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

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

   189 **

   190 ** Enabling mutexes incurs a measurable performance penalty.

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

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

   193 ** ^The default behavior is for mutexes to be enabled.

   194 **

   195 ** This interface can be used by an application to make sure that the

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

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

   198 **

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

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

   201 ** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but

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

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

   204 ** or [SQLITE_CONFIG_MUTEX].  ^(The return value of the

   205 ** sqlite3_threadsafe() function shows only the compile-time setting of

   206 ** thread safety, not any run-time changes to that setting made by

   207 ** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()

   208 ** is unchanged by calls to sqlite3_config().)^

   209 **

   210 ** See the [threading mode] documentation for additional information.

   211 */

   212 SQLITE_API int sqlite3_threadsafe(void);

   213 

   214 /*

   215 ** CAPI3REF: Database Connection Handle

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

   217 **

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

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

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

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

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

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

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

   225 ** sqlite3 object.

   226 */

   227 typedef struct sqlite3 sqlite3;

   228 

   229 /*

   230 ** CAPI3REF: 64-Bit Integer Types

   231 ** KEYWORDS: sqlite_int64 sqlite_uint64

   232 **

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

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

   235 **

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

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

   238 ** compatibility only.

   239 **

   240 ** ^The sqlite3_int64 and sqlite_int64 types can store integer values

   241 ** between -9223372036854775808 and +9223372036854775807 inclusive.  ^The

   242 ** sqlite3_uint64 and sqlite_uint64 types can store integer values 

   243 ** between 0 and +18446744073709551615 inclusive.

   244 */

   245 #ifdef SQLITE_INT64_TYPE

   246   typedef SQLITE_INT64_TYPE sqlite_int64;

   247   typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;

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

   249   typedef __int64 sqlite_int64;

   250   typedef unsigned __int64 sqlite_uint64;

   251 #else

   252   typedef long long int sqlite_int64;

   253   typedef unsigned long long int sqlite_uint64;

   254 #endif

   255 typedef sqlite_int64 sqlite3_int64;

   256 typedef sqlite_uint64 sqlite3_uint64;

   257 

   258 /*

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

   260 ** substitute integer for floating-point.

   261 */

   262 #ifdef SQLITE_OMIT_FLOATING_POINT

   263 # define double sqlite3_int64

   264 #endif

   265 

   266 /*

   267 ** CAPI3REF: Closing A Database Connection

   268 **

   269 ** ^The sqlite3_close() routine is the destructor for the [sqlite3] object.

   270 ** ^Calls to sqlite3_close() return SQLITE_OK if the [sqlite3] object is

   271 ** successfully destroyed and all associated resources are deallocated.

   272 **

   273 ** Applications must [sqlite3_finalize | finalize] all [prepared statements]

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

   275 ** the [sqlite3] object prior to attempting to close the object.  ^If

   276 ** sqlite3_close() is called on a [database connection] that still has

   277 ** outstanding [prepared statements] or [BLOB handles], then it returns

   278 ** SQLITE_BUSY.

   279 **

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

   281 ** the transaction is automatically rolled back.

   282 **

   283 ** The C parameter to [sqlite3_close(C)] must be either a NULL

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

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

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

   287 ** ^Calling sqlite3_close() with a NULL pointer argument is a 

   288 ** harmless no-op.

   289 */

   290 SQLITE_API int sqlite3_close(sqlite3 *);

   291 

   292 /*

   293 ** The type for a callback function.

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

   295 ** compatibility and is not documented.

   296 */

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

   298 

   299 /*

   300 ** CAPI3REF: One-Step Query Execution Interface

   301 **

   302 ** The sqlite3_exec() interface is a convenience wrapper around

   303 ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],

   304 ** that allows an application to run multiple statements of SQL

   305 ** without having to use a lot of C code. 

   306 **

   307 ** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,

   308 ** semicolon-separate SQL statements passed into its 2nd argument,

   309 ** in the context of the [database connection] passed in as its 1st

   310 ** argument.  ^If the callback function of the 3rd argument to

   311 ** sqlite3_exec() is not NULL, then it is invoked for each result row

   312 ** coming out of the evaluated SQL statements.  ^The 4th argument to

   313 ** sqlite3_exec() is relayed through to the 1st argument of each

   314 ** callback invocation.  ^If the callback pointer to sqlite3_exec()

   315 ** is NULL, then no callback is ever invoked and result rows are

   316 ** ignored.

   317 **

   318 ** ^If an error occurs while evaluating the SQL statements passed into

   319 ** sqlite3_exec(), then execution of the current statement stops and

   320 ** subsequent statements are skipped.  ^If the 5th parameter to sqlite3_exec()

   321 ** is not NULL then any error message is written into memory obtained

   322 ** from [sqlite3_malloc()] and passed back through the 5th parameter.

   323 ** To avoid memory leaks, the application should invoke [sqlite3_free()]

   324 ** on error message strings returned through the 5th parameter of

   325 ** of sqlite3_exec() after the error message string is no longer needed.

   326 ** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors

   327 ** occur, then sqlite3_exec() sets the pointer in its 5th parameter to

   328 ** NULL before returning.

   329 **

   330 ** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()

   331 ** routine returns SQLITE_ABORT without invoking the callback again and

   332 ** without running any subsequent SQL statements.

   333 **

   334 ** ^The 2nd argument to the sqlite3_exec() callback function is the

   335 ** number of columns in the result.  ^The 3rd argument to the sqlite3_exec()

   336 ** callback is an array of pointers to strings obtained as if from

   337 ** [sqlite3_column_text()], one for each column.  ^If an element of a

   338 ** result row is NULL then the corresponding string pointer for the

   339 ** sqlite3_exec() callback is a NULL pointer.  ^The 4th argument to the

   340 ** sqlite3_exec() callback is an array of pointers to strings where each

   341 ** entry represents the name of corresponding result column as obtained

   342 ** from [sqlite3_column_name()].

   343 **

   344 ** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer

   345 ** to an empty string, or a pointer that contains only whitespace and/or 

   346 ** SQL comments, then no SQL statements are evaluated and the database

   347 ** is not changed.

   348 **

   349 ** Restrictions:

   350 **

   351 ** <ul>

   352 ** <li> The application must insure that the 1st parameter to sqlite3_exec()

   353 **      is a valid and open [database connection].

   354 ** <li> The application must not close [database connection] specified by

   355 **      the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.

   356 ** <li> The application must not modify the SQL statement text passed into

   357 **      the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.

   358 ** </ul>

   359 */

   360 SQLITE_API int sqlite3_exec(

   361   sqlite3*,                                  /* An open database */

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

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

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

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

   366 );

   367 

   368 /*

   369 ** CAPI3REF: Result Codes

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

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

   372 **

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

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

   375 **

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

   377 **

   378 ** See also: [SQLITE_IOERR_READ | extended result codes],

   379 ** [sqlite3_vtab_on_conflict()] [SQLITE_ROLLBACK | result codes].

   380 */

   381 #define SQLITE_OK           0   /* Successful result */

   382 /* beginning-of-error-codes */

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

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

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

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

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

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

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

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

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

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

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

   394 #define SQLITE_NOTFOUND    12   /* Unknown opcode in sqlite3_file_control() */

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

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

   397 #define SQLITE_PROTOCOL    15   /* Database lock protocol error */

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

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

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

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

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

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

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

   405 #define SQLITE_AUTH        23   /* Authorization denied */

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

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

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

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

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

   411 /* end-of-error-codes */

   412 

   413 /*

   414 ** CAPI3REF: Extended Result Codes

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

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

   417 **

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

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

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

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

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

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

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

   425 ** on a per database connection basis using the

   426 ** [sqlite3_extended_result_codes()] API.

   427 **

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

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

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

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

   432 **

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

   434 ** be exactly zero.

   435 */

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   450 #define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))

   451 #define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))

   452 #define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))

   453 #define SQLITE_IOERR_SHMOPEN           (SQLITE_IOERR | (18<<8))

   454 #define SQLITE_IOERR_SHMSIZE           (SQLITE_IOERR | (19<<8))

   455 #define SQLITE_IOERR_SHMLOCK           (SQLITE_IOERR | (20<<8))

   456 #define SQLITE_IOERR_SHMMAP            (SQLITE_IOERR | (21<<8))

   457 #define SQLITE_IOERR_SEEK              (SQLITE_IOERR | (22<<8))

   458 #define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1<<8))

   459 #define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1<<8))

   460 #define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1<<8))

   461 #define SQLITE_CORRUPT_VTAB            (SQLITE_CORRUPT | (1<<8))

   462 #define SQLITE_READONLY_RECOVERY       (SQLITE_READONLY | (1<<8))

   463 #define SQLITE_READONLY_CANTLOCK       (SQLITE_READONLY | (2<<8))

   464 

   465 /*

   466 ** CAPI3REF: Flags For File Open Operations

   467 **

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

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

   470 ** in the 4th parameter to the [sqlite3_vfs.xOpen] method.

   471 */

   472 #define SQLITE_OPEN_READONLY         0x00000001  /* Ok for sqlite3_open_v2() */

   473 #define SQLITE_OPEN_READWRITE        0x00000002  /* Ok for sqlite3_open_v2() */

   474 #define SQLITE_OPEN_CREATE           0x00000004  /* Ok for sqlite3_open_v2() */

   475 #define SQLITE_OPEN_DELETEONCLOSE    0x00000008  /* VFS only */

   476 #define SQLITE_OPEN_EXCLUSIVE        0x00000010  /* VFS only */

   477 #define SQLITE_OPEN_AUTOPROXY        0x00000020  /* VFS only */

   478 #define SQLITE_OPEN_URI              0x00000040  /* Ok for sqlite3_open_v2() */

   479 #define SQLITE_OPEN_MAIN_DB          0x00000100  /* VFS only */

   480 #define SQLITE_OPEN_TEMP_DB          0x00000200  /* VFS only */

   481 #define SQLITE_OPEN_TRANSIENT_DB     0x00000400  /* VFS only */

   482 #define SQLITE_OPEN_MAIN_JOURNAL     0x00000800  /* VFS only */

   483 #define SQLITE_OPEN_TEMP_JOURNAL     0x00001000  /* VFS only */

   484 #define SQLITE_OPEN_SUBJOURNAL       0x00002000  /* VFS only */

   485 #define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */

   486 #define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */

   487 #define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */

   488 #define SQLITE_OPEN_SHAREDCACHE      0x00020000  /* Ok for sqlite3_open_v2() */

   489 #define SQLITE_OPEN_PRIVATECACHE     0x00040000  /* Ok for sqlite3_open_v2() */

   490 #define SQLITE_OPEN_WAL              0x00080000  /* VFS only */

   491 

   492 /* Reserved:                         0x00F00000 */

   493 

   494 /*

   495 ** CAPI3REF: Device Characteristics

   496 **

   497 ** The xDeviceCharacteristics method of the [sqlite3_io_methods]

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

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

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

   501 ** refers to.

   502 **

   503 ** The SQLITE_IOCAP_ATOMIC property means that all writes of

   504 ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values

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

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

   507 ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means

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

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

   510 ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that

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

   512 ** to xWrite().

   513 */

   514 #define SQLITE_IOCAP_ATOMIC                 0x00000001

   515 #define SQLITE_IOCAP_ATOMIC512              0x00000002

   516 #define SQLITE_IOCAP_ATOMIC1K               0x00000004

   517 #define SQLITE_IOCAP_ATOMIC2K               0x00000008

   518 #define SQLITE_IOCAP_ATOMIC4K               0x00000010

   519 #define SQLITE_IOCAP_ATOMIC8K               0x00000020

   520 #define SQLITE_IOCAP_ATOMIC16K              0x00000040

   521 #define SQLITE_IOCAP_ATOMIC32K              0x00000080

   522 #define SQLITE_IOCAP_ATOMIC64K              0x00000100

   523 #define SQLITE_IOCAP_SAFE_APPEND            0x00000200

   524 #define SQLITE_IOCAP_SEQUENTIAL             0x00000400

   525 #define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN  0x00000800

   526 

   527 /*

   528 ** CAPI3REF: File Locking Levels

   529 **

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

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

   532 ** of an [sqlite3_io_methods] object.

   533 */

   534 #define SQLITE_LOCK_NONE          0

   535 #define SQLITE_LOCK_SHARED        1

   536 #define SQLITE_LOCK_RESERVED      2

   537 #define SQLITE_LOCK_PENDING       3

   538 #define SQLITE_LOCK_EXCLUSIVE     4

   539 

   540 /*

   541 ** CAPI3REF: Synchronization Type Flags

   542 **

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

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

   545 ** these integer values as the second argument.

   546 **

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

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

   549 ** information need not be flushed. If the lower four bits of the flag

   550 ** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.

   551 ** If the lower four bits equal SQLITE_SYNC_FULL, that means

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

   553 **

   554 ** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags

   555 ** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL

   556 ** settings.  The [synchronous pragma] determines when calls to the

   557 ** xSync VFS method occur and applies uniformly across all platforms.

   558 ** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how

   559 ** energetic or rigorous or forceful the sync operations are and

   560 ** only make a difference on Mac OSX for the default SQLite code.

   561 ** (Third-party VFS implementations might also make the distinction

   562 ** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the

   563 ** operating systems natively supported by SQLite, only Mac OSX

   564 ** cares about the difference.)

   565 */

   566 #define SQLITE_SYNC_NORMAL        0x00002

   567 #define SQLITE_SYNC_FULL          0x00003

   568 #define SQLITE_SYNC_DATAONLY      0x00010

   569 

   570 /*

   571 ** CAPI3REF: OS Interface Open File Handle

   572 **

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

   574 ** [sqlite3_vfs | OS interface layer].  Individual OS interface

   575 ** implementations will

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

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

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

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

   580 */

   581 typedef struct sqlite3_file sqlite3_file;

   582 struct sqlite3_file {

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

   584 };

   585 

   586 /*

   587 ** CAPI3REF: OS Interface File Virtual Methods Object

   588 **

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

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

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

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

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

   594 **

   595 ** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element 

   596 ** to a non-NULL pointer, then the sqlite3_io_methods.xClose method

   597 ** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed.  The

   598 ** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]

   599 ** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element

   600 ** to NULL.

   601 **

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

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

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

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

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

   607 **

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

   609 ** <ul>

   610 ** <li> [SQLITE_LOCK_NONE],

   611 ** <li> [SQLITE_LOCK_SHARED],

   612 ** <li> [SQLITE_LOCK_RESERVED],

   613 ** <li> [SQLITE_LOCK_PENDING], or

   614 ** <li> [SQLITE_LOCK_EXCLUSIVE].

   615 ** </ul>

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

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

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

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

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

   621 **

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

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

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

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

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

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

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

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

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

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

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

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

   634 ** greater than 100 to avoid conflicts.  VFS implementations should

   635 ** return [SQLITE_NOTFOUND] for file control opcodes that they do not

   636 ** recognize.

   637 **

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

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

   640 ** minimum write that can be performed without disturbing

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

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

   643 ** underlying device:

   644 **

   645 ** <ul>

   646 ** <li> [SQLITE_IOCAP_ATOMIC]

   647 ** <li> [SQLITE_IOCAP_ATOMIC512]

   648 ** <li> [SQLITE_IOCAP_ATOMIC1K]

   649 ** <li> [SQLITE_IOCAP_ATOMIC2K]

   650 ** <li> [SQLITE_IOCAP_ATOMIC4K]

   651 ** <li> [SQLITE_IOCAP_ATOMIC8K]

   652 ** <li> [SQLITE_IOCAP_ATOMIC16K]

   653 ** <li> [SQLITE_IOCAP_ATOMIC32K]

   654 ** <li> [SQLITE_IOCAP_ATOMIC64K]

   655 ** <li> [SQLITE_IOCAP_SAFE_APPEND]

   656 ** <li> [SQLITE_IOCAP_SEQUENTIAL]

   657 ** </ul>

   658 **

   659 ** The SQLITE_IOCAP_ATOMIC property means that all writes of

   660 ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values

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

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

   663 ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means

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

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

   666 ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that

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

   668 ** to xWrite().

   669 **

   670 ** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill

   671 ** in the unread portions of the buffer with zeros.  A VFS that

   672 ** fails to zero-fill short reads might seem to work.  However,

   673 ** failure to zero-fill short reads will eventually lead to

   674 ** database corruption.

   675 */

   676 typedef struct sqlite3_io_methods sqlite3_io_methods;

   677 struct sqlite3_io_methods {

   678   int iVersion;

   679   int (*xClose)(sqlite3_file*);

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

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

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

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

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

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

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

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

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

   689   int (*xSectorSize)(sqlite3_file*);

   690   int (*xDeviceCharacteristics)(sqlite3_file*);

   691   /* Methods above are valid for version 1 */

   692   int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);

   693   int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);

   694   void (*xShmBarrier)(sqlite3_file*);

   695   int (*xShmUnmap)(sqlite3_file*, int deleteFlag);

   696   /* Methods above are valid for version 2 */

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

   698 };

   699 

   700 /*

   701 ** CAPI3REF: Standard File Control Opcodes

   702 **

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

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

   705 ** interface.

   706 **

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

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

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

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

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

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

   713 ** is defined.

   714 **

   715 ** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS

   716 ** layer a hint of how large the database file will grow to be during the

   717 ** current transaction.  This hint is not guaranteed to be accurate but it

   718 ** is often close.  The underlying VFS might choose to preallocate database

   719 ** file space based on this hint in order to help writes to the database

   720 ** file run faster.

   721 **

   722 ** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS

   723 ** extends and truncates the database file in chunks of a size specified

   724 ** by the user. The fourth argument to [sqlite3_file_control()] should 

   725 ** point to an integer (type int) containing the new chunk-size to use

   726 ** for the nominated database. Allocating database file space in large

   727 ** chunks (say 1MB at a time), may reduce file-system fragmentation and

   728 ** improve performance on some systems.

   729 **

   730 ** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer

   731 ** to the [sqlite3_file] object associated with a particular database

   732 ** connection.  See the [sqlite3_file_control()] documentation for

   733 ** additional information.

   734 **

   735 ** ^(The [SQLITE_FCNTL_SYNC_OMITTED] opcode is generated internally by

   736 ** SQLite and sent to all VFSes in place of a call to the xSync method

   737 ** when the database connection has [PRAGMA synchronous] set to OFF.)^

   738 ** Some specialized VFSes need this signal in order to operate correctly

   739 ** when [PRAGMA synchronous | PRAGMA synchronous=OFF] is set, but most 

   740 ** VFSes do not need this signal and should silently ignore this opcode.

   741 ** Applications should not call [sqlite3_file_control()] with this

   742 ** opcode as doing so may disrupt the operation of the specialized VFSes

   743 ** that do require it.  

   744 **

   745 ** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic

   746 ** retry counts and intervals for certain disk I/O operations for the

   747 ** windows [VFS] in order to work to provide robustness against

   748 ** anti-virus programs.  By default, the windows VFS will retry file read,

   749 ** file write, and file delete opertions up to 10 times, with a delay

   750 ** of 25 milliseconds before the first retry and with the delay increasing

   751 ** by an additional 25 milliseconds with each subsequent retry.  This

   752 ** opcode allows those to values (10 retries and 25 milliseconds of delay)

   753 ** to be adjusted.  The values are changed for all database connections

   754 ** within the same process.  The argument is a pointer to an array of two

   755 ** integers where the first integer i the new retry count and the second

   756 ** integer is the delay.  If either integer is negative, then the setting

   757 ** is not changed but instead the prior value of that setting is written

   758 ** into the array entry, allowing the current retry settings to be

   759 ** interrogated.  The zDbName parameter is ignored.

   760 **

   761 ** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the

   762 ** persistent [WAL | Write AHead Log] setting.  By default, the auxiliary

   763 ** write ahead log and shared memory files used for transaction control

   764 ** are automatically deleted when the latest connection to the database

   765 ** closes.  Setting persistent WAL mode causes those files to persist after

   766 ** close.  Persisting the files is useful when other processes that do not

   767 ** have write permission on the directory containing the database file want

   768 ** to read the database file, as the WAL and shared memory files must exist

   769 ** in order for the database to be readable.  The fourth parameter to

   770 ** [sqlite3_file_control()] for this opcode should be a pointer to an integer.

   771 ** That integer is 0 to disable persistent WAL mode or 1 to enable persistent

   772 ** WAL mode.  If the integer is -1, then it is overwritten with the current

   773 ** WAL persistence setting.

   774 ** 

   775 */

   776 #define SQLITE_FCNTL_LOCKSTATE        1

   777 #define SQLITE_GET_LOCKPROXYFILE      2

   778 #define SQLITE_SET_LOCKPROXYFILE      3

   779 #define SQLITE_LAST_ERRNO             4

   780 #define SQLITE_FCNTL_SIZE_HINT        5

   781 #define SQLITE_FCNTL_CHUNK_SIZE       6

   782 #define SQLITE_FCNTL_FILE_POINTER     7

   783 #define SQLITE_FCNTL_SYNC_OMITTED     8

   784 #define SQLITE_FCNTL_WIN32_AV_RETRY   9

   785 #define SQLITE_FCNTL_PERSIST_WAL     10

   786 

   787 /*

   788 ** CAPI3REF: Mutex Handle

   789 **

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

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

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

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

   794 **

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

   796 */

   797 typedef struct sqlite3_mutex sqlite3_mutex;

   798 

   799 /*

   800 ** CAPI3REF: OS Interface Object

   801 **

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

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

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

   805 ** the [VFS | VFS documentation] for further information.

   806 **

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

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

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

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

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

   812 ** modified.

   813 **

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

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

   816 ** a pathname in this VFS.

   817 **

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

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

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

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

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

   823 ** implementation should use the pNext pointer.

   824 **

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

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

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

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

   829 ** object once the object has been registered.

   830 **

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

   832 ** be unique across all VFS modules.

   833 **

   834 ** [[sqlite3_vfs.xOpen]]

   835 ** ^SQLite guarantees that the zFilename parameter to xOpen

   836 ** is either a NULL pointer or string obtained

   837 ** from xFullPathname() with an optional suffix added.

   838 ** ^If a suffix is added to the zFilename parameter, it will

   839 ** consist of a single "-" character followed by no more than

   840 ** 10 alphanumeric and/or "-" characters.

   841 ** ^SQLite further guarantees that

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

   843 ** called. Because of the previous sentence,

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

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

   846 ** If the zFilename parameter to xOpen is a NULL pointer then xOpen

   847 ** must invent its own temporary name for the file.  ^Whenever the 

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

   849 ** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].

   850 **

   851 ** The flags argument to xOpen() includes all bits set in

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

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

   854 ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. 

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

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

   857 **

   858 ** ^(SQLite will also add one of the following flags to the xOpen()

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

   860 **

   861 ** <ul>

   862 ** <li>  [SQLITE_OPEN_MAIN_DB]

   863 ** <li>  [SQLITE_OPEN_MAIN_JOURNAL]

   864 ** <li>  [SQLITE_OPEN_TEMP_DB]

   865 ** <li>  [SQLITE_OPEN_TEMP_JOURNAL]

   866 ** <li>  [SQLITE_OPEN_TRANSIENT_DB]

   867 ** <li>  [SQLITE_OPEN_SUBJOURNAL]

   868 ** <li>  [SQLITE_OPEN_MASTER_JOURNAL]

   869 ** <li>  [SQLITE_OPEN_WAL]

   870 ** </ul>)^

   871 **

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

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

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

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

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

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

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

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

   880 **

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

   882 **

   883 ** <ul>

   884 ** <li> [SQLITE_OPEN_DELETEONCLOSE]

   885 ** <li> [SQLITE_OPEN_EXCLUSIVE]

   886 ** </ul>

   887 **

   888 ** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be

   889 ** deleted when it is closed.  ^The [SQLITE_OPEN_DELETEONCLOSE]

   890 ** will be set for TEMP databases and their journals, transient

   891 ** databases, and subjournals.

   892 **

   893 ** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction

   894 ** with the [SQLITE_OPEN_CREATE] flag, which are both directly

   895 ** analogous to the O_EXCL and O_CREAT flags of the POSIX open()

   896 ** API.  The SQLITE_OPEN_EXCLUSIVE flag, when paired with the 

   897 ** SQLITE_OPEN_CREATE, is used to indicate that file should always

   898 ** be created, and that it is an error if it already exists.

   899 ** It is <i>not</i> used to indicate the file should be opened 

   900 ** for exclusive access.

   901 **

   902 ** ^At least szOsFile bytes of memory are allocated by SQLite

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

   904 ** argument to xOpen.  The xOpen method does not have to

   905 ** allocate the structure; it should just fill it in.  Note that

   906 ** the xOpen method must set the sqlite3_file.pMethods to either

   907 ** a valid [sqlite3_io_methods] object or to NULL.  xOpen must do

   908 ** this even if the open fails.  SQLite expects that the sqlite3_file.pMethods

   909 ** element will be valid after xOpen returns regardless of the success

   910 ** or failure of the xOpen call.

   911 **

   912 ** [[sqlite3_vfs.xAccess]]

   913 ** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]

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

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

   916 ** to test whether a file is at least readable.   The file can be a

   917 ** directory.

   918 **

   919 ** ^SQLite will always allocate at least mxPathname+1 bytes for the

   920 ** output buffer xFullPathname.  The exact size of the output buffer

   921 ** is also passed as a parameter to both  methods. If the output buffer

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

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

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

   925 **

   926 ** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()

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

   928 ** included in the VFS structure for completeness.

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

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

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

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

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

   934 ** method returns a Julian Day Number for the current date and time as

   935 ** a floating point value.

   936 ** ^The xCurrentTimeInt64() method returns, as an integer, the Julian

   937 ** Day Number multiplied by 86400000 (the number of milliseconds in 

   938 ** a 24-hour day).  

   939 ** ^SQLite will use the xCurrentTimeInt64() method to get the current

   940 ** date and time if that method is available (if iVersion is 2 or 

   941 ** greater and the function pointer is not NULL) and will fall back

   942 ** to xCurrentTime() if xCurrentTimeInt64() is unavailable.

   943 **

   944 ** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces

   945 ** are not used by the SQLite core.  These optional interfaces are provided

   946 ** by some VFSes to facilitate testing of the VFS code. By overriding 

   947 ** system calls with functions under its control, a test program can

   948 ** simulate faults and error conditions that would otherwise be difficult

   949 ** or impossible to induce.  The set of system calls that can be overridden

   950 ** varies from one VFS to another, and from one version of the same VFS to the

   951 ** next.  Applications that use these interfaces must be prepared for any

   952 ** or all of these interfaces to be NULL or for their behavior to change

   953 ** from one release to the next.  Applications must not attempt to access

   954 ** any of these methods if the iVersion of the VFS is less than 3.

   955 */

   956 typedef struct sqlite3_vfs sqlite3_vfs;

   957 typedef void (*sqlite3_syscall_ptr)(void);

   958 struct sqlite3_vfs {

   959   int iVersion;            /* Structure version number (currently 3) */

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

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

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

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

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

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

   966                int flags, int *pOutFlags);

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

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

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

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

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

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

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

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

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

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

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

   978   /*

   979   ** The methods above are in version 1 of the sqlite_vfs object

   980   ** definition.  Those that follow are added in version 2 or later

   981   */

   982   int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);

   983   /*

   984   ** The methods above are in versions 1 and 2 of the sqlite_vfs object.

   985   ** Those below are for version 3 and greater.

   986   */

   987   int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);

   988   sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);

   989   const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);

   990   /*

   991   ** The methods above are in versions 1 through 3 of the sqlite_vfs object.

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

   993   ** value will increment whenever this happens. 

   994   */

   995 };

   996 

   997 /*

   998 ** CAPI3REF: Flags for the xAccess VFS method

   999 **

  1000 ** These integer constants can be used as the third parameter to

  1001 ** the xAccess method of an [sqlite3_vfs] object.  They determine

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

  1003 ** With SQLITE_ACCESS_EXISTS, the xAccess method

  1004 ** simply checks whether the file exists.

  1005 ** With SQLITE_ACCESS_READWRITE, the xAccess method

  1006 ** checks whether the named directory is both readable and writable

  1007 ** (in other words, if files can be added, removed, and renamed within

  1008 ** the directory).

  1009 ** The SQLITE_ACCESS_READWRITE constant is currently used only by the

  1010 ** [temp_store_directory pragma], though this could change in a future

  1011 ** release of SQLite.

  1012 ** With SQLITE_ACCESS_READ, the xAccess method

  1013 ** checks whether the file is readable.  The SQLITE_ACCESS_READ constant is

  1014 ** currently unused, though it might be used in a future release of

  1015 ** SQLite.

  1016 */

  1017 #define SQLITE_ACCESS_EXISTS    0

  1018 #define SQLITE_ACCESS_READWRITE 1   /* Used by PRAGMA temp_store_directory */

  1019 #define SQLITE_ACCESS_READ      2   /* Unused */

  1020 

  1021 /*

  1022 ** CAPI3REF: Flags for the xShmLock VFS method

  1023 **

  1024 ** These integer constants define the various locking operations

  1025 ** allowed by the xShmLock method of [sqlite3_io_methods].  The

  1026 ** following are the only legal combinations of flags to the

  1027 ** xShmLock method:

  1028 **

  1029 ** <ul>

  1030 ** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_SHARED

  1031 ** <li>  SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE

  1032 ** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED

  1033 ** <li>  SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE

  1034 ** </ul>

  1035 **

  1036 ** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as

  1037 ** was given no the corresponding lock.  

  1038 **

  1039 ** The xShmLock method can transition between unlocked and SHARED or

  1040 ** between unlocked and EXCLUSIVE.  It cannot transition between SHARED

  1041 ** and EXCLUSIVE.

  1042 */

  1043 #define SQLITE_SHM_UNLOCK       1

  1044 #define SQLITE_SHM_LOCK         2

  1045 #define SQLITE_SHM_SHARED       4

  1046 #define SQLITE_SHM_EXCLUSIVE    8

  1047 

  1048 /*

  1049 ** CAPI3REF: Maximum xShmLock index

  1050 **

  1051 ** The xShmLock method on [sqlite3_io_methods] may use values

  1052 ** between 0 and this upper bound as its "offset" argument.

  1053 ** The SQLite core will never attempt to acquire or release a

  1054 ** lock outside of this range

  1055 */

  1056 #define SQLITE_SHM_NLOCK        8

  1057 

  1058 

  1059 /*

  1060 ** CAPI3REF: Initialize The SQLite Library

  1061 **

  1062 ** ^The sqlite3_initialize() routine initializes the

  1063 ** SQLite library.  ^The sqlite3_shutdown() routine

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

  1065 ** These routines are designed to aid in process initialization and

  1066 ** shutdown on embedded systems.  Workstation applications using

  1067 ** SQLite normally do not need to invoke either of these routines.

  1068 **

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

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

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

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

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

  1074 ** are harmless no-ops.)^

  1075 **

  1076 ** A call to sqlite3_shutdown() is an "effective" call if it is the first

  1077 ** call to sqlite3_shutdown() since the last sqlite3_initialize().  ^(Only

  1078 ** an effective call to sqlite3_shutdown() does any deinitialization.

  1079 ** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^

  1080 **

  1081 ** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()

  1082 ** is not.  The sqlite3_shutdown() interface must only be called from a

  1083 ** single thread.  All open [database connections] must be closed and all

  1084 ** other SQLite resources must be deallocated prior to invoking

  1085 ** sqlite3_shutdown().

  1086 **

  1087 ** Among other things, ^sqlite3_initialize() will invoke

  1088 ** sqlite3_os_init().  Similarly, ^sqlite3_shutdown()

  1089 ** will invoke sqlite3_os_end().

  1090 **

  1091 ** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.

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

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

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

  1095 **

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

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

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

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

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

  1101 ** already.  ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]

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

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

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

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

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

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

  1108 ** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the

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

  1110 **

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

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

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

  1114 ** performed by these routines include allocation or deallocation

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

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

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

  1118 **

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

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

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

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

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

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

  1125 ** are built into SQLite when it is compiled for Unix, Windows, or OS/2.

  1126 ** When [custom builds | built for other platforms]

  1127 ** (using the [SQLITE_OS_OTHER=1] compile-time

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

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

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

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

  1132 ** failure.

  1133 */

  1134 SQLITE_API int sqlite3_initialize(void);

  1135 SQLITE_API int sqlite3_shutdown(void);