sqlite3.h.svn-base
上传用户:sunhongbo
上传日期:2022-01-25
资源大小:3010k
文件大小:251k
源码类别:

数据库系统

开发平台:

C/C++

  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.305 2008/04/16 00:28:14 drh Exp $
  34. */
  35. #ifndef _SQLITE3_H_
  36. #define _SQLITE3_H_
  37. #include <stdarg.h>     /* Needed for the definition of va_list */
  38. /*
  39. ** Make sure we can call this stuff from C++.
  40. */
  41. #ifdef __cplusplus
  42. extern "C" {
  43. #endif
  44. /*
  45. ** Add the ability to override 'extern'
  46. */
  47. #ifndef SQLITE_EXTERN
  48. # define SQLITE_EXTERN extern
  49. #endif
  50. /*
  51. ** Make sure these symbols where not defined by some previous header
  52. ** file.
  53. */
  54. #ifdef SQLITE_VERSION
  55. # undef SQLITE_VERSION
  56. #endif
  57. #ifdef SQLITE_VERSION_NUMBER
  58. # undef SQLITE_VERSION_NUMBER
  59. #endif
  60. /*
  61. ** CAPI3REF: Compile-Time Library Version Numbers {F10010}
  62. **
  63. ** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in
  64. ** the sqlite3.h file specify the version of SQLite with which
  65. ** that header file is associated.
  66. **
  67. ** The "version" of SQLite is a string of the form "X.Y.Z".
  68. ** The phrase "alpha" or "beta" might be appended after the Z.
  69. ** The X value is major version number always 3 in SQLite3.
  70. ** The X value only changes when  backwards compatibility is
  71. ** broken and we intend to never break
  72. ** backwards compatibility.  The Y value is the minor version
  73. ** number and only changes when
  74. ** there are major feature enhancements that are forwards compatible
  75. ** but not backwards compatible.  The Z value is release number
  76. ** and is incremented with
  77. ** each release but resets back to 0 when Y is incremented.
  78. **
  79. ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
  80. **
  81. ** INVARIANTS:
  82. **
  83. ** {F10011} The SQLITE_VERSION #define in the sqlite3.h header file
  84. **          evaluates to a string literal that is the SQLite version
  85. **          with which the header file is associated.
  86. **
  87. ** {F10014} The SQLITE_VERSION_NUMBER #define resolves to an integer
  88. **          with the value  (X*1000000 + Y*1000 + Z) where X, Y, and
  89. **          Z are the major version, minor version, and release number.
  90. */
  91. #define SQLITE_VERSION         "3.5.8"
  92. #define SQLITE_VERSION_NUMBER  3005008
  93. /*
  94. ** CAPI3REF: Run-Time Library Version Numbers {F10020}
  95. ** KEYWORDS: sqlite3_version
  96. **
  97. ** These features provide the same information as the [SQLITE_VERSION]
  98. ** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated
  99. ** with the library instead of the header file.  Cautious programmers might
  100. ** include a check in their application to verify that 
  101. ** sqlite3_libversion_number() always returns the value 
  102. ** [SQLITE_VERSION_NUMBER].
  103. **
  104. ** The sqlite3_libversion() function returns the same information as is
  105. ** in the sqlite3_version[] string constant.  The function is provided
  106. ** for use in DLLs since DLL users usually do not have direct access to string
  107. ** constants within the DLL.
  108. **
  109. ** INVARIANTS:
  110. **
  111. ** {F10021} The [sqlite3_libversion_number()] interface returns an integer
  112. **          equal to [SQLITE_VERSION_NUMBER]. 
  113. **
  114. ** {F10022} The [sqlite3_version] string constant contains the text of the
  115. **          [SQLITE_VERSION] string. 
  116. **
  117. ** {F10023} The [sqlite3_libversion()] function returns
  118. **          a pointer to the [sqlite3_version] string constant.
  119. */
  120. SQLITE_EXTERN const char sqlite3_version[];
  121. const char *sqlite3_libversion(void);
  122. int sqlite3_libversion_number(void);
  123. /*
  124. ** CAPI3REF: Test To See If The Library Is Threadsafe {F10100}
  125. **
  126. ** SQLite can be compiled with or without mutexes.  When
  127. ** the SQLITE_THREADSAFE C preprocessor macro is true, mutexes
  128. ** are enabled and SQLite is threadsafe.  When that macro is false,
  129. ** the mutexes are omitted.  Without the mutexes, it is not safe
  130. ** to use SQLite from more than one thread.
  131. **
  132. ** There is a measurable performance penalty for enabling mutexes.
  133. ** So if speed is of utmost importance, it makes sense to disable
  134. ** the mutexes.  But for maximum safety, mutexes should be enabled.
  135. ** The default behavior is for mutexes to be enabled.
  136. **
  137. ** This interface can be used by a program to make sure that the
  138. ** version of SQLite that it is linking against was compiled with
  139. ** the desired setting of the SQLITE_THREADSAFE macro.
  140. **
  141. ** INVARIANTS:
  142. **
  143. ** {F10101} The [sqlite3_threadsafe()] function returns nonzero if
  144. **          SQLite was compiled with its mutexes enabled or zero
  145. **          if SQLite was compiled with mutexes disabled.
  146. */
  147. int sqlite3_threadsafe(void);
  148. /*
  149. ** CAPI3REF: Database Connection Handle {F12000}
  150. ** KEYWORDS: {database connection}
  151. **
  152. ** Each open SQLite database is represented by pointer to an instance of the
  153. ** opaque structure named "sqlite3".  It is useful to think of an sqlite3
  154. ** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and
  155. ** [sqlite3_open_v2()] interfaces are its constructors
  156. ** and [sqlite3_close()] is its destructor.  There are many other interfaces
  157. ** (such as [sqlite3_prepare_v2()], [sqlite3_create_function()], and
  158. ** [sqlite3_busy_timeout()] to name but three) that are methods on this
  159. ** object.
  160. */
  161. typedef struct sqlite3 sqlite3;
  162. /*
  163. ** CAPI3REF: 64-Bit Integer Types {F10200}
  164. ** KEYWORDS: sqlite_int64 sqlite_uint64
  165. **
  166. ** Because there is no cross-platform way to specify 64-bit integer types
  167. ** SQLite includes typedefs for 64-bit signed and unsigned integers.
  168. **
  169. ** The sqlite3_int64 and sqlite3_uint64 are the preferred type
  170. ** definitions.  The sqlite_int64 and sqlite_uint64 types are
  171. ** supported for backwards compatibility only.
  172. **
  173. ** INVARIANTS:
  174. **
  175. ** {F10201} The [sqlite_int64] and [sqlite3_int64] types specify a
  176. **          64-bit signed integer.
  177. **
  178. ** {F10202} The [sqlite_uint64] and [sqlite3_uint64] types specify
  179. **          a 64-bit unsigned integer.
  180. */
  181. #ifdef SQLITE_INT64_TYPE
  182.   typedef SQLITE_INT64_TYPE sqlite_int64;
  183.   typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
  184. #elif defined(_MSC_VER) || defined(__BORLANDC__)
  185.   typedef __int64 sqlite_int64;
  186.   typedef unsigned __int64 sqlite_uint64;
  187. #else
  188.   typedef /*long*/ long int sqlite_int64;
  189.   typedef unsigned /*long*/ long int sqlite_uint64;
  190. #endif
  191. typedef sqlite_int64 sqlite3_int64;
  192. typedef sqlite_uint64 sqlite3_uint64;
  193. /*
  194. ** If compiling for a processor that lacks floating point support,
  195. ** substitute integer for floating-point
  196. */
  197. #ifdef SQLITE_OMIT_FLOATING_POINT
  198. # define double sqlite3_int64
  199. #endif
  200. /*
  201. ** CAPI3REF: Closing A Database Connection {F12010}
  202. **
  203. ** This routine is the destructor for the [sqlite3] object.  
  204. **
  205. ** Applications should [sqlite3_finalize | finalize] all
  206. ** [prepared statements] and
  207. ** [sqlite3_blob_close | close] all [sqlite3_blob | BLOBs] 
  208. ** associated with the [sqlite3] object prior
  209. ** to attempting to close the [sqlite3] object.
  210. **
  211. ** <todo>What happens to pending transactions?  Are they
  212. ** rolled back, or abandoned?</todo>
  213. **
  214. ** INVARIANTS:
  215. **
  216. ** {F12011} The [sqlite3_close()] interface destroys an [sqlite3] object
  217. **          allocated by a prior call to [sqlite3_open()],
  218. **          [sqlite3_open16()], or [sqlite3_open_v2()].
  219. **
  220. ** {F12012} The [sqlite3_close()] function releases all memory used by the
  221. **          connection and closes all open files.
  222. **
  223. ** {F12013} If the database connection contains
  224. **          [prepared statements] that have not been
  225. **          finalized by [sqlite3_finalize()], then [sqlite3_close()]
  226. **          returns [SQLITE_BUSY] and leaves the connection open.
  227. **
  228. ** {F12014} Giving sqlite3_close() a NULL pointer is a harmless no-op.
  229. **
  230. ** LIMITATIONS:
  231. **
  232. ** {U12015} The parameter to [sqlite3_close()] must be an [sqlite3] object
  233. **          pointer previously obtained from [sqlite3_open()] or the 
  234. **          equivalent, or NULL.
  235. **
  236. ** {U12016} The parameter to [sqlite3_close()] must not have been previously
  237. **          closed.
  238. */
  239. int sqlite3_close(sqlite3 *);
  240. /*
  241. ** The type for a callback function.
  242. ** This is legacy and deprecated.  It is included for historical
  243. ** compatibility and is not documented.
  244. */
  245. typedef int (*sqlite3_callback)(void*,int,char**, char**);
  246. /*
  247. ** CAPI3REF: One-Step Query Execution Interface {F12100}
  248. **
  249. ** The sqlite3_exec() interface is a convenient way of running
  250. ** one or more SQL statements without a lot of C code.  The
  251. ** SQL statements are passed in as the second parameter to
  252. ** sqlite3_exec().  The statements are evaluated one by one
  253. ** until either an error or an interrupt is encountered or
  254. ** until they are all done.  The 3rd parameter is an optional
  255. ** callback that is invoked once for each row of any query results
  256. ** produced by the SQL statements.  The 5th parameter tells where
  257. ** to write any error messages.
  258. **
  259. ** The sqlite3_exec() interface is implemented in terms of
  260. ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
  261. ** The sqlite3_exec() routine does nothing that cannot be done
  262. ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
  263. ** The sqlite3_exec() is just a convenient wrapper.
  264. **
  265. ** INVARIANTS:
  266. ** 
  267. ** {F12101} The [sqlite3_exec()] interface evaluates zero or more UTF-8
  268. **          encoded, semicolon-separated, SQL statements in the
  269. **          zero-terminated string of its 2nd parameter within the
  270. **          context of the [sqlite3] object given in the 1st parameter.
  271. **
  272. ** {F12104} The return value of [sqlite3_exec()] is SQLITE_OK if all
  273. **          SQL statements run successfully.
  274. **
  275. ** {F12105} The return value of [sqlite3_exec()] is an appropriate 
  276. **          non-zero error code if any SQL statement fails.
  277. **
  278. ** {F12107} If one or more of the SQL statements handed to [sqlite3_exec()]
  279. **          return results and the 3rd parameter is not NULL, then
  280. **          the callback function specified by the 3rd parameter is
  281. **          invoked once for each row of result.
  282. **
  283. ** {F12110} If the callback returns a non-zero value then [sqlite3_exec()]
  284. **          will aborted the SQL statement it is currently evaluating,
  285. **          skip all subsequent SQL statements, and return [SQLITE_ABORT].
  286. **          <todo>What happens to *errmsg here?  Does the result code for
  287. **          sqlite3_errcode() get set?</todo>
  288. **
  289. ** {F12113} The [sqlite3_exec()] routine will pass its 4th parameter through
  290. **          as the 1st parameter of the callback.
  291. **
  292. ** {F12116} The [sqlite3_exec()] routine sets the 2nd parameter of its
  293. **          callback to be the number of columns in the current row of
  294. **          result.
  295. **
  296. ** {F12119} The [sqlite3_exec()] routine sets the 3rd parameter of its 
  297. **          callback to be an array of pointers to strings holding the
  298. **          values for each column in the current result set row as
  299. **          obtained from [sqlite3_column_text()].
  300. **
  301. ** {F12122} The [sqlite3_exec()] routine sets the 4th parameter of its
  302. **          callback to be an array of pointers to strings holding the
  303. **          names of result columns as obtained from [sqlite3_column_name()].
  304. **
  305. ** {F12125} If the 3rd parameter to [sqlite3_exec()] is NULL then
  306. **          [sqlite3_exec()] never invokes a callback.  All query
  307. **          results are silently discarded.
  308. **
  309. ** {F12128} If an error occurs while parsing or evaluating any of the SQL
  310. **          statements handed to [sqlite3_exec()] then [sqlite3_exec()] will
  311. **          return an [error code] other than [SQLITE_OK].
  312. **
  313. ** {F12131} If an error occurs while parsing or evaluating any of the SQL
  314. **          handed to [sqlite3_exec()] and if the 5th parameter (errmsg)
  315. **          to [sqlite3_exec()] is not NULL, then an error message is
  316. **          allocated using the equivalent of [sqlite3_mprintf()] and
  317. **          *errmsg is made to point to that message.
  318. **
  319. ** {F12134} The [sqlite3_exec()] routine does not change the value of
  320. **          *errmsg if errmsg is NULL or if there are no errors.
  321. **
  322. ** {F12137} The [sqlite3_exec()] function sets the error code and message
  323. **          accessible via [sqlite3_errcode()], [sqlite3_errmsg()], and
  324. **          [sqlite3_errmsg16()].
  325. **
  326. ** LIMITATIONS:
  327. **
  328. ** {U12141} The first parameter to [sqlite3_exec()] must be an valid and open
  329. **          [database connection].
  330. **
  331. ** {U12142} The database connection must not be closed while
  332. **          [sqlite3_exec()] is running.
  333. ** 
  334. ** {U12143} The calling function is should use [sqlite3_free()] to free
  335. **          the memory that *errmsg is left pointing at once the error
  336. **          message is no longer needed.
  337. **
  338. ** {U12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()]
  339. **          must remain unchanged while [sqlite3_exec()] is running.
  340. */
  341. int sqlite3_exec(
  342.   sqlite3*,                                  /* An open database */
  343.   const char *sql,                           /* SQL to be evaluted */
  344.   int (*callback)(void*,int,char**,char**),  /* Callback function */
  345.   void *,                                    /* 1st argument to callback */
  346.   char **errmsg                              /* Error msg written here */
  347. );
  348. /*
  349. ** CAPI3REF: Result Codes {F10210}
  350. ** KEYWORDS: SQLITE_OK {error code} {error codes}
  351. **
  352. ** Many SQLite functions return an integer result code from the set shown
  353. ** here in order to indicates success or failure.
  354. **
  355. ** See also: [SQLITE_IOERR_READ | extended result codes]
  356. */
  357. #define SQLITE_OK           0   /* Successful result */
  358. /* beginning-of-error-codes */
  359. #define SQLITE_ERROR        1   /* SQL error or missing database */
  360. #define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
  361. #define SQLITE_PERM         3   /* Access permission denied */
  362. #define SQLITE_ABORT        4   /* Callback routine requested an abort */
  363. #define SQLITE_BUSY         5   /* The database file is locked */
  364. #define SQLITE_LOCKED       6   /* A table in the database is locked */
  365. #define SQLITE_NOMEM        7   /* A malloc() failed */
  366. #define SQLITE_READONLY     8   /* Attempt to write a readonly database */
  367. #define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
  368. #define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
  369. #define SQLITE_CORRUPT     11   /* The database disk image is malformed */
  370. #define SQLITE_NOTFOUND    12   /* NOT USED. Table or record not found */
  371. #define SQLITE_FULL        13   /* Insertion failed because database is full */
  372. #define SQLITE_CANTOPEN    14   /* Unable to open the database file */
  373. #define SQLITE_PROTOCOL    15   /* NOT USED. Database lock protocol error */
  374. #define SQLITE_EMPTY       16   /* Database is empty */
  375. #define SQLITE_SCHEMA      17   /* The database schema changed */
  376. #define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
  377. #define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
  378. #define SQLITE_MISMATCH    20   /* Data type mismatch */
  379. #define SQLITE_MISUSE      21   /* Library used incorrectly */
  380. #define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
  381. #define SQLITE_AUTH        23   /* Authorization denied */
  382. #define SQLITE_FORMAT      24   /* Auxiliary database format error */
  383. #define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
  384. #define SQLITE_NOTADB      26   /* File opened that is not a database file */
  385. #define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
  386. #define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
  387. /* end-of-error-codes */
  388. /*
  389. ** CAPI3REF: Extended Result Codes {F10220}
  390. ** KEYWORDS: {extended error code} {extended error codes}
  391. ** KEYWORDS: {extended result codes}
  392. **
  393. ** In its default configuration, SQLite API routines return one of 26 integer
  394. ** [SQLITE_OK | result codes].  However, experience has shown that
  395. ** many of these result codes are too course-grained.  They do not provide as
  396. ** much information about problems as programmers might like.  In an effort to
  397. ** address this, newer versions of SQLite (version 3.3.8 and later) include
  398. ** support for additional result codes that provide more detailed information
  399. ** about errors. The extended result codes are enabled or disabled
  400. ** for each database connection using the [sqlite3_extended_result_codes()]
  401. ** API.
  402. ** 
  403. ** Some of the available extended result codes are listed here.
  404. ** One may expect the number of extended result codes will be expand
  405. ** over time.  Software that uses extended result codes should expect
  406. ** to see new result codes in future releases of SQLite.
  407. **
  408. ** The SQLITE_OK result code will never be extended.  It will always
  409. ** be exactly zero.
  410. ** 
  411. ** INVARIANTS:
  412. **
  413. ** {F10223} The symbolic name for an extended result code always contains
  414. **          a related primary result code as a prefix.
  415. **
  416. ** {F10224} Primary result code names contain a single "_" character.
  417. **
  418. ** {F10225} Extended result code names contain two or more "_" characters.
  419. **
  420. ** {F10226} The numeric value of an extended result code contains the
  421. **          numeric value of its corresponding primary result code in
  422. **          its least significant 8 bits.
  423. */
  424. #define SQLITE_IOERR_READ          (SQLITE_IOERR | (1<<8))
  425. #define SQLITE_IOERR_SHORT_READ    (SQLITE_IOERR | (2<<8))
  426. #define SQLITE_IOERR_WRITE         (SQLITE_IOERR | (3<<8))
  427. #define SQLITE_IOERR_FSYNC         (SQLITE_IOERR | (4<<8))
  428. #define SQLITE_IOERR_DIR_FSYNC     (SQLITE_IOERR | (5<<8))
  429. #define SQLITE_IOERR_TRUNCATE      (SQLITE_IOERR | (6<<8))
  430. #define SQLITE_IOERR_FSTAT         (SQLITE_IOERR | (7<<8))
  431. #define SQLITE_IOERR_UNLOCK        (SQLITE_IOERR | (8<<8))
  432. #define SQLITE_IOERR_RDLOCK        (SQLITE_IOERR | (9<<8))
  433. #define SQLITE_IOERR_DELETE        (SQLITE_IOERR | (10<<8))
  434. #define SQLITE_IOERR_BLOCKED       (SQLITE_IOERR | (11<<8))
  435. #define SQLITE_IOERR_NOMEM         (SQLITE_IOERR | (12<<8))
  436. /*
  437. ** CAPI3REF: Flags For File Open Operations {F10230}
  438. **
  439. ** These bit values are intended for use in the
  440. ** 3rd parameter to the [sqlite3_open_v2()] interface and
  441. ** in the 4th parameter to the xOpen method of the
  442. ** [sqlite3_vfs] object.
  443. */
  444. #define SQLITE_OPEN_READONLY         0x00000001
  445. #define SQLITE_OPEN_READWRITE        0x00000002
  446. #define SQLITE_OPEN_CREATE           0x00000004
  447. #define SQLITE_OPEN_DELETEONCLOSE    0x00000008
  448. #define SQLITE_OPEN_EXCLUSIVE        0x00000010
  449. #define SQLITE_OPEN_MAIN_DB          0x00000100
  450. #define SQLITE_OPEN_TEMP_DB          0x00000200
  451. #define SQLITE_OPEN_TRANSIENT_DB     0x00000400
  452. #define SQLITE_OPEN_MAIN_JOURNAL     0x00000800
  453. #define SQLITE_OPEN_TEMP_JOURNAL     0x00001000
  454. #define SQLITE_OPEN_SUBJOURNAL       0x00002000
  455. #define SQLITE_OPEN_MASTER_JOURNAL   0x00004000
  456. /*
  457. ** CAPI3REF: Device Characteristics {F10240}
  458. **
  459. ** The xDeviceCapabilities method of the [sqlite3_io_methods]
  460. ** object returns an integer which is a vector of the these
  461. ** bit values expressing I/O characteristics of the mass storage
  462. ** device that holds the file that the [sqlite3_io_methods]
  463. ** refers to.
  464. **
  465. ** The SQLITE_IOCAP_ATOMIC property means that all writes of
  466. ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
  467. ** mean that writes of blocks that are nnn bytes in size and
  468. ** are aligned to an address which is an integer multiple of
  469. ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
  470. ** that when data is appended to a file, the data is appended
  471. ** first then the size of the file is extended, never the other
  472. ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
  473. ** information is written to disk in the same order as calls
  474. ** to xWrite().
  475. */
  476. #define SQLITE_IOCAP_ATOMIC          0x00000001
  477. #define SQLITE_IOCAP_ATOMIC512       0x00000002
  478. #define SQLITE_IOCAP_ATOMIC1K        0x00000004
  479. #define SQLITE_IOCAP_ATOMIC2K        0x00000008
  480. #define SQLITE_IOCAP_ATOMIC4K        0x00000010
  481. #define SQLITE_IOCAP_ATOMIC8K        0x00000020
  482. #define SQLITE_IOCAP_ATOMIC16K       0x00000040
  483. #define SQLITE_IOCAP_ATOMIC32K       0x00000080
  484. #define SQLITE_IOCAP_ATOMIC64K       0x00000100
  485. #define SQLITE_IOCAP_SAFE_APPEND     0x00000200
  486. #define SQLITE_IOCAP_SEQUENTIAL      0x00000400
  487. /*
  488. ** CAPI3REF: File Locking Levels {F10250}
  489. **
  490. ** SQLite uses one of these integer values as the second
  491. ** argument to calls it makes to the xLock() and xUnlock() methods
  492. ** of an [sqlite3_io_methods] object.
  493. */
  494. #define SQLITE_LOCK_NONE          0
  495. #define SQLITE_LOCK_SHARED        1
  496. #define SQLITE_LOCK_RESERVED      2
  497. #define SQLITE_LOCK_PENDING       3
  498. #define SQLITE_LOCK_EXCLUSIVE     4
  499. /*
  500. ** CAPI3REF: Synchronization Type Flags {F10260}
  501. **
  502. ** When SQLite invokes the xSync() method of an
  503. ** [sqlite3_io_methods] object it uses a combination of
  504. ** these integer values as the second argument.
  505. **
  506. ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
  507. ** sync operation only needs to flush data to mass storage.  Inode
  508. ** information need not be flushed. The SQLITE_SYNC_NORMAL flag means 
  509. ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means 
  510. ** to use Mac OS-X style fullsync instead of fsync().
  511. */
  512. #define SQLITE_SYNC_NORMAL        0x00002
  513. #define SQLITE_SYNC_FULL          0x00003
  514. #define SQLITE_SYNC_DATAONLY      0x00010
  515. /*
  516. ** CAPI3REF: OS Interface Open File Handle {F11110}
  517. **
  518. ** An [sqlite3_file] object represents an open file in the OS
  519. ** interface layer.  Individual OS interface implementations will
  520. ** want to subclass this object by appending additional fields
  521. ** for their own use.  The pMethods entry is a pointer to an
  522. ** [sqlite3_io_methods] object that defines methods for performing
  523. ** I/O operations on the open file.
  524. */
  525. typedef struct sqlite3_file sqlite3_file;
  526. struct sqlite3_file {
  527.   const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
  528. };
  529. /*
  530. ** CAPI3REF: OS Interface File Virtual Methods Object {F11120}
  531. **
  532. ** Every file opened by the [sqlite3_vfs] xOpen method contains a pointer to
  533. ** an instance of this object.  This object defines the
  534. ** methods used to perform various operations against the open file.
  535. **
  536. ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
  537. ** [SQLITE_SYNC_FULL].  The first choice is the normal fsync().
  538. *  The second choice is an
  539. ** OS-X style fullsync.  The SQLITE_SYNC_DATA flag may be ORed in to
  540. ** indicate that only the data of the file and not its inode needs to be
  541. ** synced.
  542. ** 
  543. ** The integer values to xLock() and xUnlock() are one of
  544. ** <ul>
  545. ** <li> [SQLITE_LOCK_NONE],
  546. ** <li> [SQLITE_LOCK_SHARED],
  547. ** <li> [SQLITE_LOCK_RESERVED],
  548. ** <li> [SQLITE_LOCK_PENDING], or
  549. ** <li> [SQLITE_LOCK_EXCLUSIVE].
  550. ** </ul>
  551. ** xLock() increases the lock. xUnlock() decreases the lock.  
  552. ** The xCheckReservedLock() method looks
  553. ** to see if any database connection, either in this
  554. ** process or in some other process, is holding an RESERVED,
  555. ** PENDING, or EXCLUSIVE lock on the file.  It returns true
  556. ** if such a lock exists and false if not.
  557. ** 
  558. ** The xFileControl() method is a generic interface that allows custom
  559. ** VFS implementations to directly control an open file using the
  560. ** [sqlite3_file_control()] interface.  The second "op" argument
  561. ** is an integer opcode.   The third
  562. ** argument is a generic pointer which is intended to be a pointer
  563. ** to a structure that may contain arguments or space in which to
  564. ** write return values.  Potential uses for xFileControl() might be
  565. ** functions to enable blocking locks with timeouts, to change the
  566. ** locking strategy (for example to use dot-file locks), to inquire
  567. ** about the status of a lock, or to break stale locks.  The SQLite
  568. ** core reserves opcodes less than 100 for its own use. 
  569. ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
  570. ** Applications that define a custom xFileControl method should use opcodes 
  571. ** greater than 100 to avoid conflicts.
  572. **
  573. ** The xSectorSize() method returns the sector size of the
  574. ** device that underlies the file.  The sector size is the
  575. ** minimum write that can be performed without disturbing
  576. ** other bytes in the file.  The xDeviceCharacteristics()
  577. ** method returns a bit vector describing behaviors of the
  578. ** underlying device:
  579. **
  580. ** <ul>
  581. ** <li> [SQLITE_IOCAP_ATOMIC]
  582. ** <li> [SQLITE_IOCAP_ATOMIC512]
  583. ** <li> [SQLITE_IOCAP_ATOMIC1K]
  584. ** <li> [SQLITE_IOCAP_ATOMIC2K]
  585. ** <li> [SQLITE_IOCAP_ATOMIC4K]
  586. ** <li> [SQLITE_IOCAP_ATOMIC8K]
  587. ** <li> [SQLITE_IOCAP_ATOMIC16K]
  588. ** <li> [SQLITE_IOCAP_ATOMIC32K]
  589. ** <li> [SQLITE_IOCAP_ATOMIC64K]
  590. ** <li> [SQLITE_IOCAP_SAFE_APPEND]
  591. ** <li> [SQLITE_IOCAP_SEQUENTIAL]
  592. ** </ul>
  593. **
  594. ** The SQLITE_IOCAP_ATOMIC property means that all writes of
  595. ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
  596. ** mean that writes of blocks that are nnn bytes in size and
  597. ** are aligned to an address which is an integer multiple of
  598. ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
  599. ** that when data is appended to a file, the data is appended
  600. ** first then the size of the file is extended, never the other
  601. ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
  602. ** information is written to disk in the same order as calls
  603. ** to xWrite().
  604. */
  605. typedef struct sqlite3_io_methods sqlite3_io_methods;
  606. struct sqlite3_io_methods {
  607.   int iVersion;
  608.   int (*xClose)(sqlite3_file*);
  609.   int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
  610.   int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
  611.   int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
  612.   int (*xSync)(sqlite3_file*, int flags);
  613.   int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
  614.   int (*xLock)(sqlite3_file*, int);
  615.   int (*xUnlock)(sqlite3_file*, int);
  616.   int (*xCheckReservedLock)(sqlite3_file*);
  617.   int (*xFileControl)(sqlite3_file*, int op, void *pArg);
  618.   int (*xSectorSize)(sqlite3_file*);
  619.   int (*xDeviceCharacteristics)(sqlite3_file*);
  620.   /* Additional methods may be added in future releases */
  621. };
  622. /*
  623. ** CAPI3REF: Standard File Control Opcodes {F11310}
  624. **
  625. ** These integer constants are opcodes for the xFileControl method
  626. ** of the [sqlite3_io_methods] object and to the [sqlite3_file_control()]
  627. ** interface.
  628. **
  629. ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This
  630. ** opcode causes the xFileControl method to write the current state of
  631. ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
  632. ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
  633. ** into an integer that the pArg argument points to. This capability
  634. ** is used during testing and only needs to be supported when SQLITE_TEST
  635. ** is defined.
  636. */
  637. #define SQLITE_FCNTL_LOCKSTATE        1
  638. /*
  639. ** CAPI3REF: Mutex Handle {F17110}
  640. **
  641. ** The mutex module within SQLite defines [sqlite3_mutex] to be an
  642. ** abstract type for a mutex object.  The SQLite core never looks
  643. ** at the internal representation of an [sqlite3_mutex].  It only
  644. ** deals with pointers to the [sqlite3_mutex] object.
  645. **
  646. ** Mutexes are created using [sqlite3_mutex_alloc()].
  647. */
  648. typedef struct sqlite3_mutex sqlite3_mutex;
  649. /*
  650. ** CAPI3REF: OS Interface Object {F11140}
  651. **
  652. ** An instance of this object defines the interface between the
  653. ** SQLite core and the underlying operating system.  The "vfs"
  654. ** in the name of the object stands for "virtual file system".
  655. **
  656. ** The iVersion field is initially 1 but may be larger for future
  657. ** versions of SQLite.  Additional fields may be appended to this
  658. ** object when the iVersion value is increased.
  659. **
  660. ** The szOsFile field is the size of the subclassed [sqlite3_file]
  661. ** structure used by this VFS.  mxPathname is the maximum length of
  662. ** a pathname in this VFS.
  663. **
  664. ** Registered sqlite3_vfs objects are kept on a linked list formed by
  665. ** the pNext pointer.  The [sqlite3_vfs_register()]
  666. ** and [sqlite3_vfs_unregister()] interfaces manage this list
  667. ** in a thread-safe way.  The [sqlite3_vfs_find()] interface
  668. ** searches the list.
  669. **
  670. ** The pNext field is the only field in the sqlite3_vfs 
  671. ** structure that SQLite will ever modify.  SQLite will only access
  672. ** or modify this field while holding a particular static mutex.
  673. ** The application should never modify anything within the sqlite3_vfs
  674. ** object once the object has been registered.
  675. **
  676. ** The zName field holds the name of the VFS module.  The name must
  677. ** be unique across all VFS modules.
  678. **
  679. ** {F11141} SQLite will guarantee that the zFilename string passed to
  680. ** xOpen() is a full pathname as generated by xFullPathname() and
  681. ** that the string will be valid and unchanged until xClose() is
  682. ** called.  {END} So the [sqlite3_file] can store a pointer to the
  683. ** filename if it needs to remember the filename for some reason.
  684. **
  685. ** {F11142} The flags argument to xOpen() includes all bits set in
  686. ** the flags argument to [sqlite3_open_v2()].  Or if [sqlite3_open()]
  687. ** or [sqlite3_open16()] is used, then flags includes at least
  688. ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. {END}
  689. ** If xOpen() opens a file read-only then it sets *pOutFlags to
  690. ** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be
  691. ** set.
  692. ** 
  693. ** {F11143} SQLite will also add one of the following flags to the xOpen()
  694. ** call, depending on the object being opened:
  695. ** 
  696. ** <ul>
  697. ** <li>  [SQLITE_OPEN_MAIN_DB]
  698. ** <li>  [SQLITE_OPEN_MAIN_JOURNAL]
  699. ** <li>  [SQLITE_OPEN_TEMP_DB]
  700. ** <li>  [SQLITE_OPEN_TEMP_JOURNAL]
  701. ** <li>  [SQLITE_OPEN_TRANSIENT_DB]
  702. ** <li>  [SQLITE_OPEN_SUBJOURNAL]
  703. ** <li>  [SQLITE_OPEN_MASTER_JOURNAL]
  704. ** </ul> {END}
  705. **
  706. ** The file I/O implementation can use the object type flags to
  707. ** changes the way it deals with files.  For example, an application
  708. ** that does not care about crash recovery or rollback might make
  709. ** the open of a journal file a no-op.  Writes to this journal would
  710. ** also be no-ops, and any attempt to read the journal would return 
  711. ** SQLITE_IOERR.  Or the implementation might recognize that a database 
  712. ** file will be doing page-aligned sector reads and writes in a random 
  713. ** order and set up its I/O subsystem accordingly.
  714. ** 
  715. ** SQLite might also add one of the following flags to the xOpen
  716. ** method:
  717. ** 
  718. ** <ul>
  719. ** <li> [SQLITE_OPEN_DELETEONCLOSE]
  720. ** <li> [SQLITE_OPEN_EXCLUSIVE]
  721. ** </ul>
  722. ** 
  723. ** {F11145} The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
  724. ** deleted when it is closed.  {F11146} The [SQLITE_OPEN_DELETEONCLOSE]
  725. ** will be set for TEMP  databases, journals and for subjournals. 
  726. ** {F11147} The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
  727. ** for exclusive access.  This flag is set for all files except
  728. ** for the main database file. {END}
  729. ** 
  730. ** {F11148} At least szOsFile bytes of memory are allocated by SQLite 
  731. ** to hold the  [sqlite3_file] structure passed as the third 
  732. ** argument to xOpen.  {END}  The xOpen method does not have to
  733. ** allocate the structure; it should just fill it in.
  734. ** 
  735. ** {F11149} The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS] 
  736. ** to test for the existance of a file,
  737. ** or [SQLITE_ACCESS_READWRITE] to test to see
  738. ** if a file is readable and writable, or [SQLITE_ACCESS_READ]
  739. ** to test to see if a file is at least readable.  {END} The file can be a 
  740. ** directory.
  741. ** 
  742. ** {F11150} SQLite will always allocate at least mxPathname+1 bytes for
  743. ** the output buffers for xGetTempname and xFullPathname. {F11151} The exact
  744. ** size of the output buffer is also passed as a parameter to both 
  745. ** methods. {END} If the output buffer is not large enough, SQLITE_CANTOPEN
  746. ** should be returned. As this is handled as a fatal error by SQLite,
  747. ** vfs implementations should endeavor to prevent this by setting 
  748. ** mxPathname to a sufficiently large value.
  749. ** 
  750. ** The xRandomness(), xSleep(), and xCurrentTime() interfaces
  751. ** are not strictly a part of the filesystem, but they are
  752. ** included in the VFS structure for completeness.
  753. ** The xRandomness() function attempts to return nBytes bytes
  754. ** of good-quality randomness into zOut.  The return value is
  755. ** the actual number of bytes of randomness obtained.  The
  756. ** xSleep() method causes the calling thread to sleep for at
  757. ** least the number of microseconds given.  The xCurrentTime()
  758. ** method returns a Julian Day Number for the current date and
  759. ** time.
  760. */
  761. typedef struct sqlite3_vfs sqlite3_vfs;
  762. struct sqlite3_vfs {
  763.   int iVersion;            /* Structure version number */
  764.   int szOsFile;            /* Size of subclassed sqlite3_file */
  765.   int mxPathname;          /* Maximum file pathname length */
  766.   sqlite3_vfs *pNext;      /* Next registered VFS */
  767.   const char *zName;       /* Name of this virtual file system */
  768.   void *pAppData;          /* Pointer to application-specific data */
  769.   int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
  770.                int flags, int *pOutFlags);
  771.   int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
  772.   int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);
  773.   int (*xGetTempname)(sqlite3_vfs*, int nOut, char *zOut);
  774.   int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
  775.   void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
  776.   void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
  777.   void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
  778.   void (*xDlClose)(sqlite3_vfs*, void*);
  779.   int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  780.   int (*xSleep)(sqlite3_vfs*, int microseconds);
  781.   int (*xCurrentTime)(sqlite3_vfs*, double*);
  782.   /* New fields may be appended in figure versions.  The iVersion
  783.   ** value will increment whenever this happens. */
  784. };
  785. /*
  786. ** CAPI3REF: Flags for the xAccess VFS method {F11190}
  787. **
  788. ** {F11191} These integer constants can be used as the third parameter to
  789. ** the xAccess method of an [sqlite3_vfs] object. {END}  They determine
  790. ** what kind of permissions the xAccess method is
  791. ** looking for.  {F11192} With SQLITE_ACCESS_EXISTS, the xAccess method
  792. ** simply checks to see if the file exists. {F11193} With
  793. ** SQLITE_ACCESS_READWRITE, the xAccess method checks to see
  794. ** if the file is both readable and writable.  {F11194} With
  795. ** SQLITE_ACCESS_READ the xAccess method
  796. ** checks to see if the file is readable.
  797. */
  798. #define SQLITE_ACCESS_EXISTS    0
  799. #define SQLITE_ACCESS_READWRITE 1
  800. #define SQLITE_ACCESS_READ      2
  801. /*
  802. ** CAPI3REF: Enable Or Disable Extended Result Codes {F12200}
  803. **
  804. ** The sqlite3_extended_result_codes() routine enables or disables the
  805. ** [SQLITE_IOERR_READ | extended result codes] feature of SQLite.
  806. ** The extended result codes are disabled by default for historical
  807. ** compatibility.
  808. **
  809. ** INVARIANTS:
  810. **
  811. ** {F12201} Each new [database connection] has the 
  812. **          [extended result codes] feature
  813. **          disabled by default.
  814. **
  815. ** {F12202} The [sqlite3_extended_result_codes(D,F)] interface will enable
  816. **          [extended result codes] for the 
  817. **          [database connection] D if the F parameter
  818. **          is true, or disable them if F is false.
  819. */
  820. int sqlite3_extended_result_codes(sqlite3*, int onoff);
  821. /*
  822. ** CAPI3REF: Last Insert Rowid {F12220}
  823. **
  824. ** Each entry in an SQLite table has a unique 64-bit signed
  825. ** integer key called the "rowid". The rowid is always available
  826. ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
  827. ** names are not also used by explicitly declared columns. If
  828. ** the table has a column of type INTEGER PRIMARY KEY then that column
  829. ** is another alias for the rowid.
  830. **
  831. ** This routine returns the rowid of the most recent
  832. ** successful INSERT into the database from the database connection
  833. ** shown in the first argument.  If no successful inserts
  834. ** have ever occurred on this database connection, zero is returned.
  835. **
  836. ** If an INSERT occurs within a trigger, then the rowid of the
  837. ** inserted row is returned by this routine as long as the trigger
  838. ** is running.  But once the trigger terminates, the value returned
  839. ** by this routine reverts to the last value inserted before the
  840. ** trigger fired.
  841. **
  842. ** An INSERT that fails due to a constraint violation is not a
  843. ** successful insert and does not change the value returned by this
  844. ** routine.  Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
  845. ** and INSERT OR ABORT make no changes to the return value of this
  846. ** routine when their insertion fails.  When INSERT OR REPLACE 
  847. ** encounters a constraint violation, it does not fail.  The
  848. ** INSERT continues to completion after deleting rows that caused
  849. ** the constraint problem so INSERT OR REPLACE will always change
  850. ** the return value of this interface. 
  851. **
  852. ** For the purposes of this routine, an insert is considered to
  853. ** be successful even if it is subsequently rolled back.
  854. **
  855. ** INVARIANTS:
  856. **
  857. ** {F12221} The [sqlite3_last_insert_rowid()] function returns the
  858. **          rowid of the most recent successful insert done
  859. **          on the same database connection and within the same
  860. **          trigger context, or zero if there have
  861. **          been no qualifying inserts on that connection.
  862. **
  863. ** {F12223} The [sqlite3_last_insert_rowid()] function returns
  864. **          same value when called from the same trigger context
  865. **          immediately before and after a ROLLBACK.
  866. **
  867. ** LIMITATIONS:
  868. **
  869. ** {U12232} If a separate thread does a new insert on the same
  870. **          database connection while the [sqlite3_last_insert_rowid()]
  871. **          function is running and thus changes the last insert rowid,
  872. **          then the value returned by [sqlite3_last_insert_rowid()] is
  873. **          unpredictable and might not equal either the old or the new
  874. **          last insert rowid.
  875. */
  876. sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
  877. /*
  878. ** CAPI3REF: Count The Number Of Rows Modified {F12240}
  879. **
  880. ** This function returns the number of database rows that were changed
  881. ** or inserted or deleted by the most recently completed SQL statement
  882. ** on the connection specified by the first parameter.  Only
  883. ** changes that are directly specified by the INSERT, UPDATE, or
  884. ** DELETE statement are counted.  Auxiliary changes caused by
  885. ** triggers are not counted. Use the [sqlite3_total_changes()] function
  886. ** to find the total number of changes including changes caused by triggers.
  887. **
  888. ** A "row change" is a change to a single row of a single table
  889. ** caused by an INSERT, DELETE, or UPDATE statement.  Rows that
  890. ** are changed as side effects of REPLACE constraint resolution,
  891. ** rollback, ABORT processing, DROP TABLE, or by any other
  892. ** mechanisms do not count as direct row changes.
  893. **
  894. ** A "trigger context" is a scope of execution that begins and
  895. ** ends with the script of a trigger.  Most SQL statements are
  896. ** evaluated outside of any trigger.  This is the "top level"
  897. ** trigger context.  If a trigger fires from the top level, a
  898. ** new trigger context is entered for the duration of that one
  899. ** trigger.  Subtriggers create subcontexts for their duration.
  900. **
  901. ** Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
  902. ** not create a new trigger context.
  903. **
  904. ** This function returns the number of direct row changes in the
  905. ** most recent INSERT, UPDATE, or DELETE statement within the same
  906. ** trigger context.
  907. **
  908. ** So when called from the top level, this function returns the
  909. ** number of changes in the most recent INSERT, UPDATE, or DELETE
  910. ** that also occurred at the top level.
  911. ** Within the body of a trigger, the sqlite3_changes() interface
  912. ** can be called to find the number of
  913. ** changes in the most recently completed INSERT, UPDATE, or DELETE
  914. ** statement within the body of the same trigger.
  915. ** However, the number returned does not include in changes
  916. ** caused by subtriggers since they have their own context.
  917. **
  918. ** SQLite implements the command "DELETE FROM table" without
  919. ** a WHERE clause by dropping and recreating the table.  (This is much
  920. ** faster than going through and deleting individual elements from the
  921. ** table.)  Because of this optimization, the deletions in
  922. ** "DELETE FROM table" are not row changes and will not be counted
  923. ** by the sqlite3_changes() or [sqlite3_total_changes()] functions.
  924. ** To get an accurate count of the number of rows deleted, use
  925. ** "DELETE FROM table WHERE 1" instead.
  926. **
  927. ** INVARIANTS:
  928. **
  929. ** {F12241} The [sqlite3_changes()] function returns the number of
  930. **          row changes caused by the most recent INSERT, UPDATE,
  931. **          or DELETE statement on the same database connection and
  932. **          within the same trigger context, or zero if there have
  933. **          not been any qualifying row changes.
  934. **
  935. ** LIMITATIONS:
  936. **
  937. ** {U12252} If a separate thread makes changes on the same database connection
  938. **          while [sqlite3_changes()] is running then the value returned
  939. **          is unpredictable and unmeaningful.
  940. */
  941. int sqlite3_changes(sqlite3*);
  942. /*
  943. ** CAPI3REF: Total Number Of Rows Modified {F12260}
  944. ***
  945. ** This function returns the number of row changes caused
  946. ** by INSERT, UPDATE or DELETE statements since the database handle
  947. ** was opened.  The count includes all changes from all trigger
  948. ** contexts.  But the count does not include changes used to
  949. ** implement REPLACE constraints, do rollbacks or ABORT processing,
  950. ** or DROP table processing.
  951. ** The changes
  952. ** are counted as soon as the statement that makes them is completed 
  953. ** (when the statement handle is passed to [sqlite3_reset()] or 
  954. ** [sqlite3_finalize()]).
  955. **
  956. ** SQLite implements the command "DELETE FROM table" without
  957. ** a WHERE clause by dropping and recreating the table.  (This is much
  958. ** faster than going
  959. ** through and deleting individual elements from the table.)  Because of
  960. ** this optimization, the change count for "DELETE FROM table" will be
  961. ** zero regardless of the number of elements that were originally in the
  962. ** table. To get an accurate count of the number of rows deleted, use
  963. ** "DELETE FROM table WHERE 1" instead.
  964. **
  965. ** See also the [sqlite3_changes()] interface.
  966. **
  967. ** INVARIANTS:
  968. ** 
  969. ** {F12261} The [sqlite3_total_changes()] returns the total number
  970. **          of row changes caused by INSERT, UPDATE, and/or DELETE
  971. **          statements on the same [database connection], in any
  972. **          trigger context, since the database connection was
  973. **          created.
  974. **
  975. ** LIMITATIONS:
  976. **
  977. ** {U12264} If a separate thread makes changes on the same database connection
  978. **          while [sqlite3_total_changes()] is running then the value 
  979. **          returned is unpredictable and unmeaningful.
  980. */
  981. int sqlite3_total_changes(sqlite3*);
  982. /*
  983. ** CAPI3REF: Interrupt A Long-Running Query {F12270}
  984. **
  985. ** This function causes any pending database operation to abort and
  986. ** return at its earliest opportunity. This routine is typically
  987. ** called in response to a user action such as pressing "Cancel"
  988. ** or Ctrl-C where the user wants a long query operation to halt
  989. ** immediately.
  990. **
  991. ** It is safe to call this routine from a thread different from the
  992. ** thread that is currently running the database operation.  But it
  993. ** is not safe to call this routine with a database connection that
  994. ** is closed or might close before sqlite3_interrupt() returns.
  995. **
  996. ** If an SQL is very nearly finished at the time when sqlite3_interrupt()
  997. ** is called, then it might not have an opportunity to be interrupted.
  998. ** It might continue to completion.
  999. ** An SQL operation that is interrupted will return
  1000. ** [SQLITE_INTERRUPT].  If the interrupted SQL operation is an
  1001. ** INSERT, UPDATE, or DELETE that is inside an explicit transaction, 
  1002. ** then the entire transaction will be rolled back automatically.
  1003. ** A call to sqlite3_interrupt() has no effect on SQL statements
  1004. ** that are started after sqlite3_interrupt() returns.
  1005. **
  1006. ** INVARIANTS:
  1007. **
  1008. ** {F12271} The [sqlite3_interrupt()] interface will force all running
  1009. **          SQL statements associated with the same database connection
  1010. **          to halt after processing at most one additional row of
  1011. **          data.
  1012. **
  1013. ** {F12272} Any SQL statement that is interrupted by [sqlite3_interrupt()]
  1014. **          will return [SQLITE_INTERRUPT].
  1015. **
  1016. ** LIMITATIONS:
  1017. **
  1018. ** {U12279} If the database connection closes while [sqlite3_interrupt()]
  1019. **          is running then bad things will likely happen.
  1020. */
  1021. void sqlite3_interrupt(sqlite3*);
  1022. /*
  1023. ** CAPI3REF: Determine If An SQL Statement Is Complete {F10510}
  1024. **
  1025. ** These routines are useful for command-line input to determine if the
  1026. ** currently entered text seems to form complete a SQL statement or
  1027. ** if additional input is needed before sending the text into
  1028. ** SQLite for parsing.  These routines return true if the input string
  1029. ** appears to be a complete SQL statement.  A statement is judged to be
  1030. ** complete if it ends with a semicolon token and is not a fragment of a
  1031. ** CREATE TRIGGER statement.  Semicolons that are embedded within
  1032. ** string literals or quoted identifier names or comments are not
  1033. ** independent tokens (they are part of the token in which they are
  1034. ** embedded) and thus do not count as a statement terminator.
  1035. **
  1036. ** These routines do not parse the SQL and
  1037. ** so will not detect syntactically incorrect SQL.
  1038. **
  1039. ** INVARIANTS:
  1040. **
  1041. ** {F10511} The sqlite3_complete() and sqlite3_complete16() functions
  1042. **          return true (non-zero) if and only if the last
  1043. **          non-whitespace token in their input is a semicolon that
  1044. **          is not in between the BEGIN and END of a CREATE TRIGGER
  1045. **          statement.
  1046. **
  1047. ** LIMITATIONS:
  1048. **
  1049. ** {U10512} The input to sqlite3_complete() must be a zero-terminated
  1050. **          UTF-8 string.
  1051. **
  1052. ** {U10513} The input to sqlite3_complete16() must be a zero-terminated
  1053. **          UTF-16 string in native byte order.
  1054. */
  1055. int sqlite3_complete(const char *sql);
  1056. int sqlite3_complete16(const void *sql);
  1057. /*
  1058. ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {F12310}
  1059. **
  1060. ** This routine identifies a callback function that might be
  1061. ** invoked whenever an attempt is made to open a database table 
  1062. ** that another thread or process has locked.
  1063. ** If the busy callback is NULL, then [SQLITE_BUSY]
  1064. ** or [SQLITE_IOERR_BLOCKED]
  1065. ** is returned immediately upon encountering the lock.
  1066. ** If the busy callback is not NULL, then the
  1067. ** callback will be invoked with two arguments.  The
  1068. ** first argument to the handler is a copy of the void* pointer which
  1069. ** is the third argument to this routine.  The second argument to
  1070. ** the handler is the number of times that the busy handler has
  1071. ** been invoked for this locking event.   If the
  1072. ** busy callback returns 0, then no additional attempts are made to
  1073. ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
  1074. ** If the callback returns non-zero, then another attempt
  1075. ** is made to open the database for reading and the cycle repeats.
  1076. **
  1077. ** The presence of a busy handler does not guarantee that
  1078. ** it will be invoked when there is lock contention.
  1079. ** If SQLite determines that invoking the busy handler could result in
  1080. ** a deadlock, it will go ahead and return [SQLITE_BUSY] or
  1081. ** [SQLITE_IOERR_BLOCKED] instead of invoking the
  1082. ** busy handler.
  1083. ** Consider a scenario where one process is holding a read lock that
  1084. ** it is trying to promote to a reserved lock and
  1085. ** a second process is holding a reserved lock that it is trying
  1086. ** to promote to an exclusive lock.  The first process cannot proceed
  1087. ** because it is blocked by the second and the second process cannot
  1088. ** proceed because it is blocked by the first.  If both processes
  1089. ** invoke the busy handlers, neither will make any progress.  Therefore,
  1090. ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
  1091. ** will induce the first process to release its read lock and allow
  1092. ** the second process to proceed.
  1093. **
  1094. ** The default busy callback is NULL.
  1095. **
  1096. ** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
  1097. ** when SQLite is in the middle of a large transaction where all the
  1098. ** changes will not fit into the in-memory cache.  SQLite will
  1099. ** already hold a RESERVED lock on the database file, but it needs
  1100. ** to promote this lock to EXCLUSIVE so that it can spill cache
  1101. ** pages into the database file without harm to concurrent
  1102. ** readers.  If it is unable to promote the lock, then the in-memory
  1103. ** cache will be left in an inconsistent state and so the error
  1104. ** code is promoted from the relatively benign [SQLITE_BUSY] to
  1105. ** the more severe [SQLITE_IOERR_BLOCKED].  This error code promotion
  1106. ** forces an automatic rollback of the changes.  See the
  1107. ** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">
  1108. ** CorruptionFollowingBusyError</a> wiki page for a discussion of why
  1109. ** this is important.
  1110. **
  1111. ** There can only be a single busy handler defined for each database
  1112. ** connection.  Setting a new busy handler clears any previous one. 
  1113. ** Note that calling [sqlite3_busy_timeout()] will also set or clear
  1114. ** the busy handler.
  1115. **
  1116. ** INVARIANTS:
  1117. **
  1118. ** {F12311} The [sqlite3_busy_handler()] function replaces the busy handler
  1119. **          callback in the database connection identified by the 1st
  1120. **          parameter with a new busy handler identified by the 2nd and 3rd
  1121. **          parameters.
  1122. **
  1123. ** {F12312} The default busy handler for new database connections is NULL.
  1124. **
  1125. ** {F12314} When two or more database connection share a common cache,
  1126. **          the busy handler for the database connection currently using
  1127. **          the cache is invoked when the cache encounters a lock.
  1128. **
  1129. ** {F12316} If a busy handler callback returns zero, then the SQLite
  1130. **          interface that provoked the locking event will return
  1131. **          [SQLITE_BUSY].
  1132. **
  1133. ** {F12318} SQLite will invokes the busy handler with two argument which
  1134. **          are a copy of the pointer supplied by the 3rd parameter to
  1135. **          [sqlite3_busy_handler()] and a count of the number of prior
  1136. **          invocations of the busy handler for the same locking event.
  1137. **
  1138. ** LIMITATIONS:
  1139. **
  1140. ** {U12319} A busy handler should not call close the database connection
  1141. **          or prepared statement that invoked the busy handler.
  1142. */
  1143. int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
  1144. /*
  1145. ** CAPI3REF: Set A Busy Timeout {F12340}
  1146. **
  1147. ** This routine sets a [sqlite3_busy_handler | busy handler]
  1148. ** that sleeps for a while when a
  1149. ** table is locked.  The handler will sleep multiple times until 
  1150. ** at least "ms" milliseconds of sleeping have been done. {F12343} After
  1151. ** "ms" milliseconds of sleeping, the handler returns 0 which
  1152. ** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
  1153. **
  1154. ** Calling this routine with an argument less than or equal to zero
  1155. ** turns off all busy handlers.
  1156. **
  1157. ** There can only be a single busy handler for a particular database
  1158. ** connection.  If another busy handler was defined  
  1159. ** (using [sqlite3_busy_handler()]) prior to calling
  1160. ** this routine, that other busy handler is cleared.
  1161. **
  1162. ** INVARIANTS:
  1163. **
  1164. ** {F12341} The [sqlite3_busy_timeout()] function overrides any prior
  1165. **          [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting
  1166. **          on the same database connection.
  1167. **
  1168. ** {F12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than
  1169. **          or equal to zero, then the busy handler is cleared so that
  1170. **          all subsequent locking events immediately return [SQLITE_BUSY].
  1171. **
  1172. ** {F12344} If the 2nd parameter to [sqlite3_busy_timeout()] is a positive
  1173. **          number N, then a busy handler is set that repeatedly calls
  1174. **          the xSleep() method in the VFS interface until either the
  1175. **          lock clears or until the cumulative sleep time reported back
  1176. **          by xSleep() exceeds N milliseconds.
  1177. */
  1178. int sqlite3_busy_timeout(sqlite3*, int ms);
  1179. /*
  1180. ** CAPI3REF: Convenience Routines For Running Queries {F12370}
  1181. **
  1182. ** Definition: A <b>result table</b> is memory data structure created by the
  1183. ** [sqlite3_get_table()] interface.  A result table records the
  1184. ** complete query results from one or more queries.
  1185. **
  1186. ** The table conceptually has a number of rows and columns.  But
  1187. ** these numbers are not part of the result table itself.  These
  1188. ** numbers are obtained separately.  Let N be the number of rows
  1189. ** and M be the number of columns.
  1190. **
  1191. ** A result table is an array of pointers to zero-terminated
  1192. ** UTF-8 strings.  There are (N+1)*M elements in the array.  
  1193. ** The first M pointers point to zero-terminated strings that 
  1194. ** contain the names of the columns.
  1195. ** The remaining entries all point to query results.  NULL
  1196. ** values are give a NULL pointer.  All other values are in
  1197. ** their UTF-8 zero-terminated string representation as returned by
  1198. ** [sqlite3_column_text()].
  1199. **
  1200. ** A result table might consists of one or more memory allocations.
  1201. ** It is not safe to pass a result table directly to [sqlite3_free()].
  1202. ** A result table should be deallocated using [sqlite3_free_table()].
  1203. **
  1204. ** As an example of the result table format, suppose a query result
  1205. ** is as follows:
  1206. **
  1207. ** <blockquote><pre>
  1208. **        Name        | Age
  1209. **        -----------------------
  1210. **        Alice       | 43
  1211. **        Bob         | 28
  1212. **        Cindy       | 21
  1213. ** </pre></blockquote>
  1214. **
  1215. ** There are two column (M==2) and three rows (N==3).  Thus the
  1216. ** result table has 8 entries.  Suppose the result table is stored
  1217. ** in an array names azResult.  Then azResult holds this content:
  1218. **
  1219. ** <blockquote><pre>
  1220. **        azResult&#91;0] = "Name";
  1221. **        azResult&#91;1] = "Age";
  1222. **        azResult&#91;2] = "Alice";
  1223. **        azResult&#91;3] = "43";
  1224. **        azResult&#91;4] = "Bob";
  1225. **        azResult&#91;5] = "28";
  1226. **        azResult&#91;6] = "Cindy";
  1227. **        azResult&#91;7] = "21";
  1228. ** </pre></blockquote>
  1229. **
  1230. ** The sqlite3_get_table() function evaluates one or more
  1231. ** semicolon-separated SQL statements in the zero-terminated UTF-8
  1232. ** string of its 2nd parameter.  It returns a result table to the
  1233. ** pointer given in its 3rd parameter.
  1234. **
  1235. ** After the calling function has finished using the result, it should 
  1236. ** pass the pointer to the result table to sqlite3_free_table() in order to 
  1237. ** release the memory that was malloc-ed.  Because of the way the 
  1238. ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
  1239. ** function must not try to call [sqlite3_free()] directly.  Only 
  1240. ** [sqlite3_free_table()] is able to release the memory properly and safely.
  1241. **
  1242. ** The sqlite3_get_table() interface is implemented as a wrapper around
  1243. ** [sqlite3_exec()].  The sqlite3_get_table() routine does not have access
  1244. ** to any internal data structures of SQLite.  It uses only the public
  1245. ** interface defined here.  As a consequence, errors that occur in the
  1246. ** wrapper layer outside of the internal [sqlite3_exec()] call are not
  1247. ** reflected in subsequent calls to [sqlite3_errcode()] or
  1248. ** [sqlite3_errmsg()].
  1249. **
  1250. ** INVARIANTS:
  1251. **
  1252. ** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then
  1253. **          it frees the result table under construction, aborts the
  1254. **          query in process, skips any subsequent queries, sets the
  1255. **          *resultp output pointer to NULL and returns [SQLITE_NOMEM].
  1256. **
  1257. ** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL
  1258. **          then [sqlite3_get_table()] write the number of columns in the
  1259. **          result set of the query into *ncolumn if the query is
  1260. **          successful (if the function returns SQLITE_OK).
  1261. **
  1262. ** {F12374} If the nrow parameter to [sqlite3_get_table()] is not NULL
  1263. **          then [sqlite3_get_table()] write the number of rows in the
  1264. **          result set of the query into *nrow if the query is
  1265. **          successful (if the function returns SQLITE_OK).
  1266. **
  1267. ** {F12376} The [sqlite3_get_table()] function sets its *ncolumn value
  1268. **          to the number of columns in the result set of the query in the
  1269. **          sql parameter, or to zero if the query in sql has an empty
  1270. **          result set.
  1271. */
  1272. int sqlite3_get_table(
  1273.   sqlite3*,             /* An open database */
  1274.   const char *sql,      /* SQL to be evaluated */
  1275.   char ***pResult,      /* Results of the query */
  1276.   int *nrow,            /* Number of result rows written here */
  1277.   int *ncolumn,         /* Number of result columns written here */
  1278.   char **errmsg         /* Error msg written here */
  1279. );
  1280. void sqlite3_free_table(char **result);
  1281. /*
  1282. ** CAPI3REF: Formatted String Printing Functions {F17400}
  1283. **
  1284. ** These routines are workalikes of the "printf()" family of functions
  1285. ** from the standard C library.
  1286. **
  1287. ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
  1288. ** results into memory obtained from [sqlite3_malloc()].
  1289. ** The strings returned by these two routines should be
  1290. ** released by [sqlite3_free()].   Both routines return a
  1291. ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
  1292. ** memory to hold the resulting string.
  1293. **
  1294. ** In sqlite3_snprintf() routine is similar to "snprintf()" from
  1295. ** the standard C library.  The result is written into the
  1296. ** buffer supplied as the second parameter whose size is given by
  1297. ** the first parameter. Note that the order of the
  1298. ** first two parameters is reversed from snprintf().  This is an
  1299. ** historical accident that cannot be fixed without breaking
  1300. ** backwards compatibility.  Note also that sqlite3_snprintf()
  1301. ** returns a pointer to its buffer instead of the number of
  1302. ** characters actually written into the buffer.  We admit that
  1303. ** the number of characters written would be a more useful return
  1304. ** value but we cannot change the implementation of sqlite3_snprintf()
  1305. ** now without breaking compatibility.
  1306. **
  1307. ** As long as the buffer size is greater than zero, sqlite3_snprintf()
  1308. ** guarantees that the buffer is always zero-terminated.  The first
  1309. ** parameter "n" is the total size of the buffer, including space for
  1310. ** the zero terminator.  So the longest string that can be completely
  1311. ** written will be n-1 characters.
  1312. **
  1313. ** These routines all implement some additional formatting
  1314. ** options that are useful for constructing SQL statements.
  1315. ** All of the usual printf formatting options apply.  In addition, there
  1316. ** is are "%q", "%Q", and "%z" options.
  1317. **
  1318. ** The %q option works like %s in that it substitutes a null-terminated
  1319. ** string from the argument list.  But %q also doubles every ''' character.
  1320. ** %q is designed for use inside a string literal.  By doubling each '''
  1321. ** character it escapes that character and allows it to be inserted into
  1322. ** the string.
  1323. **
  1324. ** For example, so some string variable contains text as follows:
  1325. **
  1326. ** <blockquote><pre>
  1327. **  char *zText = "It's a happy day!";
  1328. ** </pre></blockquote>
  1329. **
  1330. ** One can use this text in an SQL statement as follows:
  1331. **
  1332. ** <blockquote><pre>
  1333. **  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
  1334. **  sqlite3_exec(db, zSQL, 0, 0, 0);
  1335. **  sqlite3_free(zSQL);
  1336. ** </pre></blockquote>
  1337. **
  1338. ** Because the %q format string is used, the ''' character in zText
  1339. ** is escaped and the SQL generated is as follows:
  1340. **
  1341. ** <blockquote><pre>
  1342. **  INSERT INTO table1 VALUES('It''s a happy day!')
  1343. ** </pre></blockquote>
  1344. **
  1345. ** This is correct.  Had we used %s instead of %q, the generated SQL
  1346. ** would have looked like this:
  1347. **
  1348. ** <blockquote><pre>
  1349. **  INSERT INTO table1 VALUES('It's a happy day!');
  1350. ** </pre></blockquote>
  1351. **
  1352. ** This second example is an SQL syntax error.  As a general rule you
  1353. ** should always use %q instead of %s when inserting text into a string 
  1354. ** literal.
  1355. **
  1356. ** The %Q option works like %q except it also adds single quotes around
  1357. ** the outside of the total string.  Or if the parameter in the argument
  1358. ** list is a NULL pointer, %Q substitutes the text "NULL" (without single
  1359. ** quotes) in place of the %Q option. {END}  So, for example, one could say:
  1360. **
  1361. ** <blockquote><pre>
  1362. **  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
  1363. **  sqlite3_exec(db, zSQL, 0, 0, 0);
  1364. **  sqlite3_free(zSQL);
  1365. ** </pre></blockquote>
  1366. **
  1367. ** The code above will render a correct SQL statement in the zSQL
  1368. ** variable even if the zText variable is a NULL pointer.
  1369. **
  1370. ** The "%z" formatting option works exactly like "%s" with the
  1371. ** addition that after the string has been read and copied into
  1372. ** the result, [sqlite3_free()] is called on the input string. {END}
  1373. **
  1374. ** INVARIANTS:
  1375. **
  1376. ** {F17403}  The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces
  1377. **           return either pointers to zero-terminated UTF-8 strings held in
  1378. **           memory obtained from [sqlite3_malloc()] or NULL pointers if
  1379. **           a call to [sqlite3_malloc()] fails.
  1380. **
  1381. ** {F17406}  The [sqlite3_snprintf()] interface writes a zero-terminated
  1382. **           UTF-8 string into the buffer pointed to by the second parameter
  1383. **           provided that the first parameter is greater than zero.
  1384. **
  1385. ** {F17407}  The [sqlite3_snprintf()] interface does not writes slots of
  1386. **           its output buffer (the second parameter) outside the range
  1387. **           of 0 through N-1 (where N is the first parameter)
  1388. **           regardless of the length of the string
  1389. **           requested by the format specification.
  1390. **   
  1391. */
  1392. char *sqlite3_mprintf(const char*,...);
  1393. char *sqlite3_vmprintf(const char*, va_list);
  1394. char *sqlite3_snprintf(int,char*,const char*, ...);
  1395. /*
  1396. ** CAPI3REF: Memory Allocation Subsystem {F17300}
  1397. **
  1398. ** The SQLite core  uses these three routines for all of its own
  1399. ** internal memory allocation needs. "Core" in the previous sentence
  1400. ** does not include operating-system specific VFS implementation.  The
  1401. ** windows VFS uses native malloc and free for some operations.
  1402. **
  1403. ** The sqlite3_malloc() routine returns a pointer to a block
  1404. ** of memory at least N bytes in length, where N is the parameter.
  1405. ** If sqlite3_malloc() is unable to obtain sufficient free
  1406. ** memory, it returns a NULL pointer.  If the parameter N to
  1407. ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
  1408. ** a NULL pointer.
  1409. **
  1410. ** Calling sqlite3_free() with a pointer previously returned
  1411. ** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
  1412. ** that it might be reused.  The sqlite3_free() routine is
  1413. ** a no-op if is called with a NULL pointer.  Passing a NULL pointer
  1414. ** to sqlite3_free() is harmless.  After being freed, memory
  1415. ** should neither be read nor written.  Even reading previously freed
  1416. ** memory might result in a segmentation fault or other severe error.
  1417. ** Memory corruption, a segmentation fault, or other severe error
  1418. ** might result if sqlite3_free() is called with a non-NULL pointer that
  1419. ** was not obtained from sqlite3_malloc() or sqlite3_free().
  1420. **
  1421. ** The sqlite3_realloc() interface attempts to resize a
  1422. ** prior memory allocation to be at least N bytes, where N is the
  1423. ** second parameter.  The memory allocation to be resized is the first
  1424. ** parameter.  If the first parameter to sqlite3_realloc()
  1425. ** is a NULL pointer then its behavior is identical to calling
  1426. ** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().
  1427. ** If the second parameter to sqlite3_realloc() is zero or
  1428. ** negative then the behavior is exactly the same as calling
  1429. ** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
  1430. ** Sqlite3_realloc() returns a pointer to a memory allocation
  1431. ** of at least N bytes in size or NULL if sufficient memory is unavailable.
  1432. ** If M is the size of the prior allocation, then min(N,M) bytes
  1433. ** of the prior allocation are copied into the beginning of buffer returned
  1434. ** by sqlite3_realloc() and the prior allocation is freed.
  1435. ** If sqlite3_realloc() returns NULL, then the prior allocation
  1436. ** is not freed.
  1437. **
  1438. ** The memory returned by sqlite3_malloc() and sqlite3_realloc()
  1439. ** is always aligned to at least an 8 byte boundary. {END}
  1440. **
  1441. ** The default implementation
  1442. ** of the memory allocation subsystem uses the malloc(), realloc()
  1443. ** and free() provided by the standard C library. {F17382} However, if 
  1444. ** SQLite is compiled with the following C preprocessor macro
  1445. **
  1446. ** <blockquote> SQLITE_MEMORY_SIZE=<i>NNN</i> </blockquote>
  1447. **
  1448. ** where <i>NNN</i> is an integer, then SQLite create a static
  1449. ** array of at least <i>NNN</i> bytes in size and use that array
  1450. ** for all of its dynamic memory allocation needs. {END}  Additional
  1451. ** memory allocator options may be added in future releases.
  1452. **
  1453. ** In SQLite version 3.5.0 and 3.5.1, it was possible to define
  1454. ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
  1455. ** implementation of these routines to be omitted.  That capability
  1456. ** is no longer provided.  Only built-in memory allocators can be
  1457. ** used.
  1458. **
  1459. ** The windows OS interface layer calls
  1460. ** the system malloc() and free() directly when converting
  1461. ** filenames between the UTF-8 encoding used by SQLite
  1462. ** and whatever filename encoding is used by the particular windows
  1463. ** installation.  Memory allocation errors are detected, but
  1464. ** they are reported back as [SQLITE_CANTOPEN] or
  1465. ** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
  1466. **
  1467. ** INVARIANTS:
  1468. **
  1469. ** {F17303}  The [sqlite3_malloc(N)] interface returns either a pointer to 
  1470. **           newly checked-out block of at least N bytes of memory
  1471. **           that is 8-byte aligned, 
  1472. **           or it returns NULL if it is unable to fulfill the request.
  1473. **
  1474. ** {F17304}  The [sqlite3_malloc(N)] interface returns a NULL pointer if
  1475. **           N is less than or equal to zero.
  1476. **
  1477. ** {F17305}  The [sqlite3_free(P)] interface releases memory previously
  1478. **           returned from [sqlite3_malloc()] or [sqlite3_realloc()],
  1479. **           making it available for reuse.
  1480. **
  1481. ** {F17306}  A call to [sqlite3_free(NULL)] is a harmless no-op.
  1482. **
  1483. ** {F17310}  A call to [sqlite3_realloc(0,N)] is equivalent to a call
  1484. **           to [sqlite3_malloc(N)].
  1485. **
  1486. ** {F17312}  A call to [sqlite3_realloc(P,0)] is equivalent to a call
  1487. **           to [sqlite3_free(P)].
  1488. **
  1489. ** {F17315}  The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()],
  1490. **           and [sqlite3_free()] for all of its memory allocation and
  1491. **           deallocation needs.
  1492. **
  1493. ** {F17318}  The [sqlite3_realloc(P,N)] interface returns either a pointer
  1494. **           to a block of checked-out memory of at least N bytes in size
  1495. **           that is 8-byte aligned, or a NULL pointer.
  1496. **
  1497. ** {F17321}  When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
  1498. **           copies the first K bytes of content from P into the newly allocated
  1499. **           where K is the lessor of N and the size of the buffer P.
  1500. **
  1501. ** {F17322}  When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
  1502. **           releases the buffer P.
  1503. **
  1504. ** {F17323}  When [sqlite3_realloc(P,N)] returns NULL, the buffer P is
  1505. **           not modified or released.
  1506. **
  1507. ** LIMITATIONS:
  1508. **
  1509. ** {U17350}  The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
  1510. **           must be either NULL or else a pointer obtained from a prior
  1511. **           invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that has
  1512. **           not been released.
  1513. **
  1514. ** {U17351}  The application must not read or write any part of 
  1515. **           a block of memory after it has been released using
  1516. **           [sqlite3_free()] or [sqlite3_realloc()].
  1517. **
  1518. */
  1519. void *sqlite3_malloc(int);
  1520. void *sqlite3_realloc(void*, int);
  1521. void sqlite3_free(void*);
  1522. /*
  1523. ** CAPI3REF: Memory Allocator Statistics {F17370}
  1524. **
  1525. ** SQLite provides these two interfaces for reporting on the status
  1526. ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
  1527. ** the memory allocation subsystem included within the SQLite.
  1528. **
  1529. ** INVARIANTS:
  1530. **
  1531. ** {F17371} The [sqlite3_memory_used()] routine returns the
  1532. **          number of bytes of memory currently outstanding 
  1533. **          (malloced but not freed).
  1534. **
  1535. ** {F17373} The [sqlite3_memory_highwater()] routine returns the maximum
  1536. **          value of [sqlite3_memory_used()] 
  1537. **          since the highwater mark was last reset.
  1538. **
  1539. ** {F17374} The values returned by [sqlite3_memory_used()] and
  1540. **          [sqlite3_memory_highwater()] include any overhead
  1541. **          added by SQLite in its implementation of [sqlite3_malloc()],
  1542. **          but not overhead added by the any underlying system library
  1543. **          routines that [sqlite3_malloc()] may call.
  1544. ** 
  1545. ** {F17375} The memory highwater mark is reset to the current value of
  1546. **          [sqlite3_memory_used()] if and only if the parameter to
  1547. **          [sqlite3_memory_highwater()] is true.  The value returned
  1548. **          by [sqlite3_memory_highwater(1)] is the highwater mark
  1549. **          prior to the reset.
  1550. */
  1551. sqlite3_int64 sqlite3_memory_used(void);
  1552. sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
  1553. /*
  1554. ** CAPI3REF: Pseudo-Random Number Generator {F17390}
  1555. **
  1556. ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
  1557. ** select random ROWIDs when inserting new records into a table that
  1558. ** already uses the largest possible ROWID.  The PRNG is also used for
  1559. ** the build-in random() and randomblob() SQL functions.  This interface allows
  1560. ** appliations to access the same PRNG for other purposes.
  1561. **
  1562. ** A call to this routine stores N bytes of randomness into buffer P.
  1563. **
  1564. ** The first time this routine is invoked (either internally or by
  1565. ** the application) the PRNG is seeded using randomness obtained
  1566. ** from the xRandomness method of the default [sqlite3_vfs] object.
  1567. ** On all subsequent invocations, the pseudo-randomness is generated
  1568. ** internally and without recourse to the [sqlite3_vfs] xRandomness
  1569. ** method.
  1570. **
  1571. ** INVARIANTS:
  1572. **
  1573. ** {F17392} The [sqlite3_randomness(N,P)] interface writes N bytes of
  1574. **          high-quality pseudo-randomness into buffer P.
  1575. */
  1576. void sqlite3_randomness(int N, void *P);
  1577. /*
  1578. ** CAPI3REF: Compile-Time Authorization Callbacks {F12500}
  1579. **
  1580. ** This routine registers a authorizer callback with a particular
  1581. ** [database connection], supplied in the first argument.
  1582. ** The authorizer callback is invoked as SQL statements are being compiled
  1583. ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
  1584. ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()].  At various
  1585. ** points during the compilation process, as logic is being created
  1586. ** to perform various actions, the authorizer callback is invoked to
  1587. ** see if those actions are allowed.  The authorizer callback should
  1588. ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
  1589. ** specific action but allow the SQL statement to continue to be
  1590. ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
  1591. ** rejected with an error.   If the authorizer callback returns
  1592. ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
  1593. ** then [sqlite3_prepare_v2()] or equivalent call that triggered
  1594. ** the authorizer will fail with an error message.
  1595. **
  1596. ** When the callback returns [SQLITE_OK], that means the operation
  1597. ** requested is ok.  When the callback returns [SQLITE_DENY], the
  1598. ** [sqlite3_prepare_v2()] or equivalent call that triggered the
  1599. ** authorizer will fail with an error message explaining that
  1600. ** access is denied.  If the authorizer code is [SQLITE_READ]
  1601. ** and the callback returns [SQLITE_IGNORE] then the
  1602. ** [prepared statement] statement is constructed to substitute
  1603. ** a NULL value in place of the table column that would have
  1604. ** been read if [SQLITE_OK] had been returned.  The [SQLITE_IGNORE]
  1605. ** return can be used to deny an untrusted user access to individual
  1606. ** columns of a table.
  1607. **
  1608. ** The first parameter to the authorizer callback is a copy of
  1609. ** the third parameter to the sqlite3_set_authorizer() interface.
  1610. ** The second parameter to the callback is an integer 
  1611. ** [SQLITE_COPY | action code] that specifies the particular action
  1612. ** to be authorized. The third through sixth
  1613. ** parameters to the callback are zero-terminated strings that contain 
  1614. ** additional details about the action to be authorized.
  1615. **
  1616. ** An authorizer is used when [sqlite3_prepare | preparing]
  1617. ** SQL statements from an untrusted
  1618. ** source, to ensure that the SQL statements do not try to access data
  1619. ** that they are not allowed to see, or that they do not try to
  1620. ** execute malicious statements that damage the database.  For
  1621. ** example, an application may allow a user to enter arbitrary
  1622. ** SQL queries for evaluation by a database.  But the application does
  1623. ** not want the user to be able to make arbitrary changes to the
  1624. ** database.  An authorizer could then be put in place while the
  1625. ** user-entered SQL is being [sqlite3_prepare | prepared] that
  1626. ** disallows everything except [SELECT] statements.
  1627. **
  1628. ** Applications that need to process SQL from untrusted sources
  1629. ** might also consider lowering resource limits using [sqlite3_limit()]
  1630. ** and limiting database size using the [max_page_count] [PRAGMA]
  1631. ** in addition to using an authorizer.
  1632. **
  1633. ** Only a single authorizer can be in place on a database connection
  1634. ** at a time.  Each call to sqlite3_set_authorizer overrides the
  1635. ** previous call.  Disable the authorizer by installing a NULL callback.
  1636. ** The authorizer is disabled by default.
  1637. **
  1638. ** Note that the authorizer callback is invoked only during 
  1639. ** [sqlite3_prepare()] or its variants.  Authorization is not
  1640. ** performed during statement evaluation in [sqlite3_step()].
  1641. **
  1642. ** INVARIANTS:
  1643. **
  1644. ** {F12501} The [sqlite3_set_authorizer(D,...)] interface registers a
  1645. **          authorizer callback with database connection D.
  1646. **
  1647. ** {F12502} The authorizer callback is invoked as SQL statements are
  1648. **          being compiled
  1649. **
  1650. ** {F12503} If the authorizer callback returns any value other than
  1651. **          [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] then
  1652. **          the [sqlite3_prepare_v2()] or equivalent call that caused
  1653. **          the authorizer callback to run shall fail with an
  1654. **          [SQLITE_ERROR] error code and an appropriate error message.
  1655. **
  1656. ** {F12504} When the authorizer callback returns [SQLITE_OK], the operation
  1657. **          described is coded normally.
  1658. **
  1659. ** {F12505} When the authorizer callback returns [SQLITE_DENY], the
  1660. **          [sqlite3_prepare_v2()] or equivalent call that caused the
  1661. **          authorizer callback to run shall fail
  1662. **          with an [SQLITE_ERROR] error code and an error message
  1663. **          explaining that access is denied.
  1664. **
  1665. ** {F12506} If the authorizer code (the 2nd parameter to the authorizer
  1666. **          callback) is [SQLITE_READ] and the authorizer callback returns
  1667. **          [SQLITE_IGNORE] then the prepared statement is constructed to
  1668. **          insert a NULL value in place of the table column that would have
  1669. **          been read if [SQLITE_OK] had been returned.
  1670. **
  1671. ** {F12507} If the authorizer code (the 2nd parameter to the authorizer
  1672. **          callback) is anything other than [SQLITE_READ], then
  1673. **          a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY]. 
  1674. **
  1675. ** {F12510} The first parameter to the authorizer callback is a copy of
  1676. **          the third parameter to the [sqlite3_set_authorizer()] interface.
  1677. **
  1678. ** {F12511} The second parameter to the callback is an integer 
  1679. **          [SQLITE_COPY | action code] that specifies the particular action
  1680. **          to be authorized.
  1681. **
  1682. ** {F12512} The third through sixth parameters to the callback are
  1683. **          zero-terminated strings that contain 
  1684. **          additional details about the action to be authorized.
  1685. **
  1686. ** {F12520} Each call to [sqlite3_set_authorizer()] overrides the
  1687. **          any previously installed authorizer.
  1688. **
  1689. ** {F12521} A NULL authorizer means that no authorization
  1690. **          callback is invoked.
  1691. **
  1692. ** {F12522} The default authorizer is NULL.
  1693. */
  1694. int sqlite3_set_authorizer(
  1695.   sqlite3*,
  1696.   int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
  1697.   void *pUserData
  1698. );
  1699. /*
  1700. ** CAPI3REF: Authorizer Return Codes {F12590}
  1701. **
  1702. ** The [sqlite3_set_authorizer | authorizer callback function] must
  1703. ** return either [SQLITE_OK] or one of these two constants in order
  1704. ** to signal SQLite whether or not the action is permitted.  See the
  1705. ** [sqlite3_set_authorizer | authorizer documentation] for additional
  1706. ** information.
  1707. */
  1708. #define SQLITE_DENY   1   /* Abort the SQL statement with an error */
  1709. #define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
  1710. /*
  1711. ** CAPI3REF: Authorizer Action Codes {F12550}
  1712. **
  1713. ** The [sqlite3_set_authorizer()] interface registers a callback function
  1714. ** that is invoked to authorizer certain SQL statement actions.  The
  1715. ** second parameter to the callback is an integer code that specifies
  1716. ** what action is being authorized.  These are the integer action codes that
  1717. ** the authorizer callback may be passed.
  1718. **
  1719. ** These action code values signify what kind of operation is to be 
  1720. ** authorized.  The 3rd and 4th parameters to the authorization
  1721. ** callback function will be parameters or NULL depending on which of these
  1722. ** codes is used as the second parameter.  The 5th parameter to the
  1723. ** authorizer callback is the name of the database ("main", "temp", 
  1724. ** etc.) if applicable.  The 6th parameter to the authorizer callback
  1725. ** is the name of the inner-most trigger or view that is responsible for
  1726. ** the access attempt or NULL if this access attempt is directly from 
  1727. ** top-level SQL code.
  1728. **
  1729. ** INVARIANTS:
  1730. **
  1731. ** {F12551} The second parameter to an 
  1732. **          [sqlite3_set_authorizer | authorizer callback is always an integer
  1733. **          [SQLITE_COPY | authorizer code] that specifies what action
  1734. **          is being authorized.
  1735. **
  1736. ** {F12552} The 3rd and 4th parameters to the 
  1737. **          [sqlite3_set_authorizer | authorization callback function]
  1738. **          will be parameters or NULL depending on which 
  1739. **          [SQLITE_COPY | authorizer code] is used as the second parameter.
  1740. **
  1741. ** {F12553} The 5th parameter to the
  1742. **          [sqlite3_set_authorizer | authorizer callback] is the name
  1743. **          of the database (example: "main", "temp", etc.) if applicable.
  1744. **
  1745. ** {F12554} The 6th parameter to the
  1746. **          [sqlite3_set_authorizer | authorizer callback] is the name
  1747. **          of the inner-most trigger or view that is responsible for
  1748. **          the access attempt or NULL if this access attempt is directly from 
  1749. **          top-level SQL code.
  1750. */
  1751. /******************************************* 3rd ************ 4th ***********/
  1752. #define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
  1753. #define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
  1754. #define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
  1755. #define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
  1756. #define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
  1757. #define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
  1758. #define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
  1759. #define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
  1760. #define SQLITE_DELETE                9   /* Table Name      NULL            */
  1761. #define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
  1762. #define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
  1763. #define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
  1764. #define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
  1765. #define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
  1766. #define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
  1767. #define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
  1768. #define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
  1769. #define SQLITE_INSERT               18   /* Table Name      NULL            */
  1770. #define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
  1771. #define SQLITE_READ                 20   /* Table Name      Column Name     */
  1772. #define SQLITE_SELECT               21   /* NULL            NULL            */
  1773. #define SQLITE_TRANSACTION          22   /* NULL            NULL            */
  1774. #define SQLITE_UPDATE               23   /* Table Name      Column Name     */
  1775. #define SQLITE_ATTACH               24   /* Filename        NULL            */
  1776. #define SQLITE_DETACH               25   /* Database Name   NULL            */
  1777. #define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */
  1778. #define SQLITE_REINDEX              27   /* Index Name      NULL            */
  1779. #define SQLITE_ANALYZE              28   /* Table Name      NULL            */
  1780. #define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
  1781. #define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
  1782. #define SQLITE_FUNCTION             31   /* Function Name   NULL            */
  1783. #define SQLITE_COPY                  0   /* No longer used */
  1784. /*
  1785. ** CAPI3REF: Tracing And Profiling Functions {F12280}
  1786. **
  1787. ** These routines register callback functions that can be used for
  1788. ** tracing and profiling the execution of SQL statements.
  1789. **
  1790. ** The callback function registered by sqlite3_trace() is invoked at
  1791. ** various times when an SQL statement is being run by [sqlite3_step()].
  1792. ** The callback returns a UTF-8 rendering of the SQL statement text
  1793. ** as the statement first begins executing.  Additional callbacks occur
  1794. ** as each triggersubprogram is entered.  The callbacks for triggers
  1795. ** contain a UTF-8 SQL comment that identifies the trigger.
  1796. ** 
  1797. ** The callback function registered by sqlite3_profile() is invoked
  1798. ** as each SQL statement finishes.  The profile callback contains
  1799. ** the original statement text and an estimate of wall-clock time
  1800. ** of how long that statement took to run.
  1801. **
  1802. ** The sqlite3_profile() API is currently considered experimental and
  1803. ** is subject to change or removal in a future release.
  1804. **
  1805. ** The trigger reporting feature of the trace callback is considered
  1806. ** experimental and is subject to change or removal in future releases.
  1807. ** Future versions of SQLite might also add new trace callback 
  1808. ** invocations.
  1809. **
  1810. ** INVARIANTS:
  1811. **
  1812. ** {F12281} The callback function registered by [sqlite3_trace()] is
  1813. **          whenever an SQL statement first begins to execute and
  1814. **          whenever a trigger subprogram first begins to run.
  1815. **
  1816. ** {F12282} Each call to [sqlite3_trace()] overrides the previously
  1817. **          registered trace callback.
  1818. **
  1819. ** {F12283} A NULL trace callback disables tracing.
  1820. **
  1821. ** {F12284} The first argument to the trace callback is a copy of
  1822. **          the pointer which was the 3rd argument to [sqlite3_trace()].
  1823. **
  1824. ** {F12285} The second argument to the trace callback is a
  1825. **          zero-terminated UTF8 string containing the original text
  1826. **          of the SQL statement as it was passed into [sqlite3_prepare_v2()]
  1827. **          or the equivalent, or an SQL comment indicating the beginning
  1828. **          of a trigger subprogram.
  1829. **
  1830. ** {F12287} The callback function registered by [sqlite3_profile()] is invoked
  1831. **          as each SQL statement finishes.
  1832. **
  1833. ** {F12288} The first parameter to the profile callback is a copy of
  1834. **          the 3rd parameter to [sqlite3_profile()].
  1835. **
  1836. ** {F12289} The second parameter to the profile callback is a
  1837. **          zero-terminated UTF-8 string that contains the complete text of
  1838. **          the SQL statement as it was processed by [sqlite3_prepare_v2()]
  1839. **          or the equivalent.
  1840. **
  1841. ** {F12290} The third parameter to the profile  callback is an estimate
  1842. **          of the number of nanoseconds of wall-clock time required to
  1843. **          run the SQL statement from start to finish.
  1844. */
  1845. void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
  1846. void *sqlite3_profile(sqlite3*,
  1847.    void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
  1848. /*
  1849. ** CAPI3REF: Query Progress Callbacks {F12910}
  1850. **
  1851. ** This routine configures a callback function - the
  1852. ** progress callback - that is invoked periodically during long
  1853. ** running calls to [sqlite3_exec()], [sqlite3_step()] and
  1854. ** [sqlite3_get_table()].   An example use for this 
  1855. ** interface is to keep a GUI updated during a large query.
  1856. **
  1857. ** If the progress callback returns non-zero, the opertion is
  1858. ** interrupted.  This feature can be used to implement a
  1859. ** "Cancel" button on a GUI dialog box.
  1860. **
  1861. ** INVARIANTS:
  1862. **
  1863. ** {F12911} The callback function registered by [sqlite3_progress_handler()]
  1864. **          is invoked periodically during long running calls to
  1865. **          [sqlite3_step()].
  1866. **
  1867. ** {F12912} The progress callback is invoked once for every N virtual
  1868. **          machine opcodes, where N is the second argument to 
  1869. **          the [sqlite3_progress_handler()] call that registered
  1870. **          the callback.  <todo>What if N is less than 1?</todo>
  1871. **
  1872. ** {F12913} The progress callback itself is identified by the third
  1873. **          argument to [sqlite3_progress_handler()].
  1874. **
  1875. ** {F12914} The fourth argument [sqlite3_progress_handler()] is a
  1876. ***         void pointer passed to the progress callback
  1877. **          function each time it is invoked.
  1878. **
  1879. ** {F12915} If a call to [sqlite3_step()] results in fewer than
  1880. **          N opcodes being executed,
  1881. **          then the progress callback is never invoked. {END}
  1882. ** 
  1883. ** {F12916} Every call to [sqlite3_progress_handler()]
  1884. **          overwrites any previously registere progress handler.
  1885. **
  1886. ** {F12917} If the progress handler callback is NULL then no progress
  1887. **          handler is invoked.
  1888. **
  1889. ** {F12918} If the progress callback returns a result other than 0, then
  1890. **          the behavior is a if [sqlite3_interrupt()] had been called.
  1891. */
  1892. void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
  1893. /*
  1894. ** CAPI3REF: Opening A New Database Connection {F12700}
  1895. **
  1896. ** These routines open an SQLite database file whose name
  1897. ** is given by the filename argument.
  1898. ** The filename argument is interpreted as UTF-8
  1899. ** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16
  1900. ** in the native byte order for [sqlite3_open16()].
  1901. ** An [sqlite3*] handle is usually returned in *ppDb, even
  1902. ** if an error occurs.  The only exception is if SQLite is unable
  1903. ** to allocate memory to hold the [sqlite3] object, a NULL will
  1904. ** be written into *ppDb instead of a pointer to the [sqlite3] object.
  1905. ** If the database is opened (and/or created)
  1906. ** successfully, then [SQLITE_OK] is returned.  Otherwise an
  1907. ** error code is returned.  The
  1908. ** [sqlite3_errmsg()] or [sqlite3_errmsg16()]  routines can be used to obtain
  1909. ** an English language description of the error.
  1910. **
  1911. ** The default encoding for the database will be UTF-8 if
  1912. ** [sqlite3_open()] or [sqlite3_open_v2()] is called and
  1913. ** UTF-16 in the native byte order if [sqlite3_open16()] is used.
  1914. **
  1915. ** Whether or not an error occurs when it is opened, resources
  1916. ** associated with the [sqlite3*] handle should be released by passing it
  1917. ** to [sqlite3_close()] when it is no longer required.
  1918. **
  1919. ** The [sqlite3_open_v2()] interface works like [sqlite3_open()] 
  1920. ** except that it acccepts two additional parameters for additional control
  1921. ** over the new database connection.  The flags parameter can be
  1922. ** one of:
  1923. **
  1924. ** <ol>
  1925. ** <li>  [SQLITE_OPEN_READONLY]
  1926. ** <li>  [SQLITE_OPEN_READWRITE]
  1927. ** <li>  [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]
  1928. ** </ol>
  1929. **
  1930. ** The first value opens the database read-only. 
  1931. ** If the database does not previously exist, an error is returned.
  1932. ** The second option opens
  1933. ** the database for reading and writing if possible, or reading only if
  1934. ** if the file is write protected.  In either case the database
  1935. ** must already exist or an error is returned.  The third option
  1936. ** opens the database for reading and writing and creates it if it does
  1937. ** not already exist.
  1938. ** The third options is behavior that is always used for [sqlite3_open()]
  1939. ** and [sqlite3_open16()].
  1940. **
  1941. ** If the 4th parameter to [sqlite3_open_v2()] is not one of the
  1942. ** combinations shown above then the behavior is undefined.
  1943. **
  1944. ** If the filename is ":memory:", then an private
  1945. ** in-memory database is created for the connection.  This in-memory
  1946. ** database will vanish when the database connection is closed.  Future
  1947. ** version of SQLite might make use of additional special filenames
  1948. ** that begin with the ":" character.  It is recommended that 
  1949. ** when a database filename really does begin with
  1950. ** ":" that you prefix the filename with a pathname like "./" to
  1951. ** avoid ambiguity.
  1952. **
  1953. ** If the filename is an empty string, then a private temporary
  1954. ** on-disk database will be created.  This private database will be
  1955. ** automatically deleted as soon as the database connection is closed.
  1956. **
  1957. ** The fourth parameter to sqlite3_open_v2() is the name of the
  1958. ** [sqlite3_vfs] object that defines the operating system 
  1959. ** interface that the new database connection should use.  If the
  1960. ** fourth parameter is a NULL pointer then the default [sqlite3_vfs]
  1961. ** object is used.
  1962. **
  1963. ** <b>Note to windows users:</b>  The encoding used for the filename argument
  1964. ** of [sqlite3_open()] and [sqlite3_open_v2()] must be UTF-8, not whatever
  1965. ** codepage is currently defined.  Filenames containing international
  1966. ** characters must be converted to UTF-8 prior to passing them into
  1967. ** [sqlite3_open()] or [sqlite3_open_v2()].
  1968. **
  1969. ** INVARIANTS:
  1970. **
  1971. ** {F12701} The [sqlite3_open()], [sqlite3_open16()], and
  1972. **          [sqlite3_open_v2()] interfaces create a new
  1973. **          [database connection] associated with
  1974. **          the database file given in their first parameter.
  1975. **
  1976. ** {F12702} The filename argument is interpreted as UTF-8
  1977. **          for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16
  1978. **          in the native byte order for [sqlite3_open16()].
  1979. **
  1980. ** {F12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()], 
  1981. **          or [sqlite3_open_v2()] writes a pointer to a new
  1982. **          [database connection] into *ppDb.
  1983. **
  1984. ** {F12704} The [sqlite3_open()], [sqlite3_open16()], and
  1985. **          [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success,
  1986. **          or an appropriate [error code] on failure.
  1987. **
  1988. ** {F12706} The default text encoding for a new database created using
  1989. **          [sqlite3_open()] or [sqlite3_open_v2()] will be UTF-8.
  1990. **
  1991. ** {F12707} The default text encoding for a new database created using
  1992. **          [sqlite3_open16()] will be UTF-16.
  1993. **
  1994. ** {F12709} The [sqlite3_open(F,D)] interface is equivalent to
  1995. **          [sqlite3_open_v2(F,D,G,0)] where the G parameter is
  1996. **          [SQLITE_OPEN_READWRITE]|[SQLITE_OPEN_CREATE].
  1997. **
  1998. ** {F12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
  1999. **          bit value [SQLITE_OPEN_READONLY] then the database is opened
  2000. **          for reading only.
  2001. **
  2002. ** {F12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
  2003. **          bit value [SQLITE_OPEN_READWRITE] then the database is opened
  2004. **          reading and writing if possible, or for reading only if the
  2005. **          file is write protected by the operating system.
  2006. **
  2007. ** {F12713} If the G parameter to [sqlite3_open(v2(F,D,G,V)] omits the
  2008. **          bit value [SQLITE_OPEN_CREATE] and the database does not
  2009. **          previously exist, an error is returned.
  2010. **
  2011. ** {F12714} If the G parameter to [sqlite3_open(v2(F,D,G,V)] contains the
  2012. **          bit value [SQLITE_OPEN_CREATE] and the database does not
  2013. **          previously exist, then an attempt is made to create and
  2014. **          initialize the database.
  2015. **
  2016. ** {F12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()],
  2017. **          or [sqlite3_open_v2()] is ":memory:", then an private,
  2018. **          ephemeral, in-memory database is created for the connection.
  2019. **          <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
  2020. **          in sqlite3_open_v2()?</todo>
  2021. **
  2022. ** {F12719} If the filename is NULL or an empty string, then a private,
  2023. **          ephermeral on-disk database will be created.
  2024. **          <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
  2025. **          in sqlite3_open_v2()?</todo>
  2026. **
  2027. ** {F12721} The [database connection] created by 
  2028. **          [sqlite3_open_v2(F,D,G,V)] will use the
  2029. **          [sqlite3_vfs] object identified by the V parameter, or
  2030. **          the default [sqlite3_vfs] object is V is a NULL pointer.
  2031. */
  2032. int sqlite3_open(
  2033.   const char *filename,   /* Database filename (UTF-8) */
  2034.   sqlite3 **ppDb          /* OUT: SQLite db handle */
  2035. );
  2036. int sqlite3_open16(
  2037.   const void *filename,   /* Database filename (UTF-16) */
  2038.   sqlite3 **ppDb          /* OUT: SQLite db handle */
  2039. );
  2040. int sqlite3_open_v2(
  2041.   const char *filename,   /* Database filename (UTF-8) */
  2042.   sqlite3 **ppDb,         /* OUT: SQLite db handle */
  2043.   int flags,              /* Flags */
  2044.   const char *zVfs        /* Name of VFS module to use */
  2045. );
  2046. /*
  2047. ** CAPI3REF: Error Codes And Messages {F12800}
  2048. **
  2049. ** The sqlite3_errcode() interface returns the numeric
  2050. ** [SQLITE_OK | result code] or [SQLITE_IOERR_READ | extended result code]
  2051. ** for the most recent failed sqlite3_* API call associated
  2052. ** with [sqlite3] handle 'db'. If a prior API call failed but the
  2053. ** most recent API call succeeded, the return value from sqlite3_errcode()
  2054. ** is undefined.
  2055. **
  2056. ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
  2057. ** text that describes the error, as either UTF8 or UTF16 respectively.
  2058. ** Memory to hold the error message string is managed internally.
  2059. ** The application does not need to worry with freeing the result.
  2060. ** However, the error string might be overwritten or deallocated by
  2061. ** subsequent calls to other SQLite interface functions.
  2062. **
  2063. ** INVARIANTS:
  2064. **
  2065. ** {F12801} The [sqlite3_errcode(D)] interface returns the numeric
  2066. **          [SQLITE_OK | result code] or
  2067. **          [SQLITE_IOERR_READ | extended result code]
  2068. **          for the most recently failed interface call associated
  2069. **          with [database connection] D.
  2070. **
  2071. ** {F12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)]
  2072. **          interfaces return English-language text that describes
  2073. **          the error in the mostly recently failed interface call,
  2074. **          encoded as either UTF8 or UTF16 respectively.
  2075. **
  2076. ** {F12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()]
  2077. **          are valid until the next SQLite interface call.
  2078. **
  2079. ** {F12808} Calls to API routines that do not return an error code
  2080. **          (example: [sqlite3_data_count()]) do not
  2081. **          change the error code or message returned by
  2082. **          [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
  2083. **
  2084. ** {F12809} Interfaces that are not associated with a specific
  2085. **          [database connection] (examples:
  2086. **          [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()]
  2087. **          do not change the values returned by
  2088. **          [sqlite3_errcode()], [sqlite3_errmsg()], or [sqlite3_errmsg16()].
  2089. */
  2090. int sqlite3_errcode(sqlite3 *db);
  2091. const char *sqlite3_errmsg(sqlite3*);
  2092. const void *sqlite3_errmsg16(sqlite3*);
  2093. /*
  2094. ** CAPI3REF: SQL Statement Object {F13000}
  2095. ** KEYWORDS: {prepared statement} {prepared statements}
  2096. **
  2097. ** An instance of this object represent single SQL statements.  This
  2098. ** object is variously known as a "prepared statement" or a 
  2099. ** "compiled SQL statement" or simply as a "statement".
  2100. ** 
  2101. ** The life of a statement object goes something like this:
  2102. **
  2103. ** <ol>
  2104. ** <li> Create the object using [sqlite3_prepare_v2()] or a related
  2105. **      function.
  2106. ** <li> Bind values to host parameters using
  2107. **      [sqlite3_bind_blob | sqlite3_bind_* interfaces].
  2108. ** <li> Run the SQL by calling [sqlite3_step()] one or more times.
  2109. ** <li> Reset the statement using [sqlite3_reset()] then go back
  2110. **      to step 2.  Do this zero or more times.
  2111. ** <li> Destroy the object using [sqlite3_finalize()].
  2112. ** </ol>
  2113. **
  2114. ** Refer to documentation on individual methods above for additional
  2115. ** information.
  2116. */
  2117. typedef struct sqlite3_stmt sqlite3_stmt;
  2118. /*
  2119. ** CAPI3REF: Run-time Limits {F12760}
  2120. **
  2121. ** This interface allows the size of various constructs to be limited
  2122. ** on a connection by connection basis.  The first parameter is the
  2123. ** [database connection] whose limit is to be set or queried.  The
  2124. ** second parameter is one of the [limit categories] that define a
  2125. ** class of constructs to be size limited.  The third parameter is the
  2126. ** new limit for that construct.  The function returns the old limit.
  2127. **
  2128. ** If the new limit is a negative number, the limit is unchanged.
  2129. ** For the limit category of SQLITE_LIMIT_XYZ there is a hard upper
  2130. ** bound set by a compile-time C-preprocess macro named SQLITE_MAX_XYZ.
  2131. ** (The "_LIMIT_" in the name is changed to "_MAX_".)
  2132. ** Attempts to increase a limit above its hard upper bound are
  2133. ** silently truncated to the hard upper limit.
  2134. **
  2135. ** Run time limits are intended for use in applications that manage
  2136. ** both their own internal database and also databases that are controlled
  2137. ** by untrusted external sources.  An example application might be a
  2138. ** webbrowser that has its own databases for storing history and
  2139. ** separate databases controlled by javascript applications downloaded
  2140. ** off the internet.  The internal databases can be given the
  2141. ** large, default limits.  Databases managed by external sources can
  2142. ** be given much smaller limits designed to prevent a denial of service
  2143. ** attach.  Developers might also want to use the [sqlite3_set_authorizer()]
  2144. ** interface to further control untrusted SQL.  The size of the database
  2145. ** created by an untrusted script can be contained using the
  2146. ** [max_page_count] [PRAGMA].
  2147. **
  2148. ** This interface is currently considered experimental and is subject
  2149. ** to change or removal without prior notice.
  2150. **
  2151. ** INVARIANTS:
  2152. **
  2153. ** {F12762} A successful call to [sqlite3_limit(D,C,V)] where V is
  2154. **          positive changes the
  2155. **          limit on the size of construct C in [database connection] D
  2156. **          to the lessor of V and the hard upper bound on the size
  2157. **          of C that is set at compile-time.
  2158. **
  2159. ** {F12764} A successful call to [sqlite3_limit(D,C,V)] where V is zero
  2160. **          changes the limit on the size of construct C in
  2161. **          [database connection] D to be the hard upper bound on the size
  2162. **          of C that is set at compile-time.
  2163. **
  2164. ** {F12766} A successful call to [sqlite3_limit(D,C,V)] where V is negative
  2165. **          leaves the state of [database connection] D unchanged.
  2166. **
  2167. ** {F12769} A successful call to [sqlite3_limit(D,C,V)] returns the
  2168. **          value of the limit on the size of construct C in
  2169. **          in [database connection] D as it was prior to the call.
  2170. */
  2171. int sqlite3_limit(sqlite3*, int id, int newVal);
  2172. /*
  2173. ** CAPI3REF: Run-Time Limit Categories {F12790}
  2174. ** KEYWORDS: {limit category} {limit categories}
  2175. ** 
  2176. ** These constants define various aspects of a [database connection]
  2177. ** that can be limited in size by calls to [sqlite3_limit()].
  2178. ** The meanings of the various limits are as follows:
  2179. **
  2180. ** <dl>
  2181. ** <dt>SQLITE_LIMIT_LENGTH</dt>
  2182. ** <dd>The maximum size of any
  2183. ** string or blob or table row.<dd>
  2184. **
  2185. ** <dt>SQLITE_LIMIT_SQL_LENGTH</dt>
  2186. ** <dd>The maximum length of an SQL statement.</dd>
  2187. **
  2188. ** <dt>SQLITE_LIMIT_COLUMN</dt>
  2189. ** <dd>The maximum number of columns in a table definition or in the
  2190. ** result set of a SELECT or the maximum number of columns in an index
  2191. ** or in an ORDER BY or GROUP BY clause.</dd>
  2192. **
  2193. ** <dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
  2194. ** <dd>The maximum depth of the parse tree on any expression.</dd>
  2195. **
  2196. ** <dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
  2197. ** <dd>The maximum number of terms in a compound SELECT statement.</dd>
  2198. **
  2199. ** <dt>SQLITE_LIMIT_VDBE_OP</dt>
  2200. ** <dd>The maximum number of instructions in a virtual machine program
  2201. ** used to implement an SQL statement.</dd>
  2202. **
  2203. ** <dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
  2204. ** <dd>The maximum number of arguments on a function.</dd>
  2205. **
  2206. ** <dt>SQLITE_LIMIT_ATTACHED</dt>
  2207. ** <dd>The maximum number of attached databases.</dd>
  2208. **
  2209. ** <dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
  2210. ** <dd>The maximum length of the pattern argument to the LIKE or
  2211. ** GLOB operators.</dd>
  2212. **
  2213. ** <dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
  2214. ** <dd>The maximum number of variables in an SQL statement that can
  2215. ** be bound.</dd>
  2216. ** </dl>
  2217. */
  2218. #define SQLITE_LIMIT_LENGTH                    0
  2219. #define SQLITE_LIMIT_SQL_LENGTH                1
  2220. #define SQLITE_LIMIT_COLUMN                    2
  2221. #define SQLITE_LIMIT_EXPR_DEPTH                3
  2222. #define SQLITE_LIMIT_COMPOUND_SELECT           4
  2223. #define SQLITE_LIMIT_VDBE_OP                   5
  2224. #define SQLITE_LIMIT_FUNCTION_ARG              6
  2225. #define SQLITE_LIMIT_ATTACHED                  7
  2226. #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8
  2227. #define SQLITE_LIMIT_VARIABLE_NUMBER           9
  2228. /*
  2229. ** CAPI3REF: Compiling An SQL Statement {F13010}
  2230. **
  2231. ** To execute an SQL query, it must first be compiled into a byte-code
  2232. ** program using one of these routines. 
  2233. **
  2234. ** The first argument "db" is an [database connection] 
  2235. ** obtained from a prior call to [sqlite3_open()], [sqlite3_open_v2()]
  2236. ** or [sqlite3_open16()]. 
  2237. ** The second argument "zSql" is the statement to be compiled, encoded
  2238. ** as either UTF-8 or UTF-16.  The sqlite3_prepare() and sqlite3_prepare_v2()
  2239. ** interfaces uses UTF-8 and sqlite3_prepare16() and sqlite3_prepare16_v2()
  2240. ** use UTF-16. {END}
  2241. **
  2242. ** If the nByte argument is less
  2243. ** than zero, then zSql is read up to the first zero terminator.
  2244. ** If nByte is non-negative, then it is the maximum number of 
  2245. ** bytes read from zSql.  When nByte is non-negative, the
  2246. ** zSql string ends at either the first '00' or 'u0000' character or 
  2247. ** the nByte-th byte, whichever comes first. If the caller knows
  2248. ** that the supplied string is nul-terminated, then there is a small
  2249. ** performance advantage to be had by passing an nByte parameter that 
  2250. ** is equal to the number of bytes in the input string <i>including</i> 
  2251. ** the nul-terminator bytes.{END}
  2252. **
  2253. ** *pzTail is made to point to the first byte past the end of the
  2254. ** first SQL statement in zSql.  These routines only compiles the first
  2255. ** statement in zSql, so *pzTail is left pointing to what remains
  2256. ** uncompiled.
  2257. **
  2258. ** *ppStmt is left pointing to a compiled [prepared statement] that can be
  2259. ** executed using [sqlite3_step()].  Or if there is an error, *ppStmt is
  2260. ** set to NULL.  If the input text contains no SQL (if the input
  2261. ** is and empty string or a comment) then *ppStmt is set to NULL.
  2262. ** {U13018} The calling procedure is responsible for deleting the
  2263. ** compiled SQL statement
  2264. ** using [sqlite3_finalize()] after it has finished with it.
  2265. **
  2266. ** On success, [SQLITE_OK] is returned.  Otherwise an 
  2267. ** [error code] is returned.
  2268. **
  2269. ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
  2270. ** recommended for all new programs. The two older interfaces are retained
  2271. ** for backwards compatibility, but their use is discouraged.
  2272. ** In the "v2" interfaces, the prepared statement
  2273. ** that is returned (the [sqlite3_stmt] object) contains a copy of the 
  2274. ** original SQL text. {END} This causes the [sqlite3_step()] interface to
  2275. ** behave a differently in two ways:
  2276. **
  2277. ** <ol>
  2278. ** <li>
  2279. ** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
  2280. ** always used to do, [sqlite3_step()] will automatically recompile the SQL
  2281. ** statement and try to run it again.  If the schema has changed in
  2282. ** a way that makes the statement no longer valid, [sqlite3_step()] will still
  2283. ** return [SQLITE_SCHEMA].  But unlike the legacy behavior, 
  2284. ** [SQLITE_SCHEMA] is now a fatal error.  Calling
  2285. ** [sqlite3_prepare_v2()] again will not make the
  2286. ** error go away.  Note: use [sqlite3_errmsg()] to find the text
  2287. ** of the parsing error that results in an [SQLITE_SCHEMA] return. {END}
  2288. ** </li>
  2289. **
  2290. ** <li>
  2291. ** When an error occurs, 
  2292. ** [sqlite3_step()] will return one of the detailed 
  2293. ** [error codes] or [extended error codes]. 
  2294. ** The legacy behavior was that [sqlite3_step()] would only return a generic
  2295. ** [SQLITE_ERROR] result code and you would have to make a second call to
  2296. ** [sqlite3_reset()] in order to find the underlying cause of the problem.
  2297. ** With the "v2" prepare interfaces, the underlying reason for the error is
  2298. ** returned immediately.
  2299. ** </li>
  2300. ** </ol>
  2301. **
  2302. ** INVARIANTS:
  2303. **
  2304. ** {F13011} The [sqlite3_prepare(db,zSql,...)] and
  2305. **          [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the
  2306. **          text in their zSql parameter as UTF-8.
  2307. **
  2308. ** {F13012} The [sqlite3_prepare16(db,zSql,...)] and
  2309. **          [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the
  2310. **          text in their zSql parameter as UTF-16 in the native byte order.
  2311. **
  2312. ** {F13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
  2313. **          and its variants is less than zero, then SQL text is
  2314. **          read from zSql is read up to the first zero terminator.
  2315. **
  2316. ** {F13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
  2317. **          and its variants is non-negative, then at most nBytes bytes
  2318. **          SQL text is read from zSql.
  2319. **
  2320. ** {F13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants
  2321. **          if the zSql input text contains more than one SQL statement
  2322. **          and pzTail is not NULL, then *pzTail is made to point to the
  2323. **          first byte past the end of the first SQL statement in zSql.
  2324. **          <todo>What does *pzTail point to if there is one statement?</todo>
  2325. **
  2326. ** {F13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)]
  2327. **          or one of its variants writes into *ppStmt a pointer to a new
  2328. **          [prepared statement] or a pointer to NULL
  2329. **          if zSql contains nothing other than whitespace or comments. 
  2330. **
  2331. ** {F13019} The [sqlite3_prepare_v2()] interface and its variants return
  2332. **          [SQLITE_OK] or an appropriate [error code] upon failure.
  2333. **
  2334. ** {F13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its
  2335. **          variants returns an error (any value other than [SQLITE_OK])
  2336. **          it first sets *ppStmt to NULL.
  2337. */
  2338. int sqlite3_prepare(
  2339.   sqlite3 *db,            /* Database handle */
  2340.   const char *zSql,       /* SQL statement, UTF-8 encoded */
  2341.   int nByte,              /* Maximum length of zSql in bytes. */
  2342.   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  2343.   const char **pzTail     /* OUT: Pointer to unused portion of zSql */
  2344. );
  2345. int sqlite3_prepare_v2(
  2346.   sqlite3 *db,            /* Database handle */
  2347.   const char *zSql,       /* SQL statement, UTF-8 encoded */
  2348.   int nByte,              /* Maximum length of zSql in bytes. */
  2349.   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  2350.   const char **pzTail     /* OUT: Pointer to unused portion of zSql */
  2351. );
  2352. int sqlite3_prepare16(
  2353.   sqlite3 *db,            /* Database handle */
  2354.   const void *zSql,       /* SQL statement, UTF-16 encoded */
  2355.   int nByte,              /* Maximum length of zSql in bytes. */
  2356.   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  2357.   const void **pzTail     /* OUT: Pointer to unused portion of zSql */
  2358. );
  2359. int sqlite3_prepare16_v2(
  2360.   sqlite3 *db,            /* Database handle */
  2361.   const void *zSql,       /* SQL statement, UTF-16 encoded */
  2362.   int nByte,              /* Maximum length of zSql in bytes. */
  2363.   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  2364.   const void **pzTail     /* OUT: Pointer to unused portion of zSql */
  2365. );
  2366. /*
  2367. ** CAPIREF: Retrieving Statement SQL {F13100}
  2368. **
  2369. ** This intereface can be used to retrieve a saved copy of the original
  2370. ** SQL text used to create a [prepared statement].
  2371. **
  2372. ** INVARIANTS:
  2373. **
  2374. ** {F13101} If the [prepared statement] passed as 
  2375. **          the an argument to [sqlite3_sql()] was compiled
  2376. **          compiled using either [sqlite3_prepare_v2()] or
  2377. **          [sqlite3_prepare16_v2()],
  2378. **          then [sqlite3_sql()] function returns a pointer to a
  2379. **          zero-terminated string containing a UTF-8 rendering
  2380. **          of the original SQL statement.
  2381. **
  2382. ** {F13102} If the [prepared statement] passed as 
  2383. **          the an argument to [sqlite3_sql()] was compiled
  2384. **          compiled using either [sqlite3_prepare()] or
  2385. **          [sqlite3_prepare16()],
  2386. **          then [sqlite3_sql()] function returns a NULL pointer.
  2387. **
  2388. ** {F13103} The string returned by [sqlite3_sql(S)] is valid until the
  2389. **          [prepared statement] S is deleted using [sqlite3_finalize(S)].
  2390. */
  2391. const char *sqlite3_sql(sqlite3_stmt *pStmt);
  2392. /*
  2393. ** CAPI3REF:  Dynamically Typed Value Object  {F15000}
  2394. ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
  2395. **
  2396. ** SQLite uses the sqlite3_value object to represent all values
  2397. ** that can be stored in a database table.
  2398. ** SQLite uses dynamic typing for the values it stores.  
  2399. ** Values stored in sqlite3_value objects can be
  2400. ** be integers, floating point values, strings, BLOBs, or NULL.
  2401. **
  2402. ** An sqlite3_value object may be either "protected" or "unprotected".
  2403. ** Some interfaces require a protected sqlite3_value.  Other interfaces
  2404. ** will accept either a protected or an unprotected sqlite3_value.
  2405. ** Every interface that accepts sqlite3_value arguments specifies 
  2406. ** whether or not it requires a protected sqlite3_value.
  2407. **
  2408. ** The terms "protected" and "unprotected" refer to whether or not
  2409. ** a mutex is held.  A internal mutex is held for a protected
  2410. ** sqlite3_value object but no mutex is held for an unprotected
  2411. ** sqlite3_value object.  If SQLite is compiled to be single-threaded
  2412. ** (with SQLITE_THREADSAFE=0 and with [sqlite3_threadsafe()] returning 0)
  2413. ** then there is no distinction between
  2414. ** protected and unprotected sqlite3_value objects and they can be
  2415. ** used interchangable.  However, for maximum code portability it
  2416. ** is recommended that applications make the distinction between
  2417. ** between protected and unprotected sqlite3_value objects even if
  2418. ** they are single threaded.
  2419. **
  2420. ** The sqlite3_value objects that are passed as parameters into the
  2421. ** implementation of application-defined SQL functions are protected.
  2422. ** The sqlite3_value object returned by
  2423. ** [sqlite3_column_value()] is unprotected.
  2424. ** Unprotected sqlite3_value objects may only be used with
  2425. ** [sqlite3_result_value()] and [sqlite3_bind_value()].  All other
  2426. ** interfaces that use sqlite3_value require protected sqlite3_value objects.
  2427. */
  2428. typedef struct Mem sqlite3_value;
  2429. /*
  2430. ** CAPI3REF:  SQL Function Context Object {F16001}
  2431. **
  2432. ** The context in which an SQL function executes is stored in an
  2433. ** sqlite3_context object.  A pointer to an sqlite3_context
  2434. ** object is always first parameter to application-defined SQL functions.
  2435. */
  2436. typedef struct sqlite3_context sqlite3_context;
  2437. /*
  2438. ** CAPI3REF:  Binding Values To Prepared Statements {F13500}
  2439. **
  2440. ** In the SQL strings input to [sqlite3_prepare_v2()] and its
  2441. ** variants, literals may be replace by a parameter in one
  2442. ** of these forms:
  2443. **
  2444. ** <ul>
  2445. ** <li>  ?
  2446. ** <li>  ?NNN
  2447. ** <li>  :VVV
  2448. ** <li>  @VVV
  2449. ** <li>  $VVV
  2450. ** </ul>
  2451. **
  2452. ** In the parameter forms shown above NNN is an integer literal,
  2453. ** VVV alpha-numeric parameter name.
  2454. ** The values of these parameters (also called "host parameter names"
  2455. ** or "SQL parameters")
  2456. ** can be set using the sqlite3_bind_*() routines defined here.
  2457. **
  2458. ** The first argument to the sqlite3_bind_*() routines always
  2459. ** is a pointer to the [sqlite3_stmt] object returned from
  2460. ** [sqlite3_prepare_v2()] or its variants. The second
  2461. ** argument is the index of the parameter to be set. The
  2462. ** first parameter has an index of 1.  When the same named
  2463. ** parameter is used more than once, second and subsequent
  2464. ** occurrences have the same index as the first occurrence. 
  2465. ** The index for named parameters can be looked up using the
  2466. ** [sqlite3_bind_parameter_name()] API if desired.  The index
  2467. ** for "?NNN" parameters is the value of NNN.
  2468. ** The NNN value must be between 1 and the compile-time
  2469. ** parameter SQLITE_MAX_VARIABLE_NUMBER (default value: 999).
  2470. **
  2471. ** The third argument is the value to bind to the parameter.
  2472. **
  2473. ** In those
  2474. ** routines that have a fourth argument, its value is the number of bytes
  2475. ** in the parameter.  To be clear: the value is the number of <u>bytes</u>
  2476. ** in the value, not the number of characters. 
  2477. ** If the fourth parameter is negative, the length of the string is
  2478. ** number of bytes up to the first zero terminator.
  2479. **
  2480. ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
  2481. ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
  2482. ** string after SQLite has finished with it. If the fifth argument is
  2483. ** the special value [SQLITE_STATIC], then SQLite assumes that the
  2484. ** information is in static, unmanaged space and does not need to be freed.
  2485. ** If the fifth argument has the value [SQLITE_TRANSIENT], then
  2486. ** SQLite makes its own private copy of the data immediately, before
  2487. ** the sqlite3_bind_*() routine returns.
  2488. **
  2489. ** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
  2490. ** is filled with zeros.  A zeroblob uses a fixed amount of memory
  2491. ** (just an integer to hold it size) while it is being processed.
  2492. ** Zeroblobs are intended to serve as place-holders for BLOBs whose
  2493. ** content is later written using 
  2494. ** [sqlite3_blob_open | increment BLOB I/O] routines. A negative
  2495. ** value for the zeroblob results in a zero-length BLOB.
  2496. **
  2497. ** The sqlite3_bind_*() routines must be called after
  2498. ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
  2499. ** before [sqlite3_step()].
  2500. ** Bindings are not cleared by the [sqlite3_reset()] routine.
  2501. ** Unbound parameters are interpreted as NULL.
  2502. **
  2503. ** These routines return [SQLITE_OK] on success or an error code if
  2504. ** anything goes wrong.  [SQLITE_RANGE] is returned if the parameter
  2505. ** index is out of range.  [SQLITE_NOMEM] is returned if malloc fails.
  2506. ** [SQLITE_MISUSE] might be returned if these routines are called on a
  2507. ** virtual machine that is the wrong state or which has already been finalized.
  2508. ** Detection of misuse is unreliable.  Applications should not depend
  2509. ** on SQLITE_MISUSE returns.  SQLITE_MISUSE is intended to indicate a
  2510. ** a logic error in the application.  Future versions of SQLite might
  2511. ** panic rather than return SQLITE_MISUSE.
  2512. **
  2513. ** See also: [sqlite3_bind_parameter_count()],
  2514. ** [sqlite3_bind_parameter_name()], and
  2515. ** [sqlite3_bind_parameter_index()].
  2516. **
  2517. ** INVARIANTS:
  2518. **
  2519. ** {F13506} The [sqlite3_prepare | SQL statement compiler] recognizes
  2520. **          tokens of the forms "?", "?NNN", "$VVV", ":VVV", and "@VVV"
  2521. **          as SQL parameters, where NNN is any sequence of one or more
  2522. **          digits and where VVV is any sequence of one or more 
  2523. **          alphanumeric characters or "::" optionally followed by
  2524. **          a string containing no spaces and contained within parentheses.
  2525. **
  2526. ** {F13509} The initial value of an SQL parameter is NULL.
  2527. **
  2528. ** {F13512} The index of an "?" SQL parameter is one larger than the
  2529. **          largest index of SQL parameter to the left, or 1 if
  2530. **          the "?" is the leftmost SQL parameter.
  2531. **
  2532. ** {F13515} The index of an "?NNN" SQL parameter is the integer NNN.
  2533. **
  2534. ** {F13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is
  2535. **          the same as the index of leftmost occurances of the same
  2536. **          parameter, or one more than the largest index over all
  2537. **          parameters to the left if this is the first occurrance
  2538. **          of this parameter, or 1 if this is the leftmost parameter.
  2539. **
  2540. ** {F13521} The [sqlite3_prepare | SQL statement compiler] fail with
  2541. **          an [SQLITE_RANGE] error if the index of an SQL parameter
  2542. **          is less than 1 or greater than SQLITE_MAX_VARIABLE_NUMBER.
  2543. **
  2544. ** {F13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)]
  2545. **          associate the value V with all SQL parameters having an
  2546. **          index of N in the [prepared statement] S.
  2547. **
  2548. ** {F13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)]
  2549. **          override prior calls with the same values of S and N.
  2550. **
  2551. ** {F13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)]
  2552. **          persist across calls to [sqlite3_reset(S)].
  2553. **
  2554. ** {F13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
  2555. **          [sqlite3_bind_text(S,N,V,L,D)], or
  2556. **          [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L
  2557. **          bytes of the blob or string pointed to by V, when L
  2558. **          is non-negative.
  2559. **
  2560. ** {F13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or
  2561. **          [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters
  2562. **          from V through the first zero character when L is negative.
  2563. **
  2564. ** {F13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
  2565. **          [sqlite3_bind_text(S,N,V,L,D)], or
  2566. **          [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
  2567. **          constant [SQLITE_STATIC], SQLite assumes that the value V
  2568. **          is held in static unmanaged space that will not change
  2569. **          during the lifetime of the binding.
  2570. **
  2571. ** {F13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
  2572. **          [sqlite3_bind_text(S,N,V,L,D)], or
  2573. **          [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
  2574. **          constant [SQLITE_TRANSIENT], the routine makes a 
  2575. **          private copy of V value before it returns.
  2576. **
  2577. ** {F13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
  2578. **          [sqlite3_bind_text(S,N,V,L,D)], or
  2579. **          [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to
  2580. **          a function, SQLite invokes that function to destroy the
  2581. **          V value after it has finished using the V value.
  2582. **
  2583. ** {F13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound
  2584. **          is a blob of L bytes, or a zero-length blob if L is negative.
  2585. **
  2586. ** {F13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may
  2587. **          be either a [protected sqlite3_value] object or an
  2588. **          [unprotected sqlite3_value] object.
  2589. */
  2590. int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
  2591. int sqlite3_bind_double(sqlite3_stmt*, int, double);
  2592. int sqlite3_bind_int(sqlite3_stmt*, int, int);
  2593. int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
  2594. int sqlite3_bind_null(sqlite3_stmt*, int);
  2595. int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
  2596. int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
  2597. int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
  2598. int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
  2599. /*
  2600. ** CAPI3REF: Number Of SQL Parameters {F13600}
  2601. **
  2602. ** This routine can be used to find the number of SQL parameters
  2603. ** in a prepared statement.  SQL parameters are tokens of the
  2604. ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
  2605. ** place-holders for values that are [sqlite3_bind_blob | bound]
  2606. ** to the parameters at a later time.
  2607. **
  2608. ** This routine actually returns the index of the largest parameter.
  2609. ** For all forms except ?NNN, this will correspond to the number of
  2610. ** unique parameters.  If parameters of the ?NNN are used, there may
  2611. ** be gaps in the list.
  2612. **
  2613. ** See also: [sqlite3_bind_blob|sqlite3_bind()],
  2614. ** [sqlite3_bind_parameter_name()], and
  2615. ** [sqlite3_bind_parameter_index()].
  2616. **
  2617. ** INVARIANTS:
  2618. **
  2619. ** {F13601} The [sqlite3_bind_parameter_count(S)] interface returns
  2620. **          the largest index of all SQL parameters in the
  2621. **          [prepared statement] S, or 0 if S
  2622. **          contains no SQL parameters.
  2623. */
  2624. int sqlite3_bind_parameter_count(sqlite3_stmt*);
  2625. /*
  2626. ** CAPI3REF: Name Of A Host Parameter {F13620}
  2627. **
  2628. ** This routine returns a pointer to the name of the n-th
  2629. ** SQL parameter in a [prepared statement].
  2630. ** SQL parameters of the form ":AAA" or "@AAA" or "$AAA" have a name
  2631. ** which is the string ":AAA" or "@AAA" or "$VVV". 
  2632. ** In other words, the initial ":" or "$" or "@"
  2633. ** is included as part of the name.
  2634. ** Parameters of the form "?" or "?NNN" have no name.
  2635. **
  2636. ** The first host parameter has an index of 1, not 0.
  2637. **
  2638. ** If the value n is out of range or if the n-th parameter is
  2639. ** nameless, then NULL is returned.  The returned string is
  2640. ** always in the UTF-8 encoding even if the named parameter was
  2641. ** originally specified as UTF-16 in [sqlite3_prepare16()] or
  2642. ** [sqlite3_prepare16_v2()].
  2643. **
  2644. ** See also: [sqlite3_bind_blob|sqlite3_bind()],
  2645. ** [sqlite3_bind_parameter_count()], and
  2646. ** [sqlite3_bind_parameter_index()].
  2647. **
  2648. ** INVARIANTS:
  2649. **
  2650. ** {F13621} The [sqlite3_bind_parameter_name(S,N)] interface returns
  2651. **          a UTF-8 rendering of the name of the SQL parameter in
  2652. **          [prepared statement] S having index N, or
  2653. **          NULL if there is no SQL parameter with index N or if the
  2654. **          parameter with index N is an anonymous parameter "?" or
  2655. **          a numbered parameter "?NNN".
  2656. */
  2657. const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
  2658. /*
  2659. ** CAPI3REF: Index Of A Parameter With A Given Name {F13640}
  2660. **
  2661. ** Return the index of an SQL parameter given its name.  The
  2662. ** index value returned is suitable for use as the second
  2663. ** parameter to [sqlite3_bind_blob|sqlite3_bind()].  A zero
  2664. ** is returned if no matching parameter is found.  The parameter
  2665. ** name must be given in UTF-8 even if the original statement
  2666. ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
  2667. **
  2668. ** See also: [sqlite3_bind_blob|sqlite3_bind()],
  2669. ** [sqlite3_bind_parameter_count()], and
  2670. ** [sqlite3_bind_parameter_index()].
  2671. **
  2672. ** INVARIANTS:
  2673. **
  2674. ** {F13641} The [sqlite3_bind_parameter_index(S,N)] interface returns
  2675. **          the index of SQL parameter in [prepared statement]
  2676. **          S whose name matches the UTF-8 string N, or 0 if there is
  2677. **          no match.
  2678. */
  2679. int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
  2680. /*
  2681. ** CAPI3REF: Reset All Bindings On A Prepared Statement {F13660}
  2682. **
  2683. ** Contrary to the intuition of many, [sqlite3_reset()] does not
  2684. ** reset the [sqlite3_bind_blob | bindings] on a 
  2685. ** [prepared statement].  Use this routine to
  2686. ** reset all host parameters to NULL.
  2687. **
  2688. ** INVARIANTS:
  2689. **
  2690. ** {F13661} The [sqlite3_clear_bindings(S)] interface resets all
  2691. **          SQL parameter bindings in [prepared statement] S
  2692. **          back to NULL.
  2693. */
  2694. int sqlite3_clear_bindings(sqlite3_stmt*);
  2695. /*
  2696. ** CAPI3REF: Number Of Columns In A Result Set {F13710}
  2697. **
  2698. ** Return the number of columns in the result set returned by the 
  2699. ** [prepared statement]. This routine returns 0
  2700. ** if pStmt is an SQL statement that does not return data (for 
  2701. ** example an UPDATE).
  2702. **
  2703. ** INVARIANTS:
  2704. **
  2705. ** {F13711} The [sqlite3_column_count(S)] interface returns the number of
  2706. **          columns in the result set generated by the
  2707. **          [prepared statement] S, or 0 if S does not generate
  2708. **          a result set.
  2709. */
  2710. int sqlite3_column_count(sqlite3_stmt *pStmt);
  2711. /*
  2712. ** CAPI3REF: Column Names In A Result Set {F13720}
  2713. **
  2714. ** These routines return the name assigned to a particular column
  2715. ** in the result set of a SELECT statement.  The sqlite3_column_name()
  2716. ** interface returns a pointer to a zero-terminated UTF8 string
  2717. ** and sqlite3_column_name16() returns a pointer to a zero-terminated
  2718. ** UTF16 string.  The first parameter is the
  2719. ** [prepared statement] that implements the SELECT statement.
  2720. ** The second parameter is the column number.  The left-most column is
  2721. ** number 0.
  2722. **
  2723. ** The returned string pointer is valid until either the 
  2724. ** [prepared statement] is destroyed by [sqlite3_finalize()]
  2725. ** or until the next call sqlite3_column_name() or sqlite3_column_name16()
  2726. ** on the same column.
  2727. **
  2728. ** If sqlite3_malloc() fails during the processing of either routine
  2729. ** (for example during a conversion from UTF-8 to UTF-16) then a
  2730. ** NULL pointer is returned.
  2731. **
  2732. ** The name of a result column is the value of the "AS" clause for
  2733. ** that column, if there is an AS clause.  If there is no AS clause
  2734. ** then the name of the column is unspecified and may change from
  2735. ** one release of SQLite to the next.
  2736. **
  2737. ** INVARIANTS:
  2738. **
  2739. ** {F13721} A successful invocation of the [sqlite3_column_name(S,N)]
  2740. **          interface returns the name
  2741. **          of the Nth column (where 0 is the left-most column) for the
  2742. **          result set of [prepared statement] S as a
  2743. **          zero-terminated UTF-8 string.
  2744. **
  2745. ** {F13723} A successful invocation of the [sqlite3_column_name16(S,N)]
  2746. **          interface returns the name
  2747. **          of the Nth column (where 0 is the left-most column) for the
  2748. **          result set of [prepared statement] S as a
  2749. **          zero-terminated UTF-16 string in the native byte order.
  2750. **
  2751. ** {F13724} The [sqlite3_column_name()] and [sqlite3_column_name16()]
  2752. **          interfaces return a NULL pointer if they are unable to
  2753. **          allocate memory memory to hold there normal return strings.
  2754. **
  2755. ** {F13725} If the N parameter to [sqlite3_column_name(S,N)] or
  2756. **          [sqlite3_column_name16(S,N)] is out of range, then the
  2757. **          interfaces returns a NULL pointer.
  2758. ** 
  2759. ** {F13726} The strings returned by [sqlite3_column_name(S,N)] and
  2760. **          [sqlite3_column_name16(S,N)] are valid until the next
  2761. **          call to either routine with the same S and N parameters