PageRenderTime 113ms CodeModel.GetById 79ms app.highlight 14ms RepoModel.GetById 1ms app.codeStats 2ms

/ghost/sqlite3.h

http://ghostcb.googlecode.com/
C++ Header | 5626 lines | 730 code | 146 blank | 4750 comment | 1 complexity | 7a31c1a83ea8b3a7c8f0c4bb503a4f80 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   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.458 2009/06/19 22:50:31 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
  43extern "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** These no-op macros are used in front of interfaces to mark those
  56** interfaces as either deprecated or experimental.  New applications
  57** should not use deprecated intrfaces - they are support for backwards
  58** compatibility only.  Application writers should be aware that
  59** experimental interfaces are subject to change in point releases.
  60**
  61** These macros used to resolve to various kinds of compiler magic that
  62** would generate warning messages when they were used.  But that
  63** compiler magic ended up generating such a flurry of bug reports
  64** that we have taken it all out and gone back to using simple
  65** noop macros.
  66*/
  67#define SQLITE_DEPRECATED
  68#define SQLITE_EXPERIMENTAL
  69
  70/*
  71** Ensure these symbols were not defined by some previous header file.
  72*/
  73#ifdef SQLITE_VERSION
  74# undef SQLITE_VERSION
  75#endif
  76#ifdef SQLITE_VERSION_NUMBER
  77# undef SQLITE_VERSION_NUMBER
  78#endif
  79
  80/*
  81** CAPI3REF: Compile-Time Library Version Numbers {H10010} <S60100>
  82**
  83** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in
  84** the sqlite3.h file specify the version of SQLite with which
  85** that header file is associated.
  86**
  87** The "version" of SQLite is a string of the form "X.Y.Z".
  88** The phrase "alpha" or "beta" might be appended after the Z.
  89** The X value is major version number always 3 in SQLite3.
  90** The X value only changes when backwards compatibility is
  91** broken and we intend to never break backwards compatibility.
  92** The Y value is the minor version number and only changes when
  93** there are major feature enhancements that are forwards compatible
  94** but not backwards compatible.
  95** The Z value is the release number and is incremented with
  96** each release but resets back to 0 whenever Y is incremented.
  97**
  98** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
  99**
 100** Requirements: [H10011] [H10014]
 101*/
 102#define SQLITE_VERSION         "3.6.16"
 103#define SQLITE_VERSION_NUMBER  3006016
 104
 105/*
 106** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100>
 107** KEYWORDS: sqlite3_version
 108**
 109** These features provide the same information as the [SQLITE_VERSION]
 110** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated
 111** with the library instead of the header file.  Cautious programmers might
 112** include a check in their application to verify that
 113** sqlite3_libversion_number() always returns the value
 114** [SQLITE_VERSION_NUMBER].
 115**
 116** The sqlite3_libversion() function returns the same information as is
 117** in the sqlite3_version[] string constant.  The function is provided
 118** for use in DLLs since DLL users usually do not have direct access to string
 119** constants within the DLL.
 120**
 121** Requirements: [H10021] [H10022] [H10023]
 122*/
 123SQLITE_EXTERN const char sqlite3_version[];
 124const char *sqlite3_libversion(void);
 125int sqlite3_libversion_number(void);
 126
 127/*
 128** CAPI3REF: Test To See If The Library Is Threadsafe {H10100} <S60100>
 129**
 130** SQLite can be compiled with or without mutexes.  When
 131** the [SQLITE_THREADSAFE] C preprocessor macro 1 or 2, mutexes
 132** are enabled and SQLite is threadsafe.  When the
 133** [SQLITE_THREADSAFE] macro is 0, 
 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** See the [threading mode] documentation for additional information.
 156**
 157** Requirements: [H10101] [H10102]
 158*/
 159int sqlite3_threadsafe(void);
 160
 161/*
 162** CAPI3REF: Database Connection Handle {H12000} <S40200>
 163** KEYWORDS: {database connection} {database connections}
 164**
 165** Each open SQLite database is represented by a pointer to an instance of
 166** the opaque structure named "sqlite3".  It is useful to think of an sqlite3
 167** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and
 168** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
 169** is its destructor.  There are many other interfaces (such as
 170** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
 171** [sqlite3_busy_timeout()] to name but three) that are methods on an
 172** sqlite3 object.
 173*/
 174typedef struct sqlite3 sqlite3;
 175
 176/*
 177** CAPI3REF: 64-Bit Integer Types {H10200} <S10110>
 178** KEYWORDS: sqlite_int64 sqlite_uint64
 179**
 180** Because there is no cross-platform way to specify 64-bit integer types
 181** SQLite includes typedefs for 64-bit signed and unsigned integers.
 182**
 183** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
 184** The sqlite_int64 and sqlite_uint64 types are supported for backwards
 185** compatibility only.
 186**
 187** Requirements: [H10201] [H10202]
 188*/
 189#ifdef SQLITE_INT64_TYPE
 190  typedef SQLITE_INT64_TYPE sqlite_int64;
 191  typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
 192#elif defined(_MSC_VER) || defined(__BORLANDC__)
 193  typedef __int64 sqlite_int64;
 194  typedef unsigned __int64 sqlite_uint64;
 195#else
 196  typedef long long int sqlite_int64;
 197  typedef unsigned long long int sqlite_uint64;
 198#endif
 199typedef sqlite_int64 sqlite3_int64;
 200typedef sqlite_uint64 sqlite3_uint64;
 201
 202/*
 203** If compiling for a processor that lacks floating point support,
 204** substitute integer for floating-point.
 205*/
 206#ifdef SQLITE_OMIT_FLOATING_POINT
 207# define double sqlite3_int64
 208#endif
 209
 210/*
 211** CAPI3REF: Closing A Database Connection {H12010} <S30100><S40200>
 212**
 213** This routine is the destructor for the [sqlite3] object.
 214**
 215** Applications should [sqlite3_finalize | finalize] all [prepared statements]
 216** and [sqlite3_blob_close | close] all [BLOB handles] associated with
 217** the [sqlite3] object prior to attempting to close the object.
 218** The [sqlite3_next_stmt()] interface can be used to locate all
 219** [prepared statements] associated with a [database connection] if desired.
 220** Typical code might look like this:
 221**
 222** <blockquote><pre>
 223** sqlite3_stmt *pStmt;
 224** while( (pStmt = sqlite3_next_stmt(db, 0))!=0 ){
 225** &nbsp;   sqlite3_finalize(pStmt);
 226** }
 227** </pre></blockquote>
 228**
 229** If [sqlite3_close()] is invoked while a transaction is open,
 230** the transaction is automatically rolled back.
 231**
 232** The C parameter to [sqlite3_close(C)] must be either a NULL
 233** pointer or an [sqlite3] object pointer obtained
 234** from [sqlite3_open()], [sqlite3_open16()], or
 235** [sqlite3_open_v2()], and not previously closed.
 236**
 237** Requirements:
 238** [H12011] [H12012] [H12013] [H12014] [H12015] [H12019]
 239*/
 240int sqlite3_close(sqlite3 *);
 241
 242/*
 243** The type for a callback function.
 244** This is legacy and deprecated.  It is included for historical
 245** compatibility and is not documented.
 246*/
 247typedef int (*sqlite3_callback)(void*,int,char**, char**);
 248
 249/*
 250** CAPI3REF: One-Step Query Execution Interface {H12100} <S10000>
 251**
 252** The sqlite3_exec() interface is a convenient way of running one or more
 253** SQL statements without having to write a lot of C code.  The UTF-8 encoded
 254** SQL statements are passed in as the second parameter to sqlite3_exec().
 255** The statements are evaluated one by one until either an error or
 256** an interrupt is encountered, or until they are all done.  The 3rd parameter
 257** is an optional callback that is invoked once for each row of any query
 258** results produced by the SQL statements.  The 5th parameter tells where
 259** to write any error messages.
 260**
 261** The error message passed back through the 5th parameter is held
 262** in memory obtained from [sqlite3_malloc()].  To avoid a memory leak,
 263** the calling application should call [sqlite3_free()] on any error
 264** message returned through the 5th parameter when it has finished using
 265** the error message.
 266**
 267** If the SQL statement in the 2nd parameter is NULL or an empty string
 268** or a string containing only whitespace and comments, then no SQL
 269** statements are evaluated and the database is not changed.
 270**
 271** The sqlite3_exec() interface is implemented in terms of
 272** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
 273** The sqlite3_exec() routine does nothing to the database that cannot be done
 274** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
 275**
 276** The first parameter to [sqlite3_exec()] must be an valid and open
 277** [database connection].
 278**
 279** The database connection must not be closed while
 280** [sqlite3_exec()] is running.
 281**
 282** The calling function should use [sqlite3_free()] to free
 283** the memory that *errmsg is left pointing at once the error
 284** message is no longer needed.
 285**
 286** The SQL statement text in the 2nd parameter to [sqlite3_exec()]
 287** must remain unchanged while [sqlite3_exec()] is running.
 288**
 289** Requirements:
 290** [H12101] [H12102] [H12104] [H12105] [H12107] [H12110] [H12113] [H12116]
 291** [H12119] [H12122] [H12125] [H12131] [H12134] [H12137] [H12138]
 292*/
 293int sqlite3_exec(
 294  sqlite3*,                                  /* An open database */
 295  const char *sql,                           /* SQL to be evaluated */
 296  int (*callback)(void*,int,char**,char**),  /* Callback function */
 297  void *,                                    /* 1st argument to callback */
 298  char **errmsg                              /* Error msg written here */
 299);
 300
 301/*
 302** CAPI3REF: Result Codes {H10210} <S10700>
 303** KEYWORDS: SQLITE_OK {error code} {error codes}
 304** KEYWORDS: {result code} {result codes}
 305**
 306** Many SQLite functions return an integer result code from the set shown
 307** here in order to indicates success or failure.
 308**
 309** New error codes may be added in future versions of SQLite.
 310**
 311** See also: [SQLITE_IOERR_READ | extended result codes]
 312*/
 313#define SQLITE_OK           0   /* Successful result */
 314/* beginning-of-error-codes */
 315#define SQLITE_ERROR        1   /* SQL error or missing database */
 316#define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
 317#define SQLITE_PERM         3   /* Access permission denied */
 318#define SQLITE_ABORT        4   /* Callback routine requested an abort */
 319#define SQLITE_BUSY         5   /* The database file is locked */
 320#define SQLITE_LOCKED       6   /* A table in the database is locked */
 321#define SQLITE_NOMEM        7   /* A malloc() failed */
 322#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
 323#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
 324#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
 325#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
 326#define SQLITE_NOTFOUND    12   /* NOT USED. Table or record not found */
 327#define SQLITE_FULL        13   /* Insertion failed because database is full */
 328#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
 329#define SQLITE_PROTOCOL    15   /* NOT USED. Database lock protocol error */
 330#define SQLITE_EMPTY       16   /* Database is empty */
 331#define SQLITE_SCHEMA      17   /* The database schema changed */
 332#define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
 333#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
 334#define SQLITE_MISMATCH    20   /* Data type mismatch */
 335#define SQLITE_MISUSE      21   /* Library used incorrectly */
 336#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
 337#define SQLITE_AUTH        23   /* Authorization denied */
 338#define SQLITE_FORMAT      24   /* Auxiliary database format error */
 339#define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
 340#define SQLITE_NOTADB      26   /* File opened that is not a database file */
 341#define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
 342#define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
 343/* end-of-error-codes */
 344
 345/*
 346** CAPI3REF: Extended Result Codes {H10220} <S10700>
 347** KEYWORDS: {extended error code} {extended error codes}
 348** KEYWORDS: {extended result code} {extended result codes}
 349**
 350** In its default configuration, SQLite API routines return one of 26 integer
 351** [SQLITE_OK | result codes].  However, experience has shown that many of
 352** these result codes are too coarse-grained.  They do not provide as
 353** much information about problems as programmers might like.  In an effort to
 354** address this, newer versions of SQLite (version 3.3.8 and later) include
 355** support for additional result codes that provide more detailed information
 356** about errors. The extended result codes are enabled or disabled
 357** on a per database connection basis using the
 358** [sqlite3_extended_result_codes()] API.
 359**
 360** Some of the available extended result codes are listed here.
 361** One may expect the number of extended result codes will be expand
 362** over time.  Software that uses extended result codes should expect
 363** to see new result codes in future releases of SQLite.
 364**
 365** The SQLITE_OK result code will never be extended.  It will always
 366** be exactly zero.
 367*/
 368#define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
 369#define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
 370#define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
 371#define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
 372#define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
 373#define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
 374#define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))
 375#define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))
 376#define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))
 377#define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))
 378#define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))
 379#define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))
 380#define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
 381#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
 382#define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
 383#define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
 384#define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
 385#define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED | (1<<8) )
 386
 387/*
 388** CAPI3REF: Flags For File Open Operations {H10230} <H11120> <H12700>
 389**
 390** These bit values are intended for use in the
 391** 3rd parameter to the [sqlite3_open_v2()] interface and
 392** in the 4th parameter to the xOpen method of the
 393** [sqlite3_vfs] object.
 394*/
 395#define SQLITE_OPEN_READONLY         0x00000001  /* Ok for sqlite3_open_v2() */
 396#define SQLITE_OPEN_READWRITE        0x00000002  /* Ok for sqlite3_open_v2() */
 397#define SQLITE_OPEN_CREATE           0x00000004  /* Ok for sqlite3_open_v2() */
 398#define SQLITE_OPEN_DELETEONCLOSE    0x00000008  /* VFS only */
 399#define SQLITE_OPEN_EXCLUSIVE        0x00000010  /* VFS only */
 400#define SQLITE_OPEN_MAIN_DB          0x00000100  /* VFS only */
 401#define SQLITE_OPEN_TEMP_DB          0x00000200  /* VFS only */
 402#define SQLITE_OPEN_TRANSIENT_DB     0x00000400  /* VFS only */
 403#define SQLITE_OPEN_MAIN_JOURNAL     0x00000800  /* VFS only */
 404#define SQLITE_OPEN_TEMP_JOURNAL     0x00001000  /* VFS only */
 405#define SQLITE_OPEN_SUBJOURNAL       0x00002000  /* VFS only */
 406#define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  /* VFS only */
 407#define SQLITE_OPEN_NOMUTEX          0x00008000  /* Ok for sqlite3_open_v2() */
 408#define SQLITE_OPEN_FULLMUTEX        0x00010000  /* Ok for sqlite3_open_v2() */
 409
 410/*
 411** CAPI3REF: Device Characteristics {H10240} <H11120>
 412**
 413** The xDeviceCapabilities method of the [sqlite3_io_methods]
 414** object returns an integer which is a vector of the these
 415** bit values expressing I/O characteristics of the mass storage
 416** device that holds the file that the [sqlite3_io_methods]
 417** refers to.
 418**
 419** The SQLITE_IOCAP_ATOMIC property means that all writes of
 420** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
 421** mean that writes of blocks that are nnn bytes in size and
 422** are aligned to an address which is an integer multiple of
 423** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
 424** that when data is appended to a file, the data is appended
 425** first then the size of the file is extended, never the other
 426** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
 427** information is written to disk in the same order as calls
 428** to xWrite().
 429*/
 430#define SQLITE_IOCAP_ATOMIC          0x00000001
 431#define SQLITE_IOCAP_ATOMIC512       0x00000002
 432#define SQLITE_IOCAP_ATOMIC1K        0x00000004
 433#define SQLITE_IOCAP_ATOMIC2K        0x00000008
 434#define SQLITE_IOCAP_ATOMIC4K        0x00000010
 435#define SQLITE_IOCAP_ATOMIC8K        0x00000020
 436#define SQLITE_IOCAP_ATOMIC16K       0x00000040
 437#define SQLITE_IOCAP_ATOMIC32K       0x00000080
 438#define SQLITE_IOCAP_ATOMIC64K       0x00000100
 439#define SQLITE_IOCAP_SAFE_APPEND     0x00000200
 440#define SQLITE_IOCAP_SEQUENTIAL      0x00000400
 441
 442/*
 443** CAPI3REF: File Locking Levels {H10250} <H11120> <H11310>
 444**
 445** SQLite uses one of these integer values as the second
 446** argument to calls it makes to the xLock() and xUnlock() methods
 447** of an [sqlite3_io_methods] object.
 448*/
 449#define SQLITE_LOCK_NONE          0
 450#define SQLITE_LOCK_SHARED        1
 451#define SQLITE_LOCK_RESERVED      2
 452#define SQLITE_LOCK_PENDING       3
 453#define SQLITE_LOCK_EXCLUSIVE     4
 454
 455/*
 456** CAPI3REF: Synchronization Type Flags {H10260} <H11120>
 457**
 458** When SQLite invokes the xSync() method of an
 459** [sqlite3_io_methods] object it uses a combination of
 460** these integer values as the second argument.
 461**
 462** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
 463** sync operation only needs to flush data to mass storage.  Inode
 464** information need not be flushed. If the lower four bits of the flag
 465** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
 466** If the lower four bits equal SQLITE_SYNC_FULL, that means
 467** to use Mac OS X style fullsync instead of fsync().
 468*/
 469#define SQLITE_SYNC_NORMAL        0x00002
 470#define SQLITE_SYNC_FULL          0x00003
 471#define SQLITE_SYNC_DATAONLY      0x00010
 472
 473/*
 474** CAPI3REF: OS Interface Open File Handle {H11110} <S20110>
 475**
 476** An [sqlite3_file] object represents an open file in the OS
 477** interface layer.  Individual OS interface implementations will
 478** want to subclass this object by appending additional fields
 479** for their own use.  The pMethods entry is a pointer to an
 480** [sqlite3_io_methods] object that defines methods for performing
 481** I/O operations on the open file.
 482*/
 483typedef struct sqlite3_file sqlite3_file;
 484struct sqlite3_file {
 485  const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
 486};
 487
 488/*
 489** CAPI3REF: OS Interface File Virtual Methods Object {H11120} <S20110>
 490**
 491** Every file opened by the [sqlite3_vfs] xOpen method populates an
 492** [sqlite3_file] object (or, more commonly, a subclass of the
 493** [sqlite3_file] object) with a pointer to an instance of this object.
 494** This object defines the methods used to perform various operations
 495** against the open file represented by the [sqlite3_file] object.
 496**
 497** If the xOpen method sets the sqlite3_file.pMethods element 
 498** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
 499** may be invoked even if the xOpen reported that it failed.  The
 500** only way to prevent a call to xClose following a failed xOpen
 501** is for the xOpen to set the sqlite3_file.pMethods element to NULL.
 502**
 503** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
 504** [SQLITE_SYNC_FULL].  The first choice is the normal fsync().
 505** The second choice is a Mac OS X style fullsync.  The [SQLITE_SYNC_DATAONLY]
 506** flag may be ORed in to indicate that only the data of the file
 507** and not its inode needs to be synced.
 508**
 509** The integer values to xLock() and xUnlock() are one of
 510** <ul>
 511** <li> [SQLITE_LOCK_NONE],
 512** <li> [SQLITE_LOCK_SHARED],
 513** <li> [SQLITE_LOCK_RESERVED],
 514** <li> [SQLITE_LOCK_PENDING], or
 515** <li> [SQLITE_LOCK_EXCLUSIVE].
 516** </ul>
 517** xLock() increases the lock. xUnlock() decreases the lock.
 518** The xCheckReservedLock() method checks whether any database connection,
 519** either in this process or in some other process, is holding a RESERVED,
 520** PENDING, or EXCLUSIVE lock on the file.  It returns true
 521** if such a lock exists and false otherwise.
 522**
 523** The xFileControl() method is a generic interface that allows custom
 524** VFS implementations to directly control an open file using the
 525** [sqlite3_file_control()] interface.  The second "op" argument is an
 526** integer opcode.  The third argument is a generic pointer intended to
 527** point to a structure that may contain arguments or space in which to
 528** write return values.  Potential uses for xFileControl() might be
 529** functions to enable blocking locks with timeouts, to change the
 530** locking strategy (for example to use dot-file locks), to inquire
 531** about the status of a lock, or to break stale locks.  The SQLite
 532** core reserves all opcodes less than 100 for its own use.
 533** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
 534** Applications that define a custom xFileControl method should use opcodes
 535** greater than 100 to avoid conflicts.
 536**
 537** The xSectorSize() method returns the sector size of the
 538** device that underlies the file.  The sector size is the
 539** minimum write that can be performed without disturbing
 540** other bytes in the file.  The xDeviceCharacteristics()
 541** method returns a bit vector describing behaviors of the
 542** underlying device:
 543**
 544** <ul>
 545** <li> [SQLITE_IOCAP_ATOMIC]
 546** <li> [SQLITE_IOCAP_ATOMIC512]
 547** <li> [SQLITE_IOCAP_ATOMIC1K]
 548** <li> [SQLITE_IOCAP_ATOMIC2K]
 549** <li> [SQLITE_IOCAP_ATOMIC4K]
 550** <li> [SQLITE_IOCAP_ATOMIC8K]
 551** <li> [SQLITE_IOCAP_ATOMIC16K]
 552** <li> [SQLITE_IOCAP_ATOMIC32K]
 553** <li> [SQLITE_IOCAP_ATOMIC64K]
 554** <li> [SQLITE_IOCAP_SAFE_APPEND]
 555** <li> [SQLITE_IOCAP_SEQUENTIAL]
 556** </ul>
 557**
 558** The SQLITE_IOCAP_ATOMIC property means that all writes of
 559** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
 560** mean that writes of blocks that are nnn bytes in size and
 561** are aligned to an address which is an integer multiple of
 562** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
 563** that when data is appended to a file, the data is appended
 564** first then the size of the file is extended, never the other
 565** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
 566** information is written to disk in the same order as calls
 567** to xWrite().
 568**
 569** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
 570** in the unread portions of the buffer with zeros.  A VFS that
 571** fails to zero-fill short reads might seem to work.  However,
 572** failure to zero-fill short reads will eventually lead to
 573** database corruption.
 574*/
 575typedef struct sqlite3_io_methods sqlite3_io_methods;
 576struct sqlite3_io_methods {
 577  int iVersion;
 578  int (*xClose)(sqlite3_file*);
 579  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
 580  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
 581  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
 582  int (*xSync)(sqlite3_file*, int flags);
 583  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
 584  int (*xLock)(sqlite3_file*, int);
 585  int (*xUnlock)(sqlite3_file*, int);
 586  int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
 587  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
 588  int (*xSectorSize)(sqlite3_file*);
 589  int (*xDeviceCharacteristics)(sqlite3_file*);
 590  /* Additional methods may be added in future releases */
 591};
 592
 593/*
 594** CAPI3REF: Standard File Control Opcodes {H11310} <S30800>
 595**
 596** These integer constants are opcodes for the xFileControl method
 597** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
 598** interface.
 599**
 600** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This
 601** opcode causes the xFileControl method to write the current state of
 602** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
 603** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
 604** into an integer that the pArg argument points to. This capability
 605** is used during testing and only needs to be supported when SQLITE_TEST
 606** is defined.
 607*/
 608#define SQLITE_FCNTL_LOCKSTATE        1
 609#define SQLITE_GET_LOCKPROXYFILE      2
 610#define SQLITE_SET_LOCKPROXYFILE      3
 611#define SQLITE_LAST_ERRNO             4
 612
 613/*
 614** CAPI3REF: Mutex Handle {H17110} <S20130>
 615**
 616** The mutex module within SQLite defines [sqlite3_mutex] to be an
 617** abstract type for a mutex object.  The SQLite core never looks
 618** at the internal representation of an [sqlite3_mutex].  It only
 619** deals with pointers to the [sqlite3_mutex] object.
 620**
 621** Mutexes are created using [sqlite3_mutex_alloc()].
 622*/
 623typedef struct sqlite3_mutex sqlite3_mutex;
 624
 625/*
 626** CAPI3REF: OS Interface Object {H11140} <S20100>
 627**
 628** An instance of the sqlite3_vfs object defines the interface between
 629** the SQLite core and the underlying operating system.  The "vfs"
 630** in the name of the object stands for "virtual file system".
 631**
 632** The value of the iVersion field is initially 1 but may be larger in
 633** future versions of SQLite.  Additional fields may be appended to this
 634** object when the iVersion value is increased.  Note that the structure
 635** of the sqlite3_vfs object changes in the transaction between
 636** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
 637** modified.
 638**
 639** The szOsFile field is the size of the subclassed [sqlite3_file]
 640** structure used by this VFS.  mxPathname is the maximum length of
 641** a pathname in this VFS.
 642**
 643** Registered sqlite3_vfs objects are kept on a linked list formed by
 644** the pNext pointer.  The [sqlite3_vfs_register()]
 645** and [sqlite3_vfs_unregister()] interfaces manage this list
 646** in a thread-safe way.  The [sqlite3_vfs_find()] interface
 647** searches the list.  Neither the application code nor the VFS
 648** implementation should use the pNext pointer.
 649**
 650** The pNext field is the only field in the sqlite3_vfs
 651** structure that SQLite will ever modify.  SQLite will only access
 652** or modify this field while holding a particular static mutex.
 653** The application should never modify anything within the sqlite3_vfs
 654** object once the object has been registered.
 655**
 656** The zName field holds the name of the VFS module.  The name must
 657** be unique across all VFS modules.
 658**
 659** SQLite will guarantee that the zFilename parameter to xOpen
 660** is either a NULL pointer or string obtained
 661** from xFullPathname().  SQLite further guarantees that
 662** the string will be valid and unchanged until xClose() is
 663** called. Because of the previous sentence,
 664** the [sqlite3_file] can safely store a pointer to the
 665** filename if it needs to remember the filename for some reason.
 666** If the zFilename parameter is xOpen is a NULL pointer then xOpen
 667** must invent its own temporary name for the file.  Whenever the 
 668** xFilename parameter is NULL it will also be the case that the
 669** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
 670**
 671** The flags argument to xOpen() includes all bits set in
 672** the flags argument to [sqlite3_open_v2()].  Or if [sqlite3_open()]
 673** or [sqlite3_open16()] is used, then flags includes at least
 674** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. 
 675** If xOpen() opens a file read-only then it sets *pOutFlags to
 676** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be set.
 677**
 678** SQLite will also add one of the following flags to the xOpen()
 679** call, depending on the object being opened:
 680**
 681** <ul>
 682** <li>  [SQLITE_OPEN_MAIN_DB]
 683** <li>  [SQLITE_OPEN_MAIN_JOURNAL]
 684** <li>  [SQLITE_OPEN_TEMP_DB]
 685** <li>  [SQLITE_OPEN_TEMP_JOURNAL]
 686** <li>  [SQLITE_OPEN_TRANSIENT_DB]
 687** <li>  [SQLITE_OPEN_SUBJOURNAL]
 688** <li>  [SQLITE_OPEN_MASTER_JOURNAL]
 689** </ul>
 690**
 691** The file I/O implementation can use the object type flags to
 692** change the way it deals with files.  For example, an application
 693** that does not care about crash recovery or rollback might make
 694** the open of a journal file a no-op.  Writes to this journal would
 695** also be no-ops, and any attempt to read the journal would return
 696** SQLITE_IOERR.  Or the implementation might recognize that a database
 697** file will be doing page-aligned sector reads and writes in a random
 698** order and set up its I/O subsystem accordingly.
 699**
 700** SQLite might also add one of the following flags to the xOpen method:
 701**
 702** <ul>
 703** <li> [SQLITE_OPEN_DELETEONCLOSE]
 704** <li> [SQLITE_OPEN_EXCLUSIVE]
 705** </ul>
 706**
 707** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
 708** deleted when it is closed.  The [SQLITE_OPEN_DELETEONCLOSE]
 709** will be set for TEMP  databases, journals and for subjournals.
 710**
 711** The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
 712** with the [SQLITE_OPEN_CREATE] flag, which are both directly
 713** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
 714** API.  The SQLITE_OPEN_EXCLUSIVE flag, when paired with the 
 715** SQLITE_OPEN_CREATE, is used to indicate that file should always
 716** be created, and that it is an error if it already exists.
 717** It is <i>not</i> used to indicate the file should be opened 
 718** for exclusive access.
 719**
 720** At least szOsFile bytes of memory are allocated by SQLite
 721** to hold the  [sqlite3_file] structure passed as the third
 722** argument to xOpen.  The xOpen method does not have to
 723** allocate the structure; it should just fill it in.  Note that
 724** the xOpen method must set the sqlite3_file.pMethods to either
 725** a valid [sqlite3_io_methods] object or to NULL.  xOpen must do
 726** this even if the open fails.  SQLite expects that the sqlite3_file.pMethods
 727** element will be valid after xOpen returns regardless of the success
 728** or failure of the xOpen call.
 729**
 730** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
 731** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
 732** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
 733** to test whether a file is at least readable.   The file can be a
 734** directory.
 735**
 736** SQLite will always allocate at least mxPathname+1 bytes for the
 737** output buffer xFullPathname.  The exact size of the output buffer
 738** is also passed as a parameter to both  methods. If the output buffer
 739** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
 740** handled as a fatal error by SQLite, vfs implementations should endeavor
 741** to prevent this by setting mxPathname to a sufficiently large value.
 742**
 743** The xRandomness(), xSleep(), and xCurrentTime() interfaces
 744** are not strictly a part of the filesystem, but they are
 745** included in the VFS structure for completeness.
 746** The xRandomness() function attempts to return nBytes bytes
 747** of good-quality randomness into zOut.  The return value is
 748** the actual number of bytes of randomness obtained.
 749** The xSleep() method causes the calling thread to sleep for at
 750** least the number of microseconds given.  The xCurrentTime()
 751** method returns a Julian Day Number for the current date and time.
 752**
 753*/
 754typedef struct sqlite3_vfs sqlite3_vfs;
 755struct sqlite3_vfs {
 756  int iVersion;            /* Structure version number */
 757  int szOsFile;            /* Size of subclassed sqlite3_file */
 758  int mxPathname;          /* Maximum file pathname length */
 759  sqlite3_vfs *pNext;      /* Next registered VFS */
 760  const char *zName;       /* Name of this virtual file system */
 761  void *pAppData;          /* Pointer to application-specific data */
 762  int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
 763               int flags, int *pOutFlags);
 764  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
 765  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
 766  int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
 767  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
 768  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
 769  void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
 770  void (*xDlClose)(sqlite3_vfs*, void*);
 771  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
 772  int (*xSleep)(sqlite3_vfs*, int microseconds);
 773  int (*xCurrentTime)(sqlite3_vfs*, double*);
 774  int (*xGetLastError)(sqlite3_vfs*, int, char *);
 775  /* New fields may be appended in figure versions.  The iVersion
 776  ** value will increment whenever this happens. */
 777};
 778
 779/*
 780** CAPI3REF: Flags for the xAccess VFS method {H11190} <H11140>
 781**
 782** These integer constants can be used as the third parameter to
 783** the xAccess method of an [sqlite3_vfs] object. {END}  They determine
 784** what kind of permissions the xAccess method is looking for.
 785** With SQLITE_ACCESS_EXISTS, the xAccess method
 786** simply checks whether the file exists.
 787** With SQLITE_ACCESS_READWRITE, the xAccess method
 788** checks whether the file is both readable and writable.
 789** With SQLITE_ACCESS_READ, the xAccess method
 790** checks whether the file is readable.
 791*/
 792#define SQLITE_ACCESS_EXISTS    0
 793#define SQLITE_ACCESS_READWRITE 1
 794#define SQLITE_ACCESS_READ      2
 795
 796/*
 797** CAPI3REF: Initialize The SQLite Library {H10130} <S20000><S30100>
 798**
 799** The sqlite3_initialize() routine initializes the
 800** SQLite library.  The sqlite3_shutdown() routine
 801** deallocates any resources that were allocated by sqlite3_initialize().
 802**
 803** A call to sqlite3_initialize() is an "effective" call if it is
 804** the first time sqlite3_initialize() is invoked during the lifetime of
 805** the process, or if it is the first time sqlite3_initialize() is invoked
 806** following a call to sqlite3_shutdown().  Only an effective call
 807** of sqlite3_initialize() does any initialization.  All other calls
 808** are harmless no-ops.
 809**
 810** A call to sqlite3_shutdown() is an "effective" call if it is the first
 811** call to sqlite3_shutdown() since the last sqlite3_initialize().  Only
 812** an effective call to sqlite3_shutdown() does any deinitialization.
 813** All other calls to sqlite3_shutdown() are harmless no-ops.
 814**
 815** Among other things, sqlite3_initialize() shall invoke
 816** sqlite3_os_init().  Similarly, sqlite3_shutdown()
 817** shall invoke sqlite3_os_end().
 818**
 819** The sqlite3_initialize() routine returns [SQLITE_OK] on success.
 820** If for some reason, sqlite3_initialize() is unable to initialize
 821** the library (perhaps it is unable to allocate a needed resource such
 822** as a mutex) it returns an [error code] other than [SQLITE_OK].
 823**
 824** The sqlite3_initialize() routine is called internally by many other
 825** SQLite interfaces so that an application usually does not need to
 826** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]
 827** calls sqlite3_initialize() so the SQLite library will be automatically
 828** initialized when [sqlite3_open()] is called if it has not be initialized
 829** already.  However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
 830** compile-time option, then the automatic calls to sqlite3_initialize()
 831** are omitted and the application must call sqlite3_initialize() directly
 832** prior to using any other SQLite interface.  For maximum portability,
 833** it is recommended that applications always invoke sqlite3_initialize()
 834** directly prior to using any other SQLite interface.  Future releases
 835** of SQLite may require this.  In other words, the behavior exhibited
 836** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
 837** default behavior in some future release of SQLite.
 838**
 839** The sqlite3_os_init() routine does operating-system specific
 840** initialization of the SQLite library.  The sqlite3_os_end()
 841** routine undoes the effect of sqlite3_os_init().  Typical tasks
 842** performed by these routines include allocation or deallocation
 843** of static resources, initialization of global variables,
 844** setting up a default [sqlite3_vfs] module, or setting up
 845** a default configuration using [sqlite3_config()].
 846**
 847** The application should never invoke either sqlite3_os_init()
 848** or sqlite3_os_end() directly.  The application should only invoke
 849** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()
 850** interface is called automatically by sqlite3_initialize() and
 851** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate
 852** implementations for sqlite3_os_init() and sqlite3_os_end()
 853** are built into SQLite when it is compiled for unix, windows, or os/2.
 854** When built for other platforms (using the [SQLITE_OS_OTHER=1] compile-time
 855** option) the application must supply a suitable implementation for
 856** sqlite3_os_init() and sqlite3_os_end().  An application-supplied
 857** implementation of sqlite3_os_init() or sqlite3_os_end()
 858** must return [SQLITE_OK] on success and some other [error code] upon
 859** failure.
 860*/
 861int sqlite3_initialize(void);
 862int sqlite3_shutdown(void);
 863int sqlite3_os_init(void);
 864int sqlite3_os_end(void);
 865
 866/*
 867** CAPI3REF: Configuring The SQLite Library {H14100} <S20000><S30200>
 868** EXPERIMENTAL
 869**
 870** The sqlite3_config() interface is used to make global configuration
 871** changes to SQLite in order to tune SQLite to the specific needs of
 872** the application.  The default configuration is recommended for most
 873** applications and so this routine is usually not necessary.  It is
 874** provided to support rare applications with unusual needs.
 875**
 876** The sqlite3_config() interface is not threadsafe.  The application
 877** must insure that no other SQLite interfaces are invoked by other
 878** threads while sqlite3_config() is running.  Furthermore, sqlite3_config()
 879** may only be invoked prior to library initialization using
 880** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
 881** Note, however, that sqlite3_config() can be called as part of the
 882** implementation of an application-defined [sqlite3_os_init()].
 883**
 884** The first argument to sqlite3_config() is an integer
 885** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines
 886** what property of SQLite is to be configured.  Subsequent arguments
 887** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option]
 888** in the first argument.
 889**
 890** When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
 891** If the option is unknown or SQLite is unable to set the option
 892** then this routine returns a non-zero [error code].
 893**
 894** Requirements:
 895** [H14103] [H14106] [H14120] [H14123] [H14126] [H14129] [H14132] [H14135]
 896** [H14138] [H14141] [H14144] [H14147] [H14150] [H14153] [H14156] [H14159]
 897** [H14162] [H14165] [H14168]
 898*/
 899SQLITE_EXPERIMENTAL int sqlite3_config(int, ...);
 900
 901/*
 902** CAPI3REF: Configure database connections  {H14200} <S20000>
 903** EXPERIMENTAL
 904**
 905** The sqlite3_db_config() interface is used to make configuration
 906** changes to a [database connection].  The interface is similar to
 907** [sqlite3_config()] except that the changes apply to a single
 908** [database connection] (specified in the first argument).  The
 909** sqlite3_db_config() interface can only be used immediately after
 910** the database connection is created using [sqlite3_open()],
 911** [sqlite3_open16()], or [sqlite3_open_v2()].  
 912**
 913** The second argument to sqlite3_db_config(D,V,...)  is the
 914** configuration verb - an integer code that indicates what
 915** aspect of the [database connection] is being configured.
 916** The only choice for this value is [SQLITE_DBCONFIG_LOOKASIDE].
 917** New verbs are likely to be added in future releases of SQLite.
 918** Additional arguments depend on the verb.
 919**
 920** Requirements:
 921** [H14203] [H14206] [H14209] [H14212] [H14215]
 922*/
 923SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
 924
 925/*
 926** CAPI3REF: Memory Allocation Routines {H10155} <S20120>
 927** EXPERIMENTAL
 928**
 929** An instance of this object defines the interface between SQLite
 930** and low-level memory allocation routines.
 931**
 932** This object is used in only one place in the SQLite interface.
 933** A pointer to an instance of this object is the argument to
 934** [sqlite3_config()] when the configuration option is
 935** [SQLITE_CONFIG_MALLOC].  By creating an instance of this object
 936** and passing it to [sqlite3_config()] during configuration, an
 937** application can specify an alternative memory allocation subsystem
 938** for SQLite to use for all of its dynamic memory needs.
 939**
 940** Note that SQLite comes with a built-in memory allocator that is
 941** perfectly adequate for the overwhelming majority of applications
 942** and that this object is only useful to a tiny minority of applications
 943** with specialized memory allocation requirements.  This object is
 944** also used during testing of SQLite in order to specify an alternative
 945** memory allocator that simulates memory out-of-memory conditions in
 946** order to verify that SQLite recovers gracefully from such
 947** conditions.
 948**
 949** The xMalloc, xFree, and xRealloc methods must work like the
 950** malloc(), free(), and realloc() functions from the standard library.
 951**
 952** xSize should return the allocated size of a memory allocation
 953** previously obtained from xMalloc or xRealloc.  The allocated size
 954** is always at least as big as the requested size but may be larger.
 955**
 956** The xRoundup method returns what would be the allocated size of
 957** a memory allocation given a particular requested size.  Most memory
 958** allocators round up memory allocations at least to the next multiple
 959** of 8.  Some allocators round up to a larger multiple or to a power of 2.
 960**
 961** The xInit method initializes the memory allocator.  (For example,
 962** it might allocate any require mutexes or initialize internal data
 963** structures.  The xShutdown method is invoked (indirectly) by
 964** [sqlite3_shutdown()] and should deallocate any resources acquired
 965** by xInit.  The pAppData pointer is used as the only parameter to
 966** xInit and xShutdown.
 967*/
 968typedef struct sqlite3_mem_methods sqlite3_mem_methods;
 969struct sqlite3_mem_methods {
 970  void *(*xMalloc)(int);         /* Memory allocation function */
 971  void (*xFree)(void*);          /* Free a prior allocation */
 972  void *(*xRealloc)(void*,int);  /* Resize an allocation */
 973  int (*xSize)(void*);           /* Return the size of an allocation */
 974  int (*xRoundup)(int);          /* Round up request size to allocation size */
 975  int (*xInit)(void*);           /* Initialize the memory allocator */
 976  void (*xShutdown)(void*);      /* Deinitialize the memory allocator */
 977  void *pAppData;                /* Argument to xInit() and xShutdown() */
 978};
 979
 980/*
 981** CAPI3REF: Configuration Options {H10160} <S20000>
 982** EXPERIMENTAL
 983**
 984** These constants are the available integer configuration options that
 985** can be passed as the first argument to the [sqlite3_config()] interface.
 986**
 987** New configuration options may be added in future releases of SQLite.
 988** Existing configuration options might be discontinued.  Applications
 989** should check the return code from [sqlite3_config()] to make sure that
 990** the call worked.  The [sqlite3_config()] interface will return a
 991** non-zero [error code] if a discontinued or unsupported configuration option
 992** is invoked.
 993**
 994** <dl>
 995** <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
 996** <dd>There are no arguments to this option.  This option disables
 997** all mutexing and puts SQLite into a mode where it can only be used
 998** by a single thread.</dd>
 999**
1000** <dt>SQLITE_CONFIG_MULTITHREAD</dt>
1001** <dd>There are no arguments to this option.  This option disables
1002** mutexing on [database connection] and [prepared statement] objects.
1003** The application is responsible for serializing access to
1004** [database connections] and [prepared statements].  But other mutexes
1005** are enabled so that SQLite will be safe to use in a multi-threaded
1006** environment as long as no two threads attempt to use the same
1007** [database connection] at the same time.  See the [threading mode]
1008** documentation for additional information.</dd>
1009**
1010** <dt>SQLITE_CONFIG_SERIALIZED</dt>
1011** <dd>There are no arguments to this option.  This option enables
1012** all mutexes including the recursive
1013** mutexes on [database connection] and [prepared statement] objects.
1014** In this mode (which is the default when SQLite is compiled with
1015** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
1016** to [database connections] and [prepared statements] so that the
1017** application is free to use the same [database connection] or the
1018** same [prepared statement] in different threads at the same time.
1019** See the [threading mode] documentation for additional information.</dd>
1020**
1021** <dt>SQLITE_CONFIG_MALLOC</dt>
1022** <dd>This option takes a single argument which is a pointer to an
1023** instance of the [sqlite3_mem_methods] structure.  The argument specifies
1024** alternative low-level memory allocation routines to be used in place of
1025** the memory allocation routines built into SQLite.</dd>
1026**
1027** <dt>SQLITE_CONFIG_GETMALLOC</dt>
1028** <dd>This option takes a single argument which is a pointer to an
1029** instance of the [sqlite3_mem_methods] structure.  The [sqlite3_mem_methods]
1030** structure is filled with the currently defined memory allocation routines.
1031** This option can be used to overload the default memory allocation
1032** routines with a wrapper that simulations memory allocation failure or
1033** tracks memory usage, for example.</dd>
1034**
1035** <dt>SQLITE_CONFIG_MEMSTATUS</dt>
1036** <dd>This option takes single argument of type int, interpreted as a 
1037** boolean, which enables or disables the collection of memory allocation 
1038** statistics. When disabled, the following SQLite interfaces become 
1039** non-operational:
1040**   <ul>
1041**   <li> [sqlite3_memory_used()]
1042**   <li> [sqlite3_memory_highwater()]
1043**   <li> [sqlite3_soft_heap_limit()]
1044**   <li> [sqlite3_status()]
1045**   </ul>
1046** </dd>
1047**
1048** <dt>SQLITE_CONFIG_SCRATCH</dt>
1049** <dd>This option specifies a static memory buffer that SQLite can use for
1050** scratch memory.  There are three arguments:  A pointer an 8-byte
1051** aligned memory buffer from which the scrach allocations will be
1052** drawn, the size of each scratch allocation (sz),
1053** and the maximum number of scratch allocations (N).  The sz
1054** argument must be a multiple of 16. The sz parameter should be a few bytes
1055** larger than the actual scratch space required due to internal overhead.
1056** The first argument should pointer to an 8-byte aligned buffer
1057** of at least sz*N bytes of memory.
1058** SQLite will use no more than one scratch buffer at once per thread, so
1059** N should be set to the expected maximum number of threads.  The sz
1060** parameter should be 6 times the size of the largest database page size.
1061** Scratch buffers are used as part of the btree balance operation.  If
1062** The btree balancer needs additional memory beyond what is provided by
1063** scratch buffers or if no scratch buffer space is specified, then SQLite
1064** goes to [sqlite3_malloc()] to obtain the memory it needs.</dd>
1065**
1066** <dt>SQLITE_CONFIG_PAGECACHE</dt>
1067** <dd>This option specifies a static memory buffer that SQLite can use for
1068** the database page cache with the default page cache implemenation.  
1069** This configuration should not be used if an application-define page
1070** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option.
1071** There are three arguments to this option: A pointer to 8-byte aligned
1072** memory, the size of each page buffer (sz), and the number of pages (N).
1073** The sz argument should be the size of the largest database page
1074** (a power of two between 512 and 32768) plus a little extra for each
1075** page header.  The page header size is 20 to 40 bytes depending on
1076** the host architecture.  It is harmless, apart from the wasted memory,
1077** to make sz a little too large.  The first
1078** argument should point to an allocation of at least sz*N bytes of memory.
1079** SQLite will use the memory provided by the first argument to satisfy its
1080** memory needs for the first N pages that it adds to cache.  If additional
1081** page cache memory is needed beyond what is provided by this option, then
1082** SQLite goes to [sqlite3_malloc()] for the additional storage space.
1083** The implementation might use one or more of the N buffers to hold 
1084** memory accounting information. The pointer in the first argument must
1085** be aligned to an 8-byte boundary or subsequ…

Large files files are truncated, but you can click here to view the full file