Stop using aligned allocation for WeakBlock
[WebKit.git] / WebKitLibraries / WebCoreSQLite3 / sqlite3.h
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.436 2009/03/20 13:15:30 drh Exp $
34 */
35 #ifndef _SQLITE3_H_
36 #define _SQLITE3_H_
37 #include <stdarg.h>     /* Needed for the definition of va_list */
38
39 /*
40 ** Make sure we can call this stuff from C++.
41 */
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45
46
47 /*
48 ** Add the ability to override 'extern'
49 */
50 #ifndef SQLITE_EXTERN
51 # define SQLITE_EXTERN extern
52 #endif
53
54 /*
55 ** These no-op macros are used in front of interfaces to mark those
56 ** interfaces as either deprecated or experimental.  New applications
57 ** should not use deprecated intrfaces - they are support for backwards
58 ** compatibility only.  Application writers should be aware that
59 ** experimental interfaces are subject to change in point releases.
60 **
61 ** These macros used to resolve to various kinds of compiler magic that
62 ** would generate warning messages when they were used.  But that
63 ** compiler magic ended up generating such a flurry of bug reports
64 ** that we have taken it all out and gone back to using simple
65 ** noop macros.
66 */
67 #define SQLITE_DEPRECATED
68 #define SQLITE_EXPERIMENTAL
69
70 /*
71 ** Ensure these symbols were not defined by some previous header file.
72 */
73 #ifdef SQLITE_VERSION
74 # undef SQLITE_VERSION
75 #endif
76 #ifdef SQLITE_VERSION_NUMBER
77 # undef SQLITE_VERSION_NUMBER
78 #endif
79
80 /*
81 ** CAPI3REF: Compile-Time Library Version Numbers {H10010} <S60100>
82 **
83 ** The SQLITE_VERSION and SQLITE_VERSION_NUMBER #defines in
84 ** the sqlite3.h file specify the version of SQLite with which
85 ** that header file is associated.
86 **
87 ** The "version" of SQLite is a string of the form "X.Y.Z".
88 ** The phrase "alpha" or "beta" might be appended after the Z.
89 ** The X value is major version number always 3 in SQLite3.
90 ** The X value only changes when backwards compatibility is
91 ** broken and we intend to never break backwards compatibility.
92 ** The Y value is the minor version number and only changes when
93 ** there are major feature enhancements that are forwards compatible
94 ** but not backwards compatible.
95 ** The Z value is the release number and is incremented with
96 ** each release but resets back to 0 whenever Y is incremented.
97 **
98 ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
99 **
100 ** Requirements: [H10011] [H10014]
101 */
102 #define SQLITE_VERSION         "3.6.12"
103 #define SQLITE_VERSION_NUMBER  3006012
104
105 /*
106 ** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100>
107 ** KEYWORDS: sqlite3_version
108 **
109 ** These features provide the same information as the [SQLITE_VERSION]
110 ** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated
111 ** with the library instead of the header file.  Cautious programmers might
112 ** include a check in their application to verify that
113 ** sqlite3_libversion_number() always returns the value
114 ** [SQLITE_VERSION_NUMBER].
115 **
116 ** The sqlite3_libversion() function returns the same information as is
117 ** in the sqlite3_version[] string constant.  The function is provided
118 ** for use in DLLs since DLL users usually do not have direct access to string
119 ** constants within the DLL.
120 **
121 ** Requirements: [H10021] [H10022] [H10023]
122 */
123 SQLITE_EXTERN const char sqlite3_version[];
124 const char *sqlite3_libversion(void);
125 int sqlite3_libversion_number(void);
126
127 /*
128 ** CAPI3REF: Test To See If The Library Is Threadsafe {H10100} <S60100>
129 **
130 ** SQLite can be compiled with or without mutexes.  When
131 ** the [SQLITE_THREADSAFE] C preprocessor macro 1 or 2, mutexes
132 ** are enabled and SQLite is threadsafe.  When the
133 ** [SQLITE_THREADSAFE] macro is 0, 
134 ** the mutexes are omitted.  Without the mutexes, it is not safe
135 ** to use SQLite concurrently from more than one thread.
136 **
137 ** Enabling mutexes incurs a measurable performance penalty.
138 ** So if speed is of utmost importance, it makes sense to disable
139 ** the mutexes.  But for maximum safety, mutexes should be enabled.
140 ** The default behavior is for mutexes to be enabled.
141 **
142 ** This interface can be used by a program to make sure that the
143 ** version of SQLite that it is linking against was compiled with
144 ** the desired setting of the [SQLITE_THREADSAFE] macro.
145 **
146 ** This interface only reports on the compile-time mutex setting
147 ** of the [SQLITE_THREADSAFE] flag.  If SQLite is compiled with
148 ** SQLITE_THREADSAFE=1 then mutexes are enabled by default but
149 ** can be fully or partially disabled using a call to [sqlite3_config()]
150 ** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
151 ** or [SQLITE_CONFIG_MUTEX].  The return value of this function shows
152 ** only the default compile-time setting, not any run-time changes
153 ** to that setting.
154 **
155 ** See the [threading mode] documentation for additional information.
156 **
157 ** Requirements: [H10101] [H10102]
158 */
159 int sqlite3_threadsafe(void);
160
161 /*
162 ** CAPI3REF: Database Connection Handle {H12000} <S40200>
163 ** KEYWORDS: {database connection} {database connections}
164 **
165 ** Each open SQLite database is represented by a pointer to an instance of
166 ** the opaque structure named "sqlite3".  It is useful to think of an sqlite3
167 ** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and
168 ** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
169 ** is its destructor.  There are many other interfaces (such as
170 ** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
171 ** [sqlite3_busy_timeout()] to name but three) that are methods on an
172 ** sqlite3 object.
173 */
174 typedef struct sqlite3 sqlite3;
175
176 /*
177 ** CAPI3REF: 64-Bit Integer Types {H10200} <S10110>
178 ** KEYWORDS: sqlite_int64 sqlite_uint64
179 **
180 ** Because there is no cross-platform way to specify 64-bit integer types
181 ** SQLite includes typedefs for 64-bit signed and unsigned integers.
182 **
183 ** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
184 ** The sqlite_int64 and sqlite_uint64 types are supported for backwards
185 ** compatibility only.
186 **
187 ** Requirements: [H10201] [H10202]
188 */
189 #ifdef SQLITE_INT64_TYPE
190   typedef SQLITE_INT64_TYPE sqlite_int64;
191   typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
192 #elif defined(_MSC_VER) || defined(__BORLANDC__)
193   typedef __int64 sqlite_int64;
194   typedef unsigned __int64 sqlite_uint64;
195 #else
196   typedef long long int sqlite_int64;
197   typedef unsigned long long int sqlite_uint64;
198 #endif
199 typedef sqlite_int64 sqlite3_int64;
200 typedef sqlite_uint64 sqlite3_uint64;
201
202 /*
203 ** If compiling for a processor that lacks floating point support,
204 ** substitute integer for floating-point.
205 */
206 #ifdef SQLITE_OMIT_FLOATING_POINT
207 # define double sqlite3_int64
208 #endif
209
210 /*
211 ** CAPI3REF: Closing A Database Connection {H12010} <S30100><S40200>
212 **
213 ** This routine is the destructor for the [sqlite3] object.
214 **
215 ** Applications should [sqlite3_finalize | finalize] all [prepared statements]
216 ** and [sqlite3_blob_close | close] all [BLOB handles] associated with
217 ** the [sqlite3] object prior to attempting to close the object.
218 ** The [sqlite3_next_stmt()] interface can be used to locate all
219 ** [prepared statements] associated with a [database connection] if desired.
220 ** Typical code might look like this:
221 **
222 ** <blockquote><pre>
223 ** sqlite3_stmt *pStmt;
224 ** while( (pStmt = sqlite3_next_stmt(db, 0))!=0 ){
225 ** &nbsp;   sqlite3_finalize(pStmt);
226 ** }
227 ** </pre></blockquote>
228 **
229 ** If [sqlite3_close()] is invoked while a transaction is open,
230 ** the transaction is automatically rolled back.
231 **
232 ** The C parameter to [sqlite3_close(C)] must be either a NULL
233 ** pointer or an [sqlite3] object pointer obtained
234 ** from [sqlite3_open()], [sqlite3_open16()], or
235 ** [sqlite3_open_v2()], and not previously closed.
236 **
237 ** Requirements:
238 ** [H12011] [H12012] [H12013] [H12014] [H12015] [H12019]
239 */
240 int sqlite3_close(sqlite3 *);
241
242 /*
243 ** The type for a callback function.
244 ** This is legacy and deprecated.  It is included for historical
245 ** compatibility and is not documented.
246 */
247 typedef int (*sqlite3_callback)(void*,int,char**, char**);
248
249 /*
250 ** CAPI3REF: One-Step Query Execution Interface {H12100} <S10000>
251 **
252 ** The sqlite3_exec() interface is a convenient way of running one or more
253 ** SQL statements without having to write a lot of C code.  The UTF-8 encoded
254 ** SQL statements are passed in as the second parameter to sqlite3_exec().
255 ** The statements are evaluated one by one until either an error or
256 ** an interrupt is encountered, or until they are all done.  The 3rd parameter
257 ** is an optional callback that is invoked once for each row of any query
258 ** results produced by the SQL statements.  The 5th parameter tells where
259 ** to write any error messages.
260 **
261 ** The error message passed back through the 5th parameter is held
262 ** in memory obtained from [sqlite3_malloc()].  To avoid a memory leak,
263 ** the calling application should call [sqlite3_free()] on any error
264 ** message returned through the 5th parameter when it has finished using
265 ** the error message.
266 **
267 ** If the SQL statement in the 2nd parameter is NULL or an empty string
268 ** or a string containing only whitespace and comments, then no SQL
269 ** statements are evaluated and the database is not changed.
270 **
271 ** The sqlite3_exec() interface is implemented in terms of
272 ** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
273 ** The sqlite3_exec() routine does nothing to the database that cannot be done
274 ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
275 **
276 ** The first parameter to [sqlite3_exec()] must be an valid and open
277 ** [database connection].
278 **
279 ** The database connection must not be closed while
280 ** [sqlite3_exec()] is running.
281 **
282 ** The calling function should use [sqlite3_free()] to free
283 ** the memory that *errmsg is left pointing at once the error
284 ** message is no longer needed.
285 **
286 ** The SQL statement text in the 2nd parameter to [sqlite3_exec()]
287 ** must remain unchanged while [sqlite3_exec()] is running.
288 **
289 ** Requirements:
290 ** [H12101] [H12102] [H12104] [H12105] [H12107] [H12110] [H12113] [H12116]
291 ** [H12119] [H12122] [H12125] [H12131] [H12134] [H12137] [H12138]
292 */
293 int sqlite3_exec(
294   sqlite3*,                                  /* An open database */
295   const char *sql,                           /* SQL to be evaluated */
296   int (*callback)(void*,int,char**,char**),  /* Callback function */
297   void *,                                    /* 1st argument to callback */
298   char **errmsg                              /* Error msg written here */
299 );
300
301 /*
302 ** CAPI3REF: Result Codes {H10210} <S10700>
303 ** KEYWORDS: SQLITE_OK {error code} {error codes}
304 ** KEYWORDS: {result code} {result codes}
305 **
306 ** Many SQLite functions return an integer result code from the set shown
307 ** here in order to indicates success or failure.
308 **
309 ** New error codes may be added in future versions of SQLite.
310 **
311 ** See also: [SQLITE_IOERR_READ | extended result codes]
312 */
313 #define SQLITE_OK           0   /* Successful result */
314 /* beginning-of-error-codes */
315 #define SQLITE_ERROR        1   /* SQL error or missing database */
316 #define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
317 #define SQLITE_PERM         3   /* Access permission denied */
318 #define SQLITE_ABORT        4   /* Callback routine requested an abort */
319 #define SQLITE_BUSY         5   /* The database file is locked */
320 #define SQLITE_LOCKED       6   /* A table in the database is locked */
321 #define SQLITE_NOMEM        7   /* A malloc() failed */
322 #define SQLITE_READONLY     8   /* Attempt to write a readonly database */
323 #define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
324 #define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
325 #define SQLITE_CORRUPT     11   /* The database disk image is malformed */
326 #define SQLITE_NOTFOUND    12   /* NOT USED. Table or record not found */
327 #define SQLITE_FULL        13   /* Insertion failed because database is full */
328 #define SQLITE_CANTOPEN    14   /* Unable to open the database file */
329 #define SQLITE_PROTOCOL    15   /* NOT USED. Database lock protocol error */
330 #define SQLITE_EMPTY       16   /* Database is empty */
331 #define SQLITE_SCHEMA      17   /* The database schema changed */
332 #define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
333 #define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
334 #define SQLITE_MISMATCH    20   /* Data type mismatch */
335 #define SQLITE_MISUSE      21   /* Library used incorrectly */
336 #define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
337 #define SQLITE_AUTH        23   /* Authorization denied */
338 #define SQLITE_FORMAT      24   /* Auxiliary database format error */
339 #define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
340 #define SQLITE_NOTADB      26   /* File opened that is not a database file */
341 #define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
342 #define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
343 /* end-of-error-codes */
344
345 /*
346 ** CAPI3REF: Extended Result Codes {H10220} <S10700>
347 ** KEYWORDS: {extended error code} {extended error codes}
348 ** KEYWORDS: {extended result code} {extended result codes}
349 **
350 ** In its default configuration, SQLite API routines return one of 26 integer
351 ** [SQLITE_OK | result codes].  However, experience has shown that many of
352 ** these result codes are too coarse-grained.  They do not provide as
353 ** much information about problems as programmers might like.  In an effort to
354 ** address this, newer versions of SQLite (version 3.3.8 and later) include
355 ** support for additional result codes that provide more detailed information
356 ** about errors. The extended result codes are enabled or disabled
357 ** on a per database connection basis using the
358 ** [sqlite3_extended_result_codes()] API.
359 **
360 ** Some of the available extended result codes are listed here.
361 ** One may expect the number of extended result codes will be expand
362 ** over time.  Software that uses extended result codes should expect
363 ** to see new result codes in future releases of SQLite.
364 **
365 ** The SQLITE_OK result code will never be extended.  It will always
366 ** be exactly zero.
367 */
368 #define SQLITE_IOERR_READ              (SQLITE_IOERR | (1<<8))
369 #define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2<<8))
370 #define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3<<8))
371 #define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4<<8))
372 #define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5<<8))
373 #define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6<<8))
374 #define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7<<8))
375 #define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8<<8))
376 #define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9<<8))
377 #define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10<<8))
378 #define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11<<8))
379 #define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12<<8))
380 #define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13<<8))
381 #define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
382 #define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15<<8))
383 #define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16<<8))
384 #define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17<<8))
385
386 #define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED | (1<<8) )
387
388 /*
389 ** CAPI3REF: Flags For File Open Operations {H10230} <H11120> <H12700>
390 **
391 ** These bit values are intended for use in the
392 ** 3rd parameter to the [sqlite3_open_v2()] interface and
393 ** in the 4th parameter to the xOpen method of the
394 ** [sqlite3_vfs] object.
395 */
396 #define SQLITE_OPEN_READONLY         0x00000001
397 #define SQLITE_OPEN_READWRITE        0x00000002
398 #define SQLITE_OPEN_CREATE           0x00000004
399 #define SQLITE_OPEN_DELETEONCLOSE    0x00000008
400 #define SQLITE_OPEN_EXCLUSIVE        0x00000010
401 #define SQLITE_OPEN_AUTOPROXY        0x00000020
402 #define SQLITE_OPEN_MAIN_DB          0x00000100
403 #define SQLITE_OPEN_TEMP_DB          0x00000200
404 #define SQLITE_OPEN_TRANSIENT_DB     0x00000400
405 #define SQLITE_OPEN_MAIN_JOURNAL     0x00000800
406 #define SQLITE_OPEN_TEMP_JOURNAL     0x00001000
407 #define SQLITE_OPEN_SUBJOURNAL       0x00002000
408 #define SQLITE_OPEN_MASTER_JOURNAL   0x00004000
409 #define SQLITE_OPEN_NOMUTEX          0x00008000
410 #define SQLITE_OPEN_FULLMUTEX        0x00010000
411
412 /*
413 ** CAPI3REF: Device Characteristics {H10240} <H11120>
414 **
415 ** The xDeviceCapabilities method of the [sqlite3_io_methods]
416 ** object returns an integer which is a vector of the these
417 ** bit values expressing I/O characteristics of the mass storage
418 ** device that holds the file that the [sqlite3_io_methods]
419 ** refers to.
420 **
421 ** The SQLITE_IOCAP_ATOMIC property means that all writes of
422 ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
423 ** mean that writes of blocks that are nnn bytes in size and
424 ** are aligned to an address which is an integer multiple of
425 ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
426 ** that when data is appended to a file, the data is appended
427 ** first then the size of the file is extended, never the other
428 ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
429 ** information is written to disk in the same order as calls
430 ** to xWrite().
431 */
432 #define SQLITE_IOCAP_ATOMIC          0x00000001
433 #define SQLITE_IOCAP_ATOMIC512       0x00000002
434 #define SQLITE_IOCAP_ATOMIC1K        0x00000004
435 #define SQLITE_IOCAP_ATOMIC2K        0x00000008
436 #define SQLITE_IOCAP_ATOMIC4K        0x00000010
437 #define SQLITE_IOCAP_ATOMIC8K        0x00000020
438 #define SQLITE_IOCAP_ATOMIC16K       0x00000040
439 #define SQLITE_IOCAP_ATOMIC32K       0x00000080
440 #define SQLITE_IOCAP_ATOMIC64K       0x00000100
441 #define SQLITE_IOCAP_SAFE_APPEND     0x00000200
442 #define SQLITE_IOCAP_SEQUENTIAL      0x00000400
443
444 /*
445 ** CAPI3REF: File Locking Levels {H10250} <H11120> <H11310>
446 **
447 ** SQLite uses one of these integer values as the second
448 ** argument to calls it makes to the xLock() and xUnlock() methods
449 ** of an [sqlite3_io_methods] object.
450 */
451 #define SQLITE_LOCK_NONE          0
452 #define SQLITE_LOCK_SHARED        1
453 #define SQLITE_LOCK_RESERVED      2
454 #define SQLITE_LOCK_PENDING       3
455 #define SQLITE_LOCK_EXCLUSIVE     4
456
457 /*
458 ** CAPI3REF: Synchronization Type Flags {H10260} <H11120>
459 **
460 ** When SQLite invokes the xSync() method of an
461 ** [sqlite3_io_methods] object it uses a combination of
462 ** these integer values as the second argument.
463 **
464 ** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
465 ** sync operation only needs to flush data to mass storage.  Inode
466 ** information need not be flushed. The SQLITE_SYNC_NORMAL flag means
467 ** to use normal fsync() semantics. The SQLITE_SYNC_FULL flag means
468 ** to use Mac OS X style fullsync instead of fsync().
469 */
470 #define SQLITE_SYNC_NORMAL        0x00002
471 #define SQLITE_SYNC_FULL          0x00003
472 #define SQLITE_SYNC_DATAONLY      0x00010
473
474 /*
475 ** CAPI3REF: OS Interface Open File Handle {H11110} <S20110>
476 **
477 ** An [sqlite3_file] object represents an open file in the OS
478 ** interface layer.  Individual OS interface implementations will
479 ** want to subclass this object by appending additional fields
480 ** for their own use.  The pMethods entry is a pointer to an
481 ** [sqlite3_io_methods] object that defines methods for performing
482 ** I/O operations on the open file.
483 */
484 typedef struct sqlite3_file sqlite3_file;
485 struct sqlite3_file {
486   const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
487 };
488
489 /*
490 ** CAPI3REF: OS Interface File Virtual Methods Object {H11120} <S20110>
491 **
492 ** Every file opened by the [sqlite3_vfs] xOpen method populates an
493 ** [sqlite3_file] object (or, more commonly, a subclass of the
494 ** [sqlite3_file] object) with a pointer to an instance of this object.
495 ** This object defines the methods used to perform various operations
496 ** against the open file represented by the [sqlite3_file] object.
497 **
498 ** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
499 ** [SQLITE_SYNC_FULL].  The first choice is the normal fsync().
500 ** The second choice is a Mac OS X style fullsync.  The [SQLITE_SYNC_DATAONLY]
501 ** flag may be ORed in to indicate that only the data of the file
502 ** and not its inode needs to be synced.
503 **
504 ** The integer values to xLock() and xUnlock() are one of
505 ** <ul>
506 ** <li> [SQLITE_LOCK_NONE],
507 ** <li> [SQLITE_LOCK_SHARED],
508 ** <li> [SQLITE_LOCK_RESERVED],
509 ** <li> [SQLITE_LOCK_PENDING], or
510 ** <li> [SQLITE_LOCK_EXCLUSIVE].
511 ** </ul>
512 ** xLock() increases the lock. xUnlock() decreases the lock.
513 ** The xCheckReservedLock() method checks whether any database connection,
514 ** either in this process or in some other process, is holding a RESERVED,
515 ** PENDING, or EXCLUSIVE lock on the file.  It returns true
516 ** if such a lock exists and false otherwise.
517 **
518 ** The xFileControl() method is a generic interface that allows custom
519 ** VFS implementations to directly control an open file using the
520 ** [sqlite3_file_control()] interface.  The second "op" argument is an
521 ** integer opcode.  The third argument is a generic pointer intended to
522 ** point to a structure that may contain arguments or space in which to
523 ** write return values.  Potential uses for xFileControl() might be
524 ** functions to enable blocking locks with timeouts, to change the
525 ** locking strategy (for example to use dot-file locks), to inquire
526 ** about the status of a lock, or to break stale locks.  The SQLite
527 ** core reserves all opcodes less than 100 for its own use.
528 ** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
529 ** Applications that define a custom xFileControl method should use opcodes
530 ** greater than 100 to avoid conflicts.
531 **
532 ** The xSectorSize() method returns the sector size of the
533 ** device that underlies the file.  The sector size is the
534 ** minimum write that can be performed without disturbing
535 ** other bytes in the file.  The xDeviceCharacteristics()
536 ** method returns a bit vector describing behaviors of the
537 ** underlying device:
538 **
539 ** <ul>
540 ** <li> [SQLITE_IOCAP_ATOMIC]
541 ** <li> [SQLITE_IOCAP_ATOMIC512]
542 ** <li> [SQLITE_IOCAP_ATOMIC1K]
543 ** <li> [SQLITE_IOCAP_ATOMIC2K]
544 ** <li> [SQLITE_IOCAP_ATOMIC4K]
545 ** <li> [SQLITE_IOCAP_ATOMIC8K]
546 ** <li> [SQLITE_IOCAP_ATOMIC16K]
547 ** <li> [SQLITE_IOCAP_ATOMIC32K]
548 ** <li> [SQLITE_IOCAP_ATOMIC64K]
549 ** <li> [SQLITE_IOCAP_SAFE_APPEND]
550 ** <li> [SQLITE_IOCAP_SEQUENTIAL]
551 ** </ul>
552 **
553 ** The SQLITE_IOCAP_ATOMIC property means that all writes of
554 ** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
555 ** mean that writes of blocks that are nnn bytes in size and
556 ** are aligned to an address which is an integer multiple of
557 ** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
558 ** that when data is appended to a file, the data is appended
559 ** first then the size of the file is extended, never the other
560 ** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
561 ** information is written to disk in the same order as calls
562 ** to xWrite().
563 **
564 ** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
565 ** in the unread portions of the buffer with zeros.  A VFS that
566 ** fails to zero-fill short reads might seem to work.  However,
567 ** failure to zero-fill short reads will eventually lead to
568 ** database corruption.
569 */
570 typedef struct sqlite3_io_methods sqlite3_io_methods;
571 struct sqlite3_io_methods {
572   int iVersion;
573   int (*xClose)(sqlite3_file*);
574   int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
575   int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
576   int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
577   int (*xSync)(sqlite3_file*, int flags);
578   int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
579   int (*xLock)(sqlite3_file*, int);
580   int (*xUnlock)(sqlite3_file*, int);
581   int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
582   int (*xFileControl)(sqlite3_file*, int op, void *pArg);
583   int (*xSectorSize)(sqlite3_file*);
584   int (*xDeviceCharacteristics)(sqlite3_file*);
585   /* Additional methods may be added in future releases */
586 };
587
588 /*
589 ** CAPI3REF: Standard File Control Opcodes {H11310} <S30800>
590 **
591 ** These integer constants are opcodes for the xFileControl method
592 ** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
593 ** interface.
594 **
595 ** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This
596 ** opcode causes the xFileControl method to write the current state of
597 ** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
598 ** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
599 ** into an integer that the pArg argument points to. This capability
600 ** is used during testing and only needs to be supported when SQLITE_TEST
601 ** is defined.
602 */
603 #define SQLITE_FCNTL_LOCKSTATE        1
604 #define SQLITE_GET_LOCKPROXYFILE      2
605 #define SQLITE_SET_LOCKPROXYFILE      3
606 #define SQLITE_LAST_ERRNO             4
607
608 /*
609 ** CAPI3REF: Mutex Handle {H17110} <S20130>
610 **
611 ** The mutex module within SQLite defines [sqlite3_mutex] to be an
612 ** abstract type for a mutex object.  The SQLite core never looks
613 ** at the internal representation of an [sqlite3_mutex].  It only
614 ** deals with pointers to the [sqlite3_mutex] object.
615 **
616 ** Mutexes are created using [sqlite3_mutex_alloc()].
617 */
618 typedef struct sqlite3_mutex sqlite3_mutex;
619
620 /*
621 ** CAPI3REF: OS Interface Object {H11140} <S20100>
622 **
623 ** An instance of the sqlite3_vfs object defines the interface between
624 ** the SQLite core and the underlying operating system.  The "vfs"
625 ** in the name of the object stands for "virtual file system".
626 **
627 ** The value of the iVersion field is initially 1 but may be larger in
628 ** future versions of SQLite.  Additional fields may be appended to this
629 ** object when the iVersion value is increased.  Note that the structure
630 ** of the sqlite3_vfs object changes in the transaction between
631 ** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
632 ** modified.
633 **
634 ** The szOsFile field is the size of the subclassed [sqlite3_file]
635 ** structure used by this VFS.  mxPathname is the maximum length of
636 ** a pathname in this VFS.
637 **
638 ** Registered sqlite3_vfs objects are kept on a linked list formed by
639 ** the pNext pointer.  The [sqlite3_vfs_register()]
640 ** and [sqlite3_vfs_unregister()] interfaces manage this list
641 ** in a thread-safe way.  The [sqlite3_vfs_find()] interface
642 ** searches the list.  Neither the application code nor the VFS
643 ** implementation should use the pNext pointer.
644 **
645 ** The pNext field is the only field in the sqlite3_vfs
646 ** structure that SQLite will ever modify.  SQLite will only access
647 ** or modify this field while holding a particular static mutex.
648 ** The application should never modify anything within the sqlite3_vfs
649 ** object once the object has been registered.
650 **
651 ** The zName field holds the name of the VFS module.  The name must
652 ** be unique across all VFS modules.
653 **
654 ** SQLite will guarantee that the zFilename parameter to xOpen
655 ** is either a NULL pointer or string obtained
656 ** from xFullPathname().  SQLite further guarantees that
657 ** the string will be valid and unchanged until xClose() is
658 ** called. Because of the previous sentense,
659 ** the [sqlite3_file] can safely store a pointer to the
660 ** filename if it needs to remember the filename for some reason.
661 ** If the zFilename parameter is xOpen is a NULL pointer then xOpen
662 ** must invite its own temporary name for the file.  Whenever the 
663 ** xFilename parameter is NULL it will also be the case that the
664 ** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
665 **
666 ** The flags argument to xOpen() includes all bits set in
667 ** the flags argument to [sqlite3_open_v2()].  Or if [sqlite3_open()]
668 ** or [sqlite3_open16()] is used, then flags includes at least
669 ** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. 
670 ** If xOpen() opens a file read-only then it sets *pOutFlags to
671 ** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be set.
672 **
673 ** SQLite will also add one of the following flags to the xOpen()
674 ** call, depending on the object being opened:
675 **
676 ** <ul>
677 ** <li>  [SQLITE_OPEN_MAIN_DB]
678 ** <li>  [SQLITE_OPEN_MAIN_JOURNAL]
679 ** <li>  [SQLITE_OPEN_TEMP_DB]
680 ** <li>  [SQLITE_OPEN_TEMP_JOURNAL]
681 ** <li>  [SQLITE_OPEN_TRANSIENT_DB]
682 ** <li>  [SQLITE_OPEN_SUBJOURNAL]
683 ** <li>  [SQLITE_OPEN_MASTER_JOURNAL]
684 ** </ul>
685 **
686 ** The file I/O implementation can use the object type flags to
687 ** change the way it deals with files.  For example, an application
688 ** that does not care about crash recovery or rollback might make
689 ** the open of a journal file a no-op.  Writes to this journal would
690 ** also be no-ops, and any attempt to read the journal would return
691 ** SQLITE_IOERR.  Or the implementation might recognize that a database
692 ** file will be doing page-aligned sector reads and writes in a random
693 ** order and set up its I/O subsystem accordingly.
694 **
695 ** SQLite might also add one of the following flags to the xOpen method:
696 **
697 ** <ul>
698 ** <li> [SQLITE_OPEN_DELETEONCLOSE]
699 ** <li> [SQLITE_OPEN_EXCLUSIVE]
700 ** </ul>
701 **
702 ** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
703 ** deleted when it is closed.  The [SQLITE_OPEN_DELETEONCLOSE]
704 ** will be set for TEMP  databases, journals and for subjournals.
705 **
706 ** The [SQLITE_OPEN_EXCLUSIVE] flag means the file should be opened
707 ** for exclusive access.  This flag is set for all files except
708 ** for the main database file.
709 **
710 ** At least szOsFile bytes of memory are allocated by SQLite
711 ** to hold the  [sqlite3_file] structure passed as the third
712 ** argument to xOpen.  The xOpen method does not have to
713 ** allocate the structure; it should just fill it in.
714 **
715 ** The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
716 ** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
717 ** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
718 ** to test whether a file is at least readable.   The file can be a
719 ** directory.
720 **
721 ** SQLite will always allocate at least mxPathname+1 bytes for the
722 ** output buffer xFullPathname.  The exact size of the output buffer
723 ** is also passed as a parameter to both  methods. If the output buffer
724 ** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
725 ** handled as a fatal error by SQLite, vfs implementations should endeavor
726 ** to prevent this by setting mxPathname to a sufficiently large value.
727 **
728 ** The xRandomness(), xSleep(), and xCurrentTime() interfaces
729 ** are not strictly a part of the filesystem, but they are
730 ** included in the VFS structure for completeness.
731 ** The xRandomness() function attempts to return nBytes bytes
732 ** of good-quality randomness into zOut.  The return value is
733 ** the actual number of bytes of randomness obtained.
734 ** The xSleep() method causes the calling thread to sleep for at
735 ** least the number of microseconds given.  The xCurrentTime()
736 ** method returns a Julian Day Number for the current date and time.
737 **
738 */
739 typedef struct sqlite3_vfs sqlite3_vfs;
740 struct sqlite3_vfs {
741   int iVersion;            /* Structure version number */
742   int szOsFile;            /* Size of subclassed sqlite3_file */
743   int mxPathname;          /* Maximum file pathname length */
744   sqlite3_vfs *pNext;      /* Next registered VFS */
745   const char *zName;       /* Name of this virtual file system */
746   void *pAppData;          /* Pointer to application-specific data */
747   int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
748                int flags, int *pOutFlags);
749   int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
750   int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
751   int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
752   void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
753   void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
754   void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
755   void (*xDlClose)(sqlite3_vfs*, void*);
756   int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
757   int (*xSleep)(sqlite3_vfs*, int microseconds);
758   int (*xCurrentTime)(sqlite3_vfs*, double*);
759   int (*xGetLastError)(sqlite3_vfs*, int, char *);
760   /* New fields may be appended in figure versions.  The iVersion
761   ** value will increment whenever this happens. */
762 };
763
764 /*
765 ** CAPI3REF: Flags for the xAccess VFS method {H11190} <H11140>
766 **
767 ** These integer constants can be used as the third parameter to
768 ** the xAccess method of an [sqlite3_vfs] object. {END}  They determine
769 ** what kind of permissions the xAccess method is looking for.
770 ** With SQLITE_ACCESS_EXISTS, the xAccess method
771 ** simply checks whether the file exists.
772 ** With SQLITE_ACCESS_READWRITE, the xAccess method
773 ** checks whether the file is both readable and writable.
774 ** With SQLITE_ACCESS_READ, the xAccess method
775 ** checks whether the file is readable.
776 */
777 #define SQLITE_ACCESS_EXISTS    0
778 #define SQLITE_ACCESS_READWRITE 1
779 #define SQLITE_ACCESS_READ      2
780
781 /*
782 ** CAPI3REF: Initialize The SQLite Library {H10130} <S20000><S30100>
783 **
784 ** The sqlite3_initialize() routine initializes the
785 ** SQLite library.  The sqlite3_shutdown() routine
786 ** deallocates any resources that were allocated by sqlite3_initialize().
787 **
788 ** A call to sqlite3_initialize() is an "effective" call if it is
789 ** the first time sqlite3_initialize() is invoked during the lifetime of
790 ** the process, or if it is the first time sqlite3_initialize() is invoked
791 ** following a call to sqlite3_shutdown().  Only an effective call
792 ** of sqlite3_initialize() does any initialization.  All other calls
793 ** are harmless no-ops.
794 **
795 ** Among other things, sqlite3_initialize() shall invoke
796 ** sqlite3_os_init().  Similarly, sqlite3_shutdown()
797 ** shall invoke sqlite3_os_end().
798 **
799 ** The sqlite3_initialize() routine returns [SQLITE_OK] on success.
800 ** If for some reason, sqlite3_initialize() is unable to initialize
801 ** the library (perhaps it is unable to allocate a needed resource such
802 ** as a mutex) it returns an [error code] other than [SQLITE_OK].
803 **
804 ** The sqlite3_initialize() routine is called internally by many other
805 ** SQLite interfaces so that an application usually does not need to
806 ** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]
807 ** calls sqlite3_initialize() so the SQLite library will be automatically
808 ** initialized when [sqlite3_open()] is called if it has not be initialized
809 ** already.  However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
810 ** compile-time option, then the automatic calls to sqlite3_initialize()
811 ** are omitted and the application must call sqlite3_initialize() directly
812 ** prior to using any other SQLite interface.  For maximum portability,
813 ** it is recommended that applications always invoke sqlite3_initialize()
814 ** directly prior to using any other SQLite interface.  Future releases
815 ** of SQLite may require this.  In other words, the behavior exhibited
816 ** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
817 ** default behavior in some future release of SQLite.
818 **
819 ** The sqlite3_os_init() routine does operating-system specific
820 ** initialization of the SQLite library.  The sqlite3_os_end()
821 ** routine undoes the effect of sqlite3_os_init().  Typical tasks
822 ** performed by these routines include allocation or deallocation
823 ** of static resources, initialization of global variables,
824 ** setting up a default [sqlite3_vfs] module, or setting up
825 ** a default configuration using [sqlite3_config()].
826 **
827 ** The application should never invoke either sqlite3_os_init()
828 ** or sqlite3_os_end() directly.  The application should only invoke
829 ** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()
830 ** interface is called automatically by sqlite3_initialize() and
831 ** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate
832 ** implementations for sqlite3_os_init() and sqlite3_os_end()
833 ** are built into SQLite when it is compiled for unix, windows, or os/2.
834 ** When built for other platforms (using the [SQLITE_OS_OTHER=1] compile-time
835 ** option) the application must supply a suitable implementation for
836 ** sqlite3_os_init() and sqlite3_os_end().  An application-supplied
837 ** implementation of sqlite3_os_init() or sqlite3_os_end()
838 ** must return [SQLITE_OK] on success and some other [error code] upon
839 ** failure.
840 */
841 int sqlite3_initialize(void);
842 int sqlite3_shutdown(void);
843 int sqlite3_os_init(void);
844 int sqlite3_os_end(void);
845
846 /*
847 ** CAPI3REF: Configuring The SQLite Library {H14100} <S20000><S30200>
848 ** EXPERIMENTAL
849 **
850 ** The sqlite3_config() interface is used to make global configuration
851 ** changes to SQLite in order to tune SQLite to the specific needs of
852 ** the application.  The default configuration is recommended for most
853 ** applications and so this routine is usually not necessary.  It is
854 ** provided to support rare applications with unusual needs.
855 **
856 ** The sqlite3_config() interface is not threadsafe.  The application
857 ** must insure that no other SQLite interfaces are invoked by other
858 ** threads while sqlite3_config() is running.  Furthermore, sqlite3_config()
859 ** may only be invoked prior to library initialization using
860 ** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
861 ** Note, however, that sqlite3_config() can be called as part of the
862 ** implementation of an application-defined [sqlite3_os_init()].
863 **
864 ** The first argument to sqlite3_config() is an integer
865 ** [SQLITE_CONFIG_SINGLETHREAD | configuration option] that determines
866 ** what property of SQLite is to be configured.  Subsequent arguments
867 ** vary depending on the [SQLITE_CONFIG_SINGLETHREAD | configuration option]
868 ** in the first argument.
869 **
870 ** When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
871 ** If the option is unknown or SQLite is unable to set the option
872 ** then this routine returns a non-zero [error code].
873 **
874 ** Requirements:
875 ** [H14103] [H14106] [H14120] [H14123] [H14126] [H14129] [H14132] [H14135]
876 ** [H14138] [H14141] [H14144] [H14147] [H14150] [H14153] [H14156] [H14159]
877 ** [H14162] [H14165] [H14168]
878 */
879 SQLITE_EXPERIMENTAL int sqlite3_config(int, ...);
880
881 /*
882 ** CAPI3REF: Configure database connections  {H14200} <S20000>
883 ** EXPERIMENTAL
884 **
885 ** The sqlite3_db_config() interface is used to make configuration
886 ** changes to a [database connection].  The interface is similar to
887 ** [sqlite3_config()] except that the changes apply to a single
888 ** [database connection] (specified in the first argument).  The
889 ** sqlite3_db_config() interface can only be used immediately after
890 ** the database connection is created using [sqlite3_open()],
891 ** [sqlite3_open16()], or [sqlite3_open_v2()].  
892 **
893 ** The second argument to sqlite3_db_config(D,V,...)  is the
894 ** configuration verb - an integer code that indicates what
895 ** aspect of the [database connection] is being configured.
896 ** The only choice for this value is [SQLITE_DBCONFIG_LOOKASIDE].
897 ** New verbs are likely to be added in future releases of SQLite.
898 ** Additional arguments depend on the verb.
899 **
900 ** Requirements:
901 ** [H14203] [H14206] [H14209] [H14212] [H14215]
902 */
903 SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
904
905 /*
906 ** CAPI3REF: Memory Allocation Routines {H10155} <S20120>
907 ** EXPERIMENTAL
908 **
909 ** An instance of this object defines the interface between SQLite
910 ** and low-level memory allocation routines.
911 **
912 ** This object is used in only one place in the SQLite interface.
913 ** A pointer to an instance of this object is the argument to
914 ** [sqlite3_config()] when the configuration option is
915 ** [SQLITE_CONFIG_MALLOC].  By creating an instance of this object
916 ** and passing it to [sqlite3_config()] during configuration, an
917 ** application can specify an alternative memory allocation subsystem
918 ** for SQLite to use for all of its dynamic memory needs.
919 **
920 ** Note that SQLite comes with a built-in memory allocator that is
921 ** perfectly adequate for the overwhelming majority of applications
922 ** and that this object is only useful to a tiny minority of applications
923 ** with specialized memory allocation requirements.  This object is
924 ** also used during testing of SQLite in order to specify an alternative
925 ** memory allocator that simulates memory out-of-memory conditions in
926 ** order to verify that SQLite recovers gracefully from such
927 ** conditions.
928 **
929 ** The xMalloc, xFree, and xRealloc methods must work like the
930 ** malloc(), free(), and realloc() functions from the standard library.
931 **
932 ** xSize should return the allocated size of a memory allocation
933 ** previously obtained from xMalloc or xRealloc.  The allocated size
934 ** is always at least as big as the requested size but may be larger.
935 **
936 ** The xRoundup method returns what would be the allocated size of
937 ** a memory allocation given a particular requested size.  Most memory
938 ** allocators round up memory allocations at least to the next multiple
939 ** of 8.  Some allocators round up to a larger multiple or to a power of 2.
940 **
941 ** The xInit method initializes the memory allocator.  (For example,
942 ** it might allocate any require mutexes or initialize internal data
943 ** structures.  The xShutdown method is invoked (indirectly) by
944 ** [sqlite3_shutdown()] and should deallocate any resources acquired
945 ** by xInit.  The pAppData pointer is used as the only parameter to
946 ** xInit and xShutdown.
947 */
948 typedef struct sqlite3_mem_methods sqlite3_mem_methods;
949 struct sqlite3_mem_methods {
950   void *(*xMalloc)(int);         /* Memory allocation function */
951   void (*xFree)(void*);          /* Free a prior allocation */
952   void *(*xRealloc)(void*,int);  /* Resize an allocation */
953   int (*xSize)(void*);           /* Return the size of an allocation */
954   int (*xRoundup)(int);          /* Round up request size to allocation size */
955   int (*xInit)(void*);           /* Initialize the memory allocator */
956   void (*xShutdown)(void*);      /* Deinitialize the memory allocator */
957   void *pAppData;                /* Argument to xInit() and xShutdown() */
958 };
959
960 /*
961 ** CAPI3REF: Configuration Options {H10160} <S20000>
962 ** EXPERIMENTAL
963 **
964 ** These constants are the available integer configuration options that
965 ** can be passed as the first argument to the [sqlite3_config()] interface.
966 **
967 ** New configuration options may be added in future releases of SQLite.
968 ** Existing configuration options might be discontinued.  Applications
969 ** should check the return code from [sqlite3_config()] to make sure that
970 ** the call worked.  The [sqlite3_config()] interface will return a
971 ** non-zero [error code] if a discontinued or unsupported configuration option
972 ** is invoked.
973 **
974 ** <dl>
975 ** <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
976 ** <dd>There are no arguments to this option.  This option disables
977 ** all mutexing and puts SQLite into a mode where it can only be used
978 ** by a single thread.</dd>
979 **
980 ** <dt>SQLITE_CONFIG_MULTITHREAD</dt>
981 ** <dd>There are no arguments to this option.  This option disables
982 ** mutexing on [database connection] and [prepared statement] objects.
983 ** The application is responsible for serializing access to
984 ** [database connections] and [prepared statements].  But other mutexes
985 ** are enabled so that SQLite will be safe to use in a multi-threaded
986 ** environment as long as no two threads attempt to use the same
987 ** [database connection] at the same time.  See the [threading mode]
988 ** documentation for additional information.</dd>
989 **
990 ** <dt>SQLITE_CONFIG_SERIALIZED</dt>
991 ** <dd>There are no arguments to this option.  This option enables
992 ** all mutexes including the recursive
993 ** mutexes on [database connection] and [prepared statement] objects.
994 ** In this mode (which is the default when SQLite is compiled with
995 ** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
996 ** to [database connections] and [prepared statements] so that the
997 ** application is free to use the same [database connection] or the
998 ** same [prepared statement] in different threads at the same time.
999 ** See the [threading mode] documentation for additional information.</dd>
1000 **
1001 ** <dt>SQLITE_CONFIG_MALLOC</dt>
1002 ** <dd>This option takes a single argument which is a pointer to an
1003 ** instance of the [sqlite3_mem_methods] structure.  The argument specifies
1004 ** alternative low-level memory allocation routines to be used in place of
1005 ** the memory allocation routines built into SQLite.</dd>
1006 **
1007 ** <dt>SQLITE_CONFIG_GETMALLOC</dt>
1008 ** <dd>This option takes a single argument which is a pointer to an
1009 ** instance of the [sqlite3_mem_methods] structure.  The [sqlite3_mem_methods]
1010 ** structure is filled with the currently defined memory allocation routines.
1011 ** This option can be used to overload the default memory allocation
1012 ** routines with a wrapper that simulations memory allocation failure or
1013 ** tracks memory usage, for example.</dd>
1014 **
1015 ** <dt>SQLITE_CONFIG_MEMSTATUS</dt>
1016 ** <dd>This option takes single argument of type int, interpreted as a 
1017 ** boolean, which enables or disables the collection of memory allocation 
1018 ** statistics. When disabled, the following SQLite interfaces become 
1019 ** non-operational:
1020 **   <ul>
1021 **   <li> [sqlite3_memory_used()]
1022 **   <li> [sqlite3_memory_highwater()]
1023 **   <li> [sqlite3_soft_heap_limit()]
1024 **   <li> [sqlite3_status()]
1025 **   </ul>
1026 ** </dd>
1027 **
1028 ** <dt>SQLITE_CONFIG_SCRATCH</dt>
1029 ** <dd>This option specifies a static memory buffer that SQLite can use for
1030 ** scratch memory.  There are three arguments:  A pointer to the memory, the
1031 ** size of each scratch buffer (sz), and the number of buffers (N).  The sz
1032 ** argument must be a multiple of 16. The sz parameter should be a few bytes
1033 ** larger than the actual scratch space required due internal overhead.
1034 ** The first
1035 ** argument should point to an allocation of at least sz*N bytes of memory.
1036 ** SQLite will use no more than one scratch buffer at once per thread, so
1037 ** N should be set to the expected maximum number of threads.  The sz
1038 ** parameter should be 6 times the size of the largest database page size.
1039 ** Scratch buffers are used as part of the btree balance operation.  If
1040 ** The btree balancer needs additional memory beyond what is provided by
1041 ** scratch buffers or if no scratch buffer space is specified, then SQLite
1042 ** goes to [sqlite3_malloc()] to obtain the memory it needs.</dd>
1043 **
1044 ** <dt>SQLITE_CONFIG_PAGECACHE</dt>
1045 ** <dd>This option specifies a static memory buffer that SQLite can use for
1046 ** the database page cache with the default page cache implemenation.  
1047 ** This configuration should not be used if an application-define page
1048 ** cache implementation is loaded using the SQLITE_CONFIG_PCACHE option.
1049 ** There are three arguments to this option: A pointer to the
1050 ** memory, the size of each page buffer (sz), and the number of pages (N).
1051 ** The sz argument must be a power of two between 512 and 32768.  The first
1052 ** argument should point to an allocation of at least sz*N bytes of memory.
1053 ** SQLite will use the memory provided by the first argument to satisfy its
1054 ** memory needs for the first N pages that it adds to cache.  If additional
1055 ** page cache memory is needed beyond what is provided by this option, then
1056 ** SQLite goes to [sqlite3_malloc()] for the additional storage space.
1057 ** The implementation might use one or more of the N buffers to hold 
1058 ** memory accounting information. </dd>
1059 **
1060 ** <dt>SQLITE_CONFIG_HEAP</dt>
1061 ** <dd>This option specifies a static memory buffer that SQLite will use
1062 ** for all of its dynamic memory allocation needs beyond those provided
1063 ** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].
1064 ** There are three arguments: A pointer to the memory, the number of
1065 ** bytes in the memory buffer, and the minimum allocation size.  If
1066 ** the first pointer (the memory pointer) is NULL, then SQLite reverts
1067 ** to using its default memory allocator (the system malloc() implementation),
1068 ** undoing any prior invocation of [SQLITE_CONFIG_MALLOC].  If the
1069 ** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or
1070 ** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory
1071 ** allocator is engaged to handle all of SQLites memory allocation needs.</dd>
1072 **
1073 ** <dt>SQLITE_CONFIG_MUTEX</dt>
1074 ** <dd>This option takes a single argument which is a pointer to an
1075 ** instance of the [sqlite3_mutex_methods] structure.  The argument specifies
1076 ** alternative low-level mutex routines to be used in place
1077 ** the mutex routines built into SQLite.</dd>
1078 **
1079 ** <dt>SQLITE_CONFIG_GETMUTEX</dt>
1080 ** <dd>This option takes a single argument which is a pointer to an
1081 ** instance of the [sqlite3_mutex_methods] structure.  The
1082 ** [sqlite3_mutex_methods]
1083 ** structure is filled with the currently defined mutex routines.
1084 ** This option can be used to overload the default mutex allocation
1085 ** routines with a wrapper used to track mutex usage for performance
1086 ** profiling or testing, for example.</dd>
1087 **
1088 ** <dt>SQLITE_CONFIG_LOOKASIDE</dt>
1089 ** <dd>This option takes two arguments that determine the default
1090 ** memory allcation lookaside optimization.  The first argument is the
1091 ** size of each lookaside buffer slot and the second is the number of
1092 ** slots allocated to each database connection.</dd>
1093 **
1094 ** <dt>SQLITE_CONFIG_PCACHE</dt>
1095 ** <dd>This option takes a single argument which is a pointer to
1096 ** an [sqlite3_pcache_methods] object.  This object specifies the interface
1097 ** to a custom page cache implementation.  SQLite makes a copy of the
1098 ** object and uses it for page cache memory allocations.</dd>
1099 **
1100 ** <dt>SQLITE_CONFIG_GETPCACHE</dt>
1101 ** <dd>This option takes a single argument which is a pointer to an
1102 ** [sqlite3_pcache_methods] object.  SQLite copies of the current
1103 ** page cache implementation into that object.</dd>
1104 **
1105 ** </dl>
1106 */
1107 #define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
1108 #define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
1109 #define SQLITE_CONFIG_SERIALIZED    3  /* nil */
1110 #define SQLITE_CONFIG_MALLOC        4  /* sqlite3_mem_methods* */
1111 #define SQLITE_CONFIG_GETMALLOC     5  /* sqlite3_mem_methods* */
1112 #define SQLITE_CONFIG_SCRATCH       6  /* void*, int sz, int N */
1113 #define SQLITE_CONFIG_PAGECACHE     7  /* void*, int sz, int N */
1114 #define SQLITE_CONFIG_HEAP          8  /* void*, int nByte, int min */
1115 #define SQLITE_CONFIG_MEMSTATUS     9  /* boolean */
1116 #define SQLITE_CONFIG_MUTEX        10  /* sqlite3_mutex_methods* */
1117 #define SQLITE_CONFIG_GETMUTEX     11  /* sqlite3_mutex_methods* */
1118 /* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */ 
1119 #define SQLITE_CONFIG_LOOKASIDE    13  /* int int */
1120 #define SQLITE_CONFIG_PCACHE       14  /* sqlite3_pcache_methods* */
1121 #define SQLITE_CONFIG_GETPCACHE    15  /* sqlite3_pcache_methods* */
1122
1123 /*
1124 ** CAPI3REF: Configuration Options {H10170} <S20000>
1125 ** EXPERIMENTAL
1126 **
1127 ** These constants are the available integer configuration options that
1128 ** can be passed as the second argument to the [sqlite3_db_config()] interface.
1129 **
1130 ** New configuration options may be added in future releases of SQLite.
1131 ** Existing configuration options might be discontinued.  Applications
1132 ** should check the return code from [sqlite3_db_config()] to make sure that
1133 ** the call worked.  The [sqlite3_db_config()] interface will return a
1134 ** non-zero [error code] if a discontinued or unsupported configuration option
1135 ** is invoked.
1136 **
1137 ** <dl>
1138 ** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
1139 ** <dd>This option takes three additional arguments that determine the 
1140 ** [lookaside memory allocator] configuration for the [database connection].
1141 ** The first argument (the third parameter to [sqlite3_db_config()] is a
1142 ** pointer to a memory buffer to use for lookaside memory.  The first
1143 ** argument may be NULL in which case SQLite will allocate the lookaside
1144 ** buffer itself using [sqlite3_malloc()].  The second argument is the
1145 ** size of each lookaside buffer slot and the third argument is the number of
1146 ** slots.  The size of the buffer in the first argument must be greater than
1147 ** or equal to the product of the second and third arguments.</dd>
1148 **
1149 ** </dl>
1150 */
1151 #define SQLITE_DBCONFIG_LOOKASIDE    1001  /* void* int int */
1152
1153
1154 /*
1155 ** CAPI3REF: Enable Or Disable Extended Result Codes {H12200} <S10700>
1156 **
1157 ** The sqlite3_extended_result_codes() routine enables or disables the
1158 ** [extended result codes] feature of SQLite. The extended result
1159 ** codes are disabled by default for historical compatibility considerations.
1160 **
1161 ** Requirements:
1162 ** [H12201] [H12202]
1163 */
1164 int sqlite3_extended_result_codes(sqlite3*, int onoff);
1165
1166 /*
1167 ** CAPI3REF: Last Insert Rowid {H12220} <S10700>
1168 **
1169 ** Each entry in an SQLite table has a unique 64-bit signed
1170 ** integer key called the [ROWID | "rowid"]. The rowid is always available
1171 ** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
1172 ** names are not also used by explicitly declared columns. If
1173 ** the table has a column of type [INTEGER PRIMARY KEY] then that column
1174 ** is another alias for the rowid.
1175 **
1176 ** This routine returns the [rowid] of the most recent
1177 ** successful [INSERT] into the database from the [database connection]
1178 ** in the first argument.  If no successful [INSERT]s
1179 ** have ever occurred on that database connection, zero is returned.
1180 **
1181 ** If an [INSERT] occurs within a trigger, then the [rowid] of the inserted
1182 ** row is returned by this routine as long as the trigger is running.
1183 ** But once the trigger terminates, the value returned by this routine
1184 ** reverts to the last value inserted before the trigger fired.
1185 **
1186 ** An [INSERT] that fails due to a constraint violation is not a
1187 ** successful [INSERT] and does not change the value returned by this
1188 ** routine.  Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
1189 ** and INSERT OR ABORT make no changes to the return value of this
1190 ** routine when their insertion fails.  When INSERT OR REPLACE
1191 ** encounters a constraint violation, it does not fail.  The
1192 ** INSERT continues to completion after deleting rows that caused
1193 ** the constraint problem so INSERT OR REPLACE will always change
1194 ** the return value of this interface.
1195 **
1196 ** For the purposes of this routine, an [INSERT] is considered to
1197 ** be successful even if it is subsequently rolled back.
1198 **
1199 ** Requirements:
1200 ** [H12221] [H12223]
1201 **
1202 ** If a separate thread performs a new [INSERT] on the same
1203 ** database connection while the [sqlite3_last_insert_rowid()]
1204 ** function is running and thus changes the last insert [rowid],
1205 ** then the value returned by [sqlite3_last_insert_rowid()] is
1206 ** unpredictable and might not equal either the old or the new
1207 ** last insert [rowid].
1208 */
1209 sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
1210
1211 /*
1212 ** CAPI3REF: Count The Number Of Rows Modified {H12240} <S10600>
1213 **
1214 ** This function returns the number of database rows that were changed
1215 ** or inserted or deleted by the most recently completed SQL statement
1216 ** on the [database connection] specified by the first parameter.
1217 ** Only changes that are directly specified by the [INSERT], [UPDATE],
1218 ** or [DELETE] statement are counted.  Auxiliary changes caused by
1219 ** triggers are not counted. Use the [sqlite3_total_changes()] function
1220 ** to find the total number of changes including changes caused by triggers.
1221 **
1222 ** A "row change" is a change to a single row of a single table
1223 ** caused by an INSERT, DELETE, or UPDATE statement.  Rows that
1224 ** are changed as side effects of REPLACE constraint resolution,
1225 ** rollback, ABORT processing, DROP TABLE, or by any other
1226 ** mechanisms do not count as direct row changes.
1227 **
1228 ** A "trigger context" is a scope of execution that begins and
1229 ** ends with the script of a trigger.  Most SQL statements are
1230 ** evaluated outside of any trigger.  This is the "top level"
1231 ** trigger context.  If a trigger fires from the top level, a
1232 ** new trigger context is entered for the duration of that one
1233 ** trigger.  Subtriggers create subcontexts for their duration.
1234 **
1235 ** Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
1236 ** not create a new trigger context.
1237 **
1238 ** This function returns the number of direct row changes in the
1239 ** most recent INSERT, UPDATE, or DELETE statement within the same
1240 ** trigger context.
1241 **
1242 ** Thus, when called from the top level, this function returns the
1243 ** number of changes in the most recent INSERT, UPDATE, or DELETE
1244 ** that also occurred at the top level.  Within the body of a trigger,
1245 ** the sqlite3_changes() interface can be called to find the number of
1246 ** changes in the most recently completed INSERT, UPDATE, or DELETE
1247 ** statement within the body of the same trigger.
1248 ** However, the number returned does not include changes
1249 ** caused by subtriggers since those have their own context.
1250 **
1251 ** SQLite implements the command "DELETE FROM table" without a WHERE clause
1252 ** by dropping and recreating the table.  Doing so is much faster than going
1253 ** through and deleting individual elements from the table.  Because of this
1254 ** optimization, the deletions in "DELETE FROM table" are not row changes and
1255 ** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()]
1256 ** functions, regardless of the number of elements that were originally
1257 ** in the table.  To get an accurate count of the number of rows deleted, use
1258 ** "DELETE FROM table WHERE 1" instead.  Or recompile using the
1259 ** [SQLITE_OMIT_TRUNCATE_OPTIMIZATION] compile-time option to disable the
1260 ** optimization on all queries.
1261 **
1262 ** Requirements:
1263 ** [H12241] [H12243]
1264 **
1265 ** If a separate thread makes changes on the same database connection
1266 ** while [sqlite3_changes()] is running then the value returned
1267 ** is unpredictable and not meaningful.
1268 */
1269 int sqlite3_changes(sqlite3*);
1270
1271 /*
1272 ** CAPI3REF: Total Number Of Rows Modified {H12260} <S10600>
1273 **
1274 ** This function returns the number of row changes caused by INSERT,
1275 ** UPDATE or DELETE statements since the [database connection] was opened.
1276 ** The count includes all changes from all trigger contexts.  However,
1277 ** the count does not include changes used to implement REPLACE constraints,
1278 ** do rollbacks or ABORT processing, or DROP table processing.
1279 ** The changes are counted as soon as the statement that makes them is
1280 ** completed (when the statement handle is passed to [sqlite3_reset()] or
1281 ** [sqlite3_finalize()]).
1282 **
1283 ** SQLite implements the command "DELETE FROM table" without a WHERE clause
1284 ** by dropping and recreating the table.  (This is much faster than going
1285 ** through and deleting individual elements from the table.)  Because of this
1286 ** optimization, the deletions in "DELETE FROM table" are not row changes and
1287 ** will not be counted by the sqlite3_changes() or [sqlite3_total_changes()]
1288 ** functions, regardless of the number of elements that were originally
1289 ** in the table.  To get an accurate count of the number of rows deleted, use
1290 ** "DELETE FROM table WHERE 1" instead.   Or recompile using the
1291 ** [SQLITE_OMIT_TRUNCATE_OPTIMIZATION] compile-time option to disable the
1292 ** optimization on all queries.
1293 **
1294 ** See also the [sqlite3_changes()] interface.
1295 **
1296 ** Requirements:
1297 ** [H12261] [H12263]
1298 **
1299 ** If a separate thread makes changes on the same database connection
1300 ** while [sqlite3_total_changes()] is running then the value
1301 ** returned is unpredictable and not meaningful.
1302 */
1303 int sqlite3_total_changes(sqlite3*);
1304
1305 /*
1306 ** CAPI3REF: Interrupt A Long-Running Query {H12270} <S30500>
1307 **
1308 ** This function causes any pending database operation to abort and
1309 ** return at its earliest opportunity. This routine is typically
1310 ** called in response to a user action such as pressing "Cancel"
1311 ** or Ctrl-C where the user wants a long query operation to halt
1312 ** immediately.
1313 **
1314 ** It is safe to call this routine from a thread different from the
1315 ** thread that is currently running the database operation.  But it
1316 ** is not safe to call this routine with a [database connection] that
1317 ** is closed or might close before sqlite3_interrupt() returns.
1318 **
1319 ** If an SQL operation is very nearly finished at the time when
1320 ** sqlite3_interrupt() is called, then it might not have an opportunity
1321 ** to be interrupted and might continue to completion.
1322 **
1323 ** An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
1324 ** If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
1325 ** that is inside an explicit transaction, then the entire transaction
1326 ** will be rolled back automatically.
1327 **
1328 ** A call to sqlite3_interrupt() has no effect on SQL statements
1329 ** that are started after sqlite3_interrupt() returns.
1330 **
1331 ** Requirements:
1332 ** [H12271] [H12272]
1333 **
1334 ** If the database connection closes while [sqlite3_interrupt()]
1335 ** is running then bad things will likely happen.
1336 */
1337 void sqlite3_interrupt(sqlite3*);
1338
1339 /*
1340 ** CAPI3REF: Determine If An SQL Statement Is Complete {H10510} <S70200>
1341 **
1342 ** These routines are useful for command-line input to determine if the
1343 ** currently entered text seems to form complete a SQL statement or
1344 ** if additional input is needed before sending the text into
1345 ** SQLite for parsing.  These routines return true if the input string
1346 ** appears to be a complete SQL statement.  A statement is judged to be
1347 ** complete if it ends with a semicolon token and is not a fragment of a
1348 ** CREATE TRIGGER statement.  Semicolons that are embedded within
1349 ** string literals or quoted identifier names or comments are not
1350 ** independent tokens (they are part of the token in which they are
1351 ** embedded) and thus do not count as a statement terminator.
1352 **
1353 ** These routines do not parse the SQL statements thus
1354 ** will not detect syntactically incorrect SQL.
1355 **
1356 ** Requirements: [H10511] [H10512]
1357 **
1358 ** The input to [sqlite3_complete()] must be a zero-terminated
1359 ** UTF-8 string.
1360 **
1361 ** The input to [sqlite3_complete16()] must be a zero-terminated
1362 ** UTF-16 string in native byte order.
1363 */
1364 int sqlite3_complete(const char *sql);
1365 int sqlite3_complete16(const void *sql);
1366
1367 /*
1368 ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors {H12310} <S40400>
1369 **
1370 ** This routine sets a callback function that might be invoked whenever
1371 ** an attempt is made to open a database table that another thread
1372 ** or process has locked.
1373 **
1374 ** If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]
1375 ** is returned immediately upon encountering the lock. If the busy callback
1376 ** is not NULL, then the callback will be invoked with two arguments.
1377 **
1378 ** The first argument to the handler is a copy of the void* pointer which
1379 ** is the third argument to sqlite3_busy_handler().  The second argument to
1380 ** the handler callback is the number of times that the busy handler has
1381 ** been invoked for this locking event.  If the
1382 ** busy callback returns 0, then no additional attempts are made to
1383 ** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
1384 ** If the callback returns non-zero, then another attempt
1385 ** is made to open the database for reading and the cycle repeats.
1386 **
1387 ** The presence of a busy handler does not guarantee that it will be invoked
1388 ** when there is lock contention. If SQLite determines that invoking the busy
1389 ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
1390 ** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler.
1391 ** Consider a scenario where one process is holding a read lock that
1392 ** it is trying to promote to a reserved lock and
1393 ** a second process is holding a reserved lock that it is trying
1394 ** to promote to an exclusive lock.  The first process cannot proceed
1395 ** because it is blocked by the second and the second process cannot
1396 ** proceed because it is blocked by the first.  If both processes
1397 ** invoke the busy handlers, neither will make any progress.  Therefore,
1398 ** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
1399 ** will induce the first process to release its read lock and allow
1400 ** the second process to proceed.
1401 **
1402 ** The default busy callback is NULL.
1403 **
1404 ** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
1405 ** when SQLite is in the middle of a large transaction where all the
1406 ** changes will not fit into the in-memory cache.  SQLite will
1407 ** already hold a RESERVED lock on the database file, but it needs
1408 ** to promote this lock to EXCLUSIVE so that it can spill cache
1409 ** pages into the database file without harm to concurrent
1410 ** readers.  If it is unable to promote the lock, then the in-memory
1411 ** cache will be left in an inconsistent state and so the error
1412 ** code is promoted from the relatively benign [SQLITE_BUSY] to
1413 ** the more severe [SQLITE_IOERR_BLOCKED].  This error code promotion
1414 ** forces an automatic rollback of the changes.  See the
1415 ** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError">
1416 ** CorruptionFollowingBusyError</a> wiki page for a discussion of why
1417 ** this is important.
1418 **
1419 ** There can only be a single busy handler defined for each
1420 ** [database connection].  Setting a new busy handler clears any
1421 ** previously set handler.  Note that calling [sqlite3_busy_timeout()]
1422 ** will also set or clear the busy handler.
1423 **
1424 ** The busy callback should not take any actions which modify the
1425 ** database connection that invoked the busy handler.  Any such actions
1426 ** result in undefined behavior.
1427 ** 
1428 ** Requirements:
1429 ** [H12311] [H12312] [H12314] [H12316] [H12318]
1430 **
1431 ** A busy handler must not close the database connection
1432 ** or [prepared statement] that invoked the busy handler.
1433 */
1434 int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
1435
1436 /*
1437 ** CAPI3REF: Set A Busy Timeout {H12340} <S40410>
1438 **
1439 ** This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
1440 ** for a specified amount of time when a table is locked.  The handler
1441 ** will sleep multiple times until at least "ms" milliseconds of sleeping
1442 ** have accumulated. {H12343} After "ms" milliseconds of sleeping,
1443 ** the handler returns 0 which causes [sqlite3_step()] to return
1444 ** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
1445 **
1446 ** Calling this routine with an argument less than or equal to zero
1447 ** turns off all busy handlers.
1448 **
1449 ** There can only be a single busy handler for a particular
1450 ** [database connection] any any given moment.  If another busy handler
1451 ** was defined  (using [sqlite3_busy_handler()]) prior to calling
1452 ** this routine, that other busy handler is cleared.
1453 **
1454 ** Requirements:
1455 ** [H12341] [H12343] [H12344]
1456 */
1457 int sqlite3_busy_timeout(sqlite3*, int ms);
1458
1459 /*
1460 ** CAPI3REF: Convenience Routines For Running Queries {H12370} <S10000>
1461 **
1462 ** Definition: A <b>result table</b> is memory data structure created by the
1463 ** [sqlite3_get_table()] interface.  A result table records the
1464 ** complete query results from one or more queries.
1465 **
1466 ** The table conceptually has a number of rows and columns.  But
1467 ** these numbers are not part of the result table itself.  These
1468 ** numbers are obtained separately.  Let N be the number of rows
1469 ** and M be the number of columns.
1470 **
1471 ** A result table is an array of pointers to zero-terminated UTF-8 strings.
1472 ** There are (N+1)*M elements in the array.  The first M pointers point
1473 ** to zero-terminated strings that  contain the names of the columns.
1474 ** The remaining entries all point to query results.  NULL values result
1475 ** in NULL pointers.  All other values are in their UTF-8 zero-terminated
1476 ** string representation as returned by [sqlite3_column_text()].
1477 **
1478 ** A result table might consist of one or more memory allocations.
1479 ** It is not safe to pass a result table directly to [sqlite3_free()].
1480 ** A result table should be deallocated using [sqlite3_free_table()].
1481 **
1482 ** As an example of the result table format, suppose a query result
1483 ** is as follows:
1484 **
1485 ** <blockquote><pre>
1486 **        Name        | Age
1487 **        -----------------------
1488 **        Alice       | 43
1489 **        Bob         | 28
1490 **        Cindy       | 21
1491 ** </pre></blockquote>
1492 **
1493 ** There are two column (M==2) and three rows (N==3).  Thus the
1494 ** result table has 8 entries.  Suppose the result table is stored
1495 ** in an array names azResult.  Then azResult holds this content:
1496 **
1497 ** <blockquote><pre>
1498 **        azResult&#91;0] = "Name";
1499 **        azResult&#91;1] = "Age";
1500 **        azResult&#91;2] = "Alice";
1501 **        azResult&#91;3] = "43";
1502 **        azResult&#91;4] = "Bob";
1503 **        azResult&#91;5] = "28";
1504 **        azResult&#91;6] = "Cindy";
1505 **        azResult&#91;7] = "21";
1506 ** </pre></blockquote>
1507 **
1508 ** The sqlite3_get_table() function evaluates one or more
1509 ** semicolon-separated SQL statements in the zero-terminated UTF-8
1510 ** string of its 2nd parameter.  It returns a result table to the
1511 ** pointer given in its 3rd parameter.
1512 **
1513 ** After the calling function has finished using the result, it should
1514 ** pass the pointer to the result table to sqlite3_free_table() in order to
1515 ** release the memory that was malloced.  Because of the way the
1516 ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
1517 ** function must not try to call [sqlite3_free()] directly.  Only
1518 ** [sqlite3_free_table()] is able to release the memory properly and safely.
1519 **
1520 ** The sqlite3_get_table() interface is implemented as a wrapper around
1521 ** [sqlite3_exec()].  The sqlite3_get_table() routine does not have access
1522 ** to any internal data structures of SQLite.  It uses only the public
1523 ** interface defined here.  As a consequence, errors that occur in the
1524 ** wrapper layer outside of the internal [sqlite3_exec()] call are not
1525 ** reflected in subsequent calls to [sqlite3_errcode()] or [sqlite3_errmsg()].
1526 **
1527 ** Requirements:
1528 ** [H12371] [H12373] [H12374] [H12376] [H12379] [H12382]
1529 */
1530 int sqlite3_get_table(
1531   sqlite3 *db,          /* An open database */
1532   const char *zSql,     /* SQL to be evaluated */
1533   char ***pazResult,    /* Results of the query */
1534   int *pnRow,           /* Number of result rows written here */
1535   int *pnColumn,        /* Number of result columns written here */
1536   char **pzErrmsg       /* Error msg written here */
1537 );
1538 void sqlite3_free_table(char **result);
1539
1540 /*
1541 ** CAPI3REF: Formatted String Printing Functions {H17400} <S70000><S20000>
1542 **
1543 ** These routines are workalikes of the "printf()" family of functions
1544 ** from the standard C library.
1545 **
1546 ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
1547 ** results into memory obtained from [sqlite3_malloc()].
1548 ** The strings returned by these two routines should be
1549 ** released by [sqlite3_free()].  Both routines return a
1550 ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
1551 ** memory to hold the resulting string.
1552 **
1553 ** In sqlite3_snprintf() routine is similar to "snprintf()" from
1554 ** the standard C library.  The result is written into the
1555 ** buffer supplied as the second parameter whose size is given by
1556 ** the first parameter. Note that the order of the
1557 ** first two parameters is reversed from snprintf().  This is an
1558 ** historical accident that cannot be fixed without breaking
1559 ** backwards compatibility.  Note also that sqlite3_snprintf()
1560 ** returns a pointer to its buffer instead of the number of
1561 ** characters actually written into the buffer.  We admit that
1562 ** the number of characters written would be a more useful return
1563 ** value but we cannot change the implementation of sqlite3_snprintf()
1564 ** now without breaking compatibility.
1565 **
1566 ** As long as the buffer size is greater than zero, sqlite3_snprintf()
1567 ** guarantees that the buffer is always zero-terminated.  The first
1568 ** parameter "n" is the total size of the buffer, including space for
1569 ** the zero terminator.  So the longest string that can be completely
1570 ** written will be n-1 characters.
1571 **
1572 ** These routines all implement some additional formatting
1573 ** options that are useful for constructing SQL statements.
1574 ** All of the usual printf() formatting options apply.  In addition, there
1575 ** is are "%q", "%Q", and "%z" options.
1576 **
1577 ** The %q option works like %s in that it substitutes a null-terminated
1578 ** string from the argument list.  But %q also doubles every '\'' character.
1579 ** %q is designed for use inside a string literal.  By doubling each '\''
1580 ** character it escapes that character and allows it to be inserted into
1581 ** the string.
1582 **
1583 ** For example, assume the string variable zText contains text as follows:
1584 **
1585 ** <blockquote><pre>
1586 **  char *zText = "It's a happy day!";
1587 ** </pre></blockquote>
1588 **
1589 ** One can use this text in an SQL statement as follows:
1590 **
1591 ** <blockquote><pre>
1592 **  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
1593 **  sqlite3_exec(db, zSQL, 0, 0, 0);
1594 **  sqlite3_free(zSQL);
1595 ** </pre></blockquote>
1596 **
1597 ** Because the %q format string is used, the '\'' character in zText
1598 ** is escaped and the SQL generated is as follows:
1599 **
1600 ** <blockquote><pre>
1601 **  INSERT INTO table1 VALUES('It''s a happy day!')
1602 ** </pre></blockquote>
1603 **
1604 ** This is correct.  Had we used %s instead of %q, the generated SQL
1605 ** would have looked like this:
1606 **
1607 ** <blockquote><pre>
1608 **  INSERT INTO table1 VALUES('It's a happy day!');
1609 ** </pre></blockquote>
1610 **
1611 ** This second example is an SQL syntax error.  As a general rule you should
1612 ** always use %q instead of %s when inserting text into a string literal.
1613 **
1614 ** The %Q option works like %q except it also adds single quotes around
1615 ** the outside of the total string.  Additionally, if the parameter in the
1616 ** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
1617 ** single quotes) in place of the %Q option.  So, for example, one could say:
1618 **
1619 ** <blockquote><pre>
1620 **  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
1621 **  sqlite3_exec(db, zSQL, 0, 0, 0);
1622 **  sqlite3_free(zSQL);
1623 ** </pre></blockquote>
1624 **
1625 ** The code above will render a correct SQL statement in the zSQL
1626 ** variable even if the zText variable is a NULL pointer.
1627 **
1628 ** The "%z" formatting option works exactly like "%s" with the
1629 ** addition that after the string has been read and copied into
1630 ** the result, [sqlite3_free()] is called on the input string. {END}
1631 **
1632 ** Requirements:
1633 ** [H17403] [H17406] [H17407]
1634 */
1635 char *sqlite3_mprintf(const char*,...);
1636 char *sqlite3_vmprintf(const char*, va_list);
1637 char *sqlite3_snprintf(int,char*,const char*, ...);
1638
1639 /*
1640 ** CAPI3REF: Memory Allocation Subsystem {H17300} <S20000>
1641 **
1642 ** The SQLite core  uses these three routines for all of its own
1643 ** internal memory allocation needs. "Core" in the previous sentence
1644 ** does not include operating-system specific VFS implementation.  The
1645 ** Windows VFS uses native malloc() and free() for some operations.
1646 **
1647 ** The sqlite3_malloc() routine returns a pointer to a block
1648 ** of memory at least N bytes in length, where N is the parameter.
1649 ** If sqlite3_malloc() is unable to obtain sufficient free
1650 ** memory, it returns a NULL pointer.  If the parameter N to
1651 ** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
1652 ** a NULL pointer.
1653 **
1654 ** Calling sqlite3_free() with a pointer previously returned
1655 ** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
1656 ** that it might be reused.  The sqlite3_free() routine is
1657 ** a no-op if is called with a NULL pointer.  Passing a NULL pointer
1658 ** to sqlite3_free() is harmless.  After being freed, memory
1659 ** should neither be read nor written.  Even reading previously freed
1660 ** memory might result in a segmentation fault or other severe error.
1661 ** Memory corruption, a segmentation fault, or other severe error
1662 ** might result if sqlite3_free() is called with a non-NULL pointer that
1663 ** was not obtained from sqlite3_malloc() or sqlite3_realloc().
1664 **
1665 ** The sqlite3_realloc() interface attempts to resize a
1666 ** prior memory allocation to be at least N bytes, where N is the
1667 ** second parameter.  The memory allocation to be resized is the first
1668 ** parameter.  If the first parameter to sqlite3_realloc()
1669 ** is a NULL pointer then its behavior is identical to calling
1670 ** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().
1671 ** If the second parameter to sqlite3_realloc() is zero or
1672 ** negative then the behavior is exactly the same as calling
1673 ** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
1674 ** sqlite3_realloc() returns a pointer to a memory allocation
1675 ** of at least N bytes in size or NULL if sufficient memory is unavailable.
1676 ** If M is the size of the prior allocation, then min(N,M) bytes
1677 ** of the prior allocation are copied into the beginning of buffer returned
1678 ** by sqlite3_realloc() and the prior allocation is freed.
1679 ** If sqlite3_realloc() returns NULL, then the prior allocation
1680 ** is not freed.
1681 **
1682 ** The memory returned by sqlite3_malloc() and sqlite3_realloc()
1683 ** is always aligned to at least an 8 byte boundary. {END}
1684 **
1685 ** The default implementation of the memory allocation subsystem uses
1686 ** the malloc(), realloc() and free() provided by the standard C library.
1687 ** {H17382} However, if SQLite is compiled with the
1688 ** SQLITE_MEMORY_SIZE=<i>NNN</i> C preprocessor macro (where <i>NNN</i>
1689 ** is an integer), then SQLite create a static array of at least
1690 ** <i>NNN</i> bytes in size and uses that array for all of its dynamic
1691 ** memory allocation needs. {END}  Additional memory allocator options
1692 ** may be added in future releases.
1693 **
1694 ** In SQLite version 3.5.0 and 3.5.1, it was possible to define
1695 ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
1696 ** implementation of these routines to be omitted.  That capability
1697 ** is no longer provided.  Only built-in memory allocators can be used.
1698 **
1699 ** The Windows OS interface layer calls
1700 ** the system malloc() and free() directly when converting
1701 ** filenames between the UTF-8 encoding used by SQLite
1702 ** and whatever filename encoding is used by the particular Windows
1703 ** installation.  Memory allocation errors are detected, but
1704 ** they are reported back as [SQLITE_CANTOPEN] or
1705 ** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
1706 **
1707 ** Requirements:
1708 ** [H17303] [H17304] [H17305] [H17306] [H17310] [H17312] [H17315] [H17318]
1709 ** [H17321] [H17322] [H17323]
1710 **
1711 ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
1712 ** must be either NULL or else pointers obtained from a prior
1713 ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
1714 ** not yet been released.
1715 **
1716 ** The application must not read or write any part of
1717 ** a block of memory after it has been released using
1718 ** [sqlite3_free()] or [sqlite3_realloc()].
1719 */
1720 void *sqlite3_malloc(int);
1721 void *sqlite3_realloc(void*, int);
1722 void sqlite3_free(void*);
1723
1724 /*
1725 ** CAPI3REF: Memory Allocator Statistics {H17370} <S30210>
1726 **
1727 ** SQLite provides these two interfaces for reporting on the status
1728 ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
1729 ** routines, which form the built-in memory allocation subsystem.
1730 **
1731 ** Requirements:
1732 ** [H17371] [H17373] [H17374] [H17375]
1733 */
1734 sqlite3_int64 sqlite3_memory_used(void);
1735 sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
1736
1737 /*
1738 ** CAPI3REF: Pseudo-Random Number Generator {H17390} <S20000>
1739 **
1740 ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
1741 ** select random [ROWID | ROWIDs] when inserting new records into a table that
1742 ** already uses the largest possible [ROWID].  The PRNG is also used for
1743 ** the build-in random() and randomblob() SQL functions.  This interface allows
1744 ** applications to access the same PRNG for other purposes.
1745 **
1746 ** A call to this routine stores N bytes of randomness into buffer P.
1747 **
1748 ** The first time this routine is invoked (either internally or by
1749 ** the application) the PRNG is seeded using randomness obtained
1750 ** from the xRandomness method of the default [sqlite3_vfs] object.
1751 ** On all subsequent invocations, the pseudo-randomness is generated
1752 ** internally and without recourse to the [sqlite3_vfs] xRandomness
1753 ** method.
1754 **
1755 ** Requirements:
1756 ** [H17392]
1757 */
1758 void sqlite3_randomness(int N, void *P);
1759
1760 /*
1761 ** CAPI3REF: Compile-Time Authorization Callbacks {H12500} <S70100>
1762 **
1763 ** This routine registers a authorizer callback with a particular
1764 ** [database connection], supplied in the first argument.
1765 ** The authorizer callback is invoked as SQL statements are being compiled
1766 ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
1767 ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()].  At various
1768 ** points during the compilation process, as logic is being created
1769 ** to perform various actions, the authorizer callback is invoked to
1770 ** see if those actions are allowed.  The authorizer callback should
1771 ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
1772 ** specific action but allow the SQL statement to continue to be
1773 ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
1774 ** rejected with an error.  If the authorizer callback returns
1775 ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
1776 ** then the [sqlite3_prepare_v2()] or equivalent call that triggered
1777 ** the authorizer will fail with an error message.
1778 **
1779 ** When the callback returns [SQLITE_OK], that means the operation
1780 ** requested is ok.  When the callback returns [SQLITE_DENY], the
1781 ** [sqlite3_prepare_v2()] or equivalent call that triggered the
1782 ** authorizer will fail with an error message explaining that
1783 ** access is denied.  If the authorizer code is [SQLITE_READ]
1784 ** and the callback returns [SQLITE_IGNORE] then the
1785 ** [prepared statement] statement is constructed to substitute
1786 ** a NULL value in place of the table column that would have
1787 ** been read if [SQLITE_OK] had been returned.  The [SQLITE_IGNORE]
1788 ** return can be used to deny an untrusted user access to individual
1789 ** columns of a table.
1790 **
1791 ** The first parameter to the authorizer callback is a copy of the third
1792 ** parameter to the sqlite3_set_authorizer() interface. The second parameter
1793 ** to the callback is an integer [SQLITE_COPY | action code] that specifies
1794 ** the particular action to be authorized. The third through sixth parameters
1795 ** to the callback are zero-terminated strings that contain additional
1796 ** details about the action to be authorized.
1797 **
1798 ** An authorizer is used when [sqlite3_prepare | preparing]
1799 ** SQL statements from an untrusted source, to ensure that the SQL statements
1800 ** do not try to access data they are not allowed to see, or that they do not
1801 ** try to execute malicious statements that damage the database.  For
1802 ** example, an application may allow a user to enter arbitrary
1803 ** SQL queries for evaluation by a database.  But the application does
1804 ** not want the user to be able to make arbitrary changes to the
1805 ** database.  An authorizer could then be put in place while the
1806 ** user-entered SQL is being [sqlite3_prepare | prepared] that
1807 ** disallows everything except [SELECT] statements.
1808 **
1809 ** Applications that need to process SQL from untrusted sources
1810 ** might also consider lowering resource limits using [sqlite3_limit()]
1811 ** and limiting database size using the [max_page_count] [PRAGMA]
1812 ** in addition to using an authorizer.
1813 **
1814 ** Only a single authorizer can be in place on a database connection
1815 ** at a time.  Each call to sqlite3_set_authorizer overrides the
1816 ** previous call.  Disable the authorizer by installing a NULL callback.
1817 ** The authorizer is disabled by default.
1818 **
1819 ** The authorizer callback must not do anything that will modify
1820 ** the database connection that invoked the authorizer callback.
1821 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
1822 ** database connections for the meaning of "modify" in this paragraph.
1823 **
1824 ** When [sqlite3_prepare_v2()] is used to prepare a statement, the
1825 ** statement might be reprepared during [sqlite3_step()] due to a 
1826 ** schema change.  Hence, the application should ensure that the
1827 ** correct authorizer callback remains in place during the [sqlite3_step()].
1828 **
1829 ** Note that the authorizer callback is invoked only during
1830 ** [sqlite3_prepare()] or its variants.  Authorization is not
1831 ** performed during statement evaluation in [sqlite3_step()].
1832 **
1833 ** Requirements:
1834 ** [H12501] [H12502] [H12503] [H12504] [H12505] [H12506] [H12507] [H12510]
1835 ** [H12511] [H12512] [H12520] [H12521] [H12522]
1836 */
1837 int sqlite3_set_authorizer(
1838   sqlite3*,
1839   int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
1840   void *pUserData
1841 );
1842
1843 /*
1844 ** CAPI3REF: Authorizer Return Codes {H12590} <H12500>
1845 **
1846 ** The [sqlite3_set_authorizer | authorizer callback function] must
1847 ** return either [SQLITE_OK] or one of these two constants in order
1848 ** to signal SQLite whether or not the action is permitted.  See the
1849 ** [sqlite3_set_authorizer | authorizer documentation] for additional
1850 ** information.
1851 */
1852 #define SQLITE_DENY   1   /* Abort the SQL statement with an error */
1853 #define SQLITE_IGNORE 2   /* Don't allow access, but don't generate an error */
1854
1855 /*
1856 ** CAPI3REF: Authorizer Action Codes {H12550} <H12500>
1857 **
1858 ** The [sqlite3_set_authorizer()] interface registers a callback function
1859 ** that is invoked to authorize certain SQL statement actions.  The
1860 ** second parameter to the callback is an integer code that specifies
1861 ** what action is being authorized.  These are the integer action codes that
1862 ** the authorizer callback may be passed.
1863 **
1864 ** These action code values signify what kind of operation is to be
1865 ** authorized.  The 3rd and 4th parameters to the authorization
1866 ** callback function will be parameters or NULL depending on which of these
1867 ** codes is used as the second parameter.  The 5th parameter to the
1868 ** authorizer callback is the name of the database ("main", "temp",
1869 ** etc.) if applicable.  The 6th parameter to the authorizer callback
1870 ** is the name of the inner-most trigger or view that is responsible for
1871 ** the access attempt or NULL if this access attempt is directly from
1872 ** top-level SQL code.
1873 **
1874 ** Requirements:
1875 ** [H12551] [H12552] [H12553] [H12554]
1876 */
1877 /******************************************* 3rd ************ 4th ***********/
1878 #define SQLITE_CREATE_INDEX          1   /* Index Name      Table Name      */
1879 #define SQLITE_CREATE_TABLE          2   /* Table Name      NULL            */
1880 #define SQLITE_CREATE_TEMP_INDEX     3   /* Index Name      Table Name      */
1881 #define SQLITE_CREATE_TEMP_TABLE     4   /* Table Name      NULL            */
1882 #define SQLITE_CREATE_TEMP_TRIGGER   5   /* Trigger Name    Table Name      */
1883 #define SQLITE_CREATE_TEMP_VIEW      6   /* View Name       NULL            */
1884 #define SQLITE_CREATE_TRIGGER        7   /* Trigger Name    Table Name      */
1885 #define SQLITE_CREATE_VIEW           8   /* View Name       NULL            */
1886 #define SQLITE_DELETE                9   /* Table Name      NULL            */
1887 #define SQLITE_DROP_INDEX           10   /* Index Name      Table Name      */
1888 #define SQLITE_DROP_TABLE           11   /* Table Name      NULL            */
1889 #define SQLITE_DROP_TEMP_INDEX      12   /* Index Name      Table Name      */
1890 #define SQLITE_DROP_TEMP_TABLE      13   /* Table Name      NULL            */
1891 #define SQLITE_DROP_TEMP_TRIGGER    14   /* Trigger Name    Table Name      */
1892 #define SQLITE_DROP_TEMP_VIEW       15   /* View Name       NULL            */
1893 #define SQLITE_DROP_TRIGGER         16   /* Trigger Name    Table Name      */
1894 #define SQLITE_DROP_VIEW            17   /* View Name       NULL            */
1895 #define SQLITE_INSERT               18   /* Table Name      NULL            */
1896 #define SQLITE_PRAGMA               19   /* Pragma Name     1st arg or NULL */
1897 #define SQLITE_READ                 20   /* Table Name      Column Name     */
1898 #define SQLITE_SELECT               21   /* NULL            NULL            */
1899 #define SQLITE_TRANSACTION          22   /* Operation       NULL            */
1900 #define SQLITE_UPDATE               23   /* Table Name      Column Name     */
1901 #define SQLITE_ATTACH               24   /* Filename        NULL            */
1902 #define SQLITE_DETACH               25   /* Database Name   NULL            */
1903 #define SQLITE_ALTER_TABLE          26   /* Database Name   Table Name      */
1904 #define SQLITE_REINDEX              27   /* Index Name      NULL            */
1905 #define SQLITE_ANALYZE              28   /* Table Name      NULL            */
1906 #define SQLITE_CREATE_VTABLE        29   /* Table Name      Module Name     */
1907 #define SQLITE_DROP_VTABLE          30   /* Table Name      Module Name     */
1908 #define SQLITE_FUNCTION             31   /* NULL            Function Name   */
1909 #define SQLITE_SAVEPOINT            32   /* Operation       Savepoint Name  */
1910 #define SQLITE_COPY                  0   /* No longer used */
1911
1912 /*
1913 ** CAPI3REF: Tracing And Profiling Functions {H12280} <S60400>
1914 ** EXPERIMENTAL
1915 **
1916 ** These routines register callback functions that can be used for
1917 ** tracing and profiling the execution of SQL statements.
1918 **
1919 ** The callback function registered by sqlite3_trace() is invoked at
1920 ** various times when an SQL statement is being run by [sqlite3_step()].
1921 ** The callback returns a UTF-8 rendering of the SQL statement text
1922 ** as the statement first begins executing.  Additional callbacks occur
1923 ** as each triggered subprogram is entered.  The callbacks for triggers
1924 ** contain a UTF-8 SQL comment that identifies the trigger.
1925 **
1926 ** The callback function registered by sqlite3_profile() is invoked
1927 ** as each SQL statement finishes.  The profile callback contains
1928 ** the original statement text and an estimate of wall-clock time
1929 ** of how long that statement took to run.
1930 **
1931 ** Requirements:
1932 ** [H12281] [H12282] [H12283] [H12284] [H12285] [H12287] [H12288] [H12289]
1933 ** [H12290]
1934 */
1935 SQLITE_EXPERIMENTAL void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
1936 SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
1937    void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
1938
1939 /*
1940 ** CAPI3REF: Query Progress Callbacks {H12910} <S60400>
1941 **
1942 ** This routine configures a callback function - the
1943 ** progress callback - that is invoked periodically during long
1944 ** running calls to [sqlite3_exec()], [sqlite3_step()] and
1945 ** [sqlite3_get_table()].  An example use for this
1946 ** interface is to keep a GUI updated during a large query.
1947 **
1948 ** If the progress callback returns non-zero, the operation is
1949 ** interrupted.  This feature can be used to implement a
1950 ** "Cancel" button on a GUI progress dialog box.
1951 **
1952 ** The progress handler must not do anything that will modify
1953 ** the database connection that invoked the progress handler.
1954 ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
1955 ** database connections for the meaning of "modify" in this paragraph.
1956 **
1957 ** Requirements:
1958 ** [H12911] [H12912] [H12913] [H12914] [H12915] [H12916] [H12917] [H12918]
1959 **
1960 */
1961 void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
1962
1963 /*
1964 ** CAPI3REF: Opening A New Database Connection {H12700} <S40200>
1965 **
1966 ** These routines open an SQLite database file whose name is given by the
1967 ** filename argument. The filename argument is interpreted as UTF-8 for
1968 ** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
1969 ** order for sqlite3_open16(). A [database connection] handle is usually
1970 ** returned in *ppDb, even if an error occurs.  The only exception is that
1971 ** if SQLite is unable to allocate memory to hold the [sqlite3] object,
1972 ** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
1973 ** object. If the database is opened (and/or created) successfully, then
1974 ** [SQLITE_OK] is returned.  Otherwise an [error code] is returned.  The
1975 ** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
1976 ** an English language description of the error.
1977 **
1978 ** The default encoding for the database will be UTF-8 if
1979 ** sqlite3_open() or sqlite3_open_v2() is called and
1980 ** UTF-16 in the native byte order if sqlite3_open16() is used.
1981 **
1982 ** Whether or not an error occurs when it is opened, resources
1983 ** associated with the [database connection] handle should be released by
1984 ** passing it to [sqlite3_close()] when it is no longer required.
1985 **
1986 ** The sqlite3_open_v2() interface works like sqlite3_open()
1987 ** except that it accepts two additional parameters for additional control
1988 ** over the new database connection.  The flags parameter can take one of
1989 ** the following three values, optionally combined with the 
1990 ** [SQLITE_OPEN_NOMUTEX] or [SQLITE_OPEN_FULLMUTEX] flags:
1991 **
1992 ** <dl>
1993 ** <dt>[SQLITE_OPEN_READONLY]</dt>
1994 ** <dd>The database is opened in read-only mode.  If the database does not
1995 ** already exist, an error is returned.</dd>
1996 **
1997 ** <dt>[SQLITE_OPEN_READWRITE]</dt>
1998 ** <dd>The database is opened for reading and writing if possible, or reading
1999 ** only if the file is write protected by the operating system.  In either
2000 ** case the database must already exist, otherwise an error is returned.</dd>
2001 **
2002 ** <dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
2003 ** <dd>The database is opened for reading and writing, and is creates it if
2004 ** it does not already exist. This is the behavior that is always used for
2005 ** sqlite3_open() and sqlite3_open16().</dd>
2006 ** </dl>
2007 **
2008 ** If the 3rd parameter to sqlite3_open_v2() is not one of the
2009 ** combinations shown above or one of the combinations shown above combined
2010 ** with the [SQLITE_OPEN_NOMUTEX] or [SQLITE_OPEN_FULLMUTEX] flags,
2011 ** then the behavior is undefined.
2012 **
2013 ** If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
2014 ** opens in the multi-thread [threading mode] as long as the single-thread
2015 ** mode has not been set at compile-time or start-time.  If the
2016 ** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
2017 ** in the serialized [threading mode] unless single-thread was
2018 ** previously selected at compile-time or start-time.
2019 **
2020 ** If the filename is ":memory:", then a private, temporary in-memory database
2021 ** is created for the connection.  This in-memory database will vanish when
2022 ** the database connection is closed.  Future versions of SQLite might
2023 ** make use of additional special filenames that begin with the ":" character.
2024 ** It is recommended that when a database filename actually does begin with
2025 ** a ":" character you should prefix the filename with a pathname such as
2026 ** "./" to avoid ambiguity.
2027 **
2028 ** If the filename is an empty string, then a private, temporary
2029 ** on-disk database will be created.  This private database will be
2030 ** automatically deleted as soon as the database connection is closed.
2031 **
2032 ** The fourth parameter to sqlite3_open_v2() is the name of the
2033 ** [sqlite3_vfs] object that defines the operating system interface that
2034 ** the new database connection should use.  If the fourth parameter is
2035 ** a NULL pointer then the default [sqlite3_vfs] object is used.
2036 **
2037 ** <b>Note to Windows users:</b>  The encoding used for the filename argument
2038 ** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
2039 ** codepage is currently defined.  Filenames containing international
2040 ** characters must be converted to UTF-8 prior to passing them into
2041 ** sqlite3_open() or sqlite3_open_v2().
2042 **
2043 ** Requirements:
2044 ** [H12701] [H12702] [H12703] [H12704] [H12706] [H12707] [H12709] [H12711]
2045 ** [H12712] [H12713] [H12714] [H12717] [H12719] [H12721] [H12723]
2046 */
2047 int sqlite3_open(
2048   const char *filename,   /* Database filename (UTF-8) */
2049   sqlite3 **ppDb          /* OUT: SQLite db handle */
2050 );
2051 int sqlite3_open16(
2052   const void *filename,   /* Database filename (UTF-16) */
2053   sqlite3 **ppDb          /* OUT: SQLite db handle */
2054 );
2055 int sqlite3_open_v2(
2056   const char *filename,   /* Database filename (UTF-8) */
2057   sqlite3 **ppDb,         /* OUT: SQLite db handle */
2058   int flags,              /* Flags */
2059   const char *zVfs        /* Name of VFS module to use */
2060 );
2061
2062 /*
2063 ** CAPI3REF: Error Codes And Messages {H12800} <S60200>
2064 **
2065 ** The sqlite3_errcode() interface returns the numeric [result code] or
2066 ** [extended result code] for the most recent failed sqlite3_* API call
2067 ** associated with a [database connection]. If a prior API call failed
2068 ** but the most recent API call succeeded, the return value from
2069 ** sqlite3_errcode() is undefined.  The sqlite3_extended_errcode()
2070 ** interface is the same except that it always returns the 
2071 ** [extended result code] even when extended result codes are
2072 ** disabled.
2073 **
2074 ** The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
2075 ** text that describes the error, as either UTF-8 or UTF-16 respectively.
2076 ** Memory to hold the error message string is managed internally.
2077 ** The application does not need to worry about freeing the result.
2078 ** However, the error string might be overwritten or deallocated by
2079 ** subsequent calls to other SQLite interface functions.
2080 **
2081 ** When the serialized [threading mode] is in use, it might be the
2082 ** case that a second error occurs on a separate thread in between
2083 ** the time of the first error and the call to these interfaces.
2084 ** When that happens, the second error will be reported since these
2085 ** interfaces always report the most recent result.  To avoid
2086 ** this, each thread can obtain exclusive use of the [database connection] D
2087 ** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
2088 ** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
2089 ** all calls to the interfaces listed here are completed.
2090 **
2091 ** If an interface fails with SQLITE_MISUSE, that means the interface
2092 ** was invoked incorrectly by the application.  In that case, the
2093 ** error code and message may or may not be set.
2094 **
2095 ** Requirements:
2096 ** [H12801] [H12802] [H12803] [H12807] [H12808] [H12809]
2097 */
2098 int sqlite3_errcode(sqlite3 *db);
2099 int sqlite3_extended_errcode(sqlite3 *db);
2100 const char *sqlite3_errmsg(sqlite3*);
2101 const void *sqlite3_errmsg16(sqlite3*);
2102
2103 /*
2104 ** CAPI3REF: SQL Statement Object {H13000} <H13010>
2105 ** KEYWORDS: {prepared statement} {prepared statements}
2106 **
2107 ** An instance of this object represents a single SQL statement.
2108 ** This object is variously known as a "prepared statement" or a
2109 ** "compiled SQL statement" or simply as a "statement".
2110 **
2111 ** The life of a statement object goes something like this:
2112 **
2113 ** <ol>
2114 ** <li> Create the object using [sqlite3_prepare_v2()] or a related
2115 **      function.
2116 ** <li> Bind values to [host parameters] using the sqlite3_bind_*()
2117 **      interfaces.
2118 ** <li> Run the SQL by calling [sqlite3_step()] one or more times.
2119 ** <li> Reset the statement using [sqlite3_reset()] then go back
2120 **      to step 2.  Do this zero or more times.
2121 ** <li> Destroy the object using [sqlite3_finalize()].
2122 ** </ol>
2123 **
2124 ** Refer to documentation on individual methods above for additional
2125 ** information.
2126 */
2127 typedef struct sqlite3_stmt sqlite3_stmt;
2128
2129 /*
2130 ** CAPI3REF: Run-time Limits {H12760} <S20600>
2131 **
2132 ** This interface allows the size of various constructs to be limited
2133 ** on a connection by connection basis.  The first parameter is the
2134 ** [database connection] whose limit is to be set or queried.  The
2135 ** second parameter is one of the [limit categories] that define a
2136 ** class of constructs to be size limited.  The third parameter is the
2137 ** new limit for that construct.  The function returns the old limit.
2138 **
2139 ** If the new limit is a negative number, the limit is unchanged.
2140 ** For the limit category of SQLITE_LIMIT_XYZ there is a 
2141 ** [limits | hard upper bound]
2142 ** set by a compile-time C preprocessor macro named 
2143 ** [limits | SQLITE_MAX_XYZ].
2144 ** (The "_LIMIT_" in the name is changed to "_MAX_".)
2145 ** Attempts to increase a limit above its hard upper bound are
2146 ** silently truncated to the hard upper limit.
2147 **
2148 ** Run time limits are intended for use in applications that manage
2149 ** both their own internal database and also databases that are controlled
2150 ** by untrusted external sources.  An example application might be a
2151 ** web browser that has its own databases for storing history and
2152 ** separate databases controlled by JavaScript applications downloaded
2153 ** off the Internet.  The internal databases can be given the
2154 ** large, default limits.  Databases managed by external sources can
2155 ** be given much smaller limits designed to prevent a denial of service
2156 ** attack.  Developers might also want to use the [sqlite3_set_authorizer()]
2157 ** interface to further control untrusted SQL.  The size of the database
2158 ** created by an untrusted script can be contained using the
2159 ** [max_page_count] [PRAGMA].
2160 **
2161 ** New run-time limit categories may be added in future releases.
2162 **
2163 ** Requirements:
2164 ** [H12762] [H12766] [H12769]
2165 */
2166 int sqlite3_limit(sqlite3*, int id, int newVal);
2167
2168 /*
2169 ** CAPI3REF: Run-Time Limit Categories {H12790} <H12760>
2170 ** KEYWORDS: {limit category} {limit categories}
2171 **
2172 ** These constants define various performance limits
2173 ** that can be lowered at run-time using [sqlite3_limit()].
2174 ** The synopsis of the meanings of the various limits is shown below.
2175 ** Additional information is available at [limits | Limits in SQLite].
2176 **
2177 ** <dl>
2178 ** <dt>SQLITE_LIMIT_LENGTH</dt>
2179 ** <dd>The maximum size of any string or BLOB or table row.<dd>
2180 **
2181 ** <dt>SQLITE_LIMIT_SQL_LENGTH</dt>
2182 ** <dd>The maximum length of an SQL statement.</dd>
2183 **
2184 ** <dt>SQLITE_LIMIT_COLUMN</dt>
2185 ** <dd>The maximum number of columns in a table definition or in the
2186 ** result set of a [SELECT] or the maximum number of columns in an index
2187 ** or in an ORDER BY or GROUP BY clause.</dd>
2188 **
2189 ** <dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
2190 ** <dd>The maximum depth of the parse tree on any expression.</dd>
2191 **
2192 ** <dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
2193 ** <dd>The maximum number of terms in a compound SELECT statement.</dd>
2194 **
2195 ** <dt>SQLITE_LIMIT_VDBE_OP</dt>
2196 ** <dd>The maximum number of instructions in a virtual machine program
2197 ** used to implement an SQL statement.</dd>
2198 **
2199 ** <dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
2200 ** <dd>The maximum number of arguments on a function.</dd>
2201 **
2202 ** <dt>SQLITE_LIMIT_ATTACHED</dt>
2203 ** <dd>The maximum number of [ATTACH | attached databases].</dd>
2204 **
2205 ** <dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
2206 ** <dd>The maximum length of the pattern argument to the [LIKE] or
2207 ** [GLOB] operators.</dd>
2208 **
2209 ** <dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
2210 ** <dd>The maximum number of variables in an SQL statement that can
2211 ** be bound.</dd>
2212 ** </dl>
2213 */
2214 #define SQLITE_LIMIT_LENGTH                    0
2215 #define SQLITE_LIMIT_SQL_LENGTH                1
2216 #define SQLITE_LIMIT_COLUMN                    2
2217 #define SQLITE_LIMIT_EXPR_DEPTH                3
2218 #define SQLITE_LIMIT_COMPOUND_SELECT           4
2219 #define SQLITE_LIMIT_VDBE_OP                   5
2220 #define SQLITE_LIMIT_FUNCTION_ARG              6
2221 #define SQLITE_LIMIT_ATTACHED                  7
2222 #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8
2223 #define SQLITE_LIMIT_VARIABLE_NUMBER           9
2224
2225 /*
2226 ** CAPI3REF: Compiling An SQL Statement {H13010} <S10000>
2227 ** KEYWORDS: {SQL statement compiler}
2228 **
2229 ** To execute an SQL query, it must first be compiled into a byte-code
2230 ** program using one of these routines.
2231 **
2232 ** The first argument, "db", is a [database connection] obtained from a
2233 ** prior call to [sqlite3_open()], [sqlite3_open_v2()] or [sqlite3_open16()].
2234 **
2235 ** The second argument, "zSql", is the statement to be compiled, encoded
2236 ** as either UTF-8 or UTF-16.  The sqlite3_prepare() and sqlite3_prepare_v2()
2237 ** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
2238 ** use UTF-16.
2239 **
2240 ** If the nByte argument is less than zero, then zSql is read up to the
2241 ** first zero terminator. If nByte is non-negative, then it is the maximum
2242 ** number of  bytes read from zSql.  When nByte is non-negative, the
2243 ** zSql string ends at either the first '\000' or '\u0000' character or
2244 ** the nByte-th byte, whichever comes first. If the caller knows
2245 ** that the supplied string is nul-terminated, then there is a small
2246 ** performance advantage to be gained by passing an nByte parameter that
2247 ** is equal to the number of bytes in the input string <i>including</i>
2248 ** the nul-terminator bytes.
2249 **
2250 ** *pzTail is made to point to the first byte past the end of the
2251 ** first SQL statement in zSql.  These routines only compile the first
2252 ** statement in zSql, so *pzTail is left pointing to what remains
2253 ** uncompiled.
2254 **
2255 ** *ppStmt is left pointing to a compiled [prepared statement] that can be
2256 ** executed using [sqlite3_step()].  If there is an error, *ppStmt is set
2257 ** to NULL.  If the input text contains no SQL (if the input is an empty
2258 ** string or a comment) then *ppStmt is set to NULL.
2259 ** {A13018} The calling procedure is responsible for deleting the compiled
2260 ** SQL statement using [sqlite3_finalize()] after it has finished with it.
2261 **
2262 ** On success, [SQLITE_OK] is returned, otherwise an [error code] is returned.
2263 **
2264 ** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
2265 ** recommended for all new programs. The two older interfaces are retained
2266 ** for backwards compatibility, but their use is discouraged.
2267 ** In the "v2" interfaces, the prepared statement
2268 ** that is returned (the [sqlite3_stmt] object) contains a copy of the
2269 ** original SQL text. This causes the [sqlite3_step()] interface to
2270 ** behave a differently in two ways:
2271 **
2272 ** <ol>
2273 ** <li>
2274 ** If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
2275 ** always used to do, [sqlite3_step()] will automatically recompile the SQL
2276 ** statement and try to run it again.  If the schema has changed in
2277 ** a way that makes the statement no longer valid, [sqlite3_step()] will still
2278 ** return [SQLITE_SCHEMA].  But unlike the legacy behavior, [SQLITE_SCHEMA] is
2279 ** now a fatal error.  Calling [sqlite3_prepare_v2()] again will not make the
2280 ** error go away.  Note: use [sqlite3_errmsg()] to find the text
2281 ** of the parsing error that results in an [SQLITE_SCHEMA] return.
2282 ** </li>
2283 **
2284 ** <li>
2285 ** When an error occurs, [sqlite3_step()] will return one of the detailed
2286 ** [error codes] or [extended error codes].  The legacy behavior was that
2287 ** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
2288 ** and you would have to make a second call to [sqlite3_reset()] in order
2289 ** to find the underlying cause of the problem. With the "v2" prepare
2290 ** interfaces, the underlying reason for the error is returned immediately.
2291 ** </li>
2292 ** </ol>
2293 **
2294 ** Requirements:
2295 ** [H13011] [H13012] [H13013] [H13014] [H13015] [H13016] [H13019] [H13021]
2296 **
2297 */
2298 int sqlite3_prepare(
2299   sqlite3 *db,            /* Database handle */
2300   const char *zSql,       /* SQL statement, UTF-8 encoded */
2301   int nByte,              /* Maximum length of zSql in bytes. */
2302   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
2303   const char **pzTail     /* OUT: Pointer to unused portion of zSql */
2304 );
2305 int sqlite3_prepare_v2(
2306   sqlite3 *db,            /* Database handle */
2307   const char *zSql,       /* SQL statement, UTF-8 encoded */
2308   int nByte,              /* Maximum length of zSql in bytes. */
2309   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
2310   const char **pzTail     /* OUT: Pointer to unused portion of zSql */
2311 );
2312 int sqlite3_prepare16(
2313   sqlite3 *db,            /* Database handle */
2314   const void *zSql,       /* SQL statement, UTF-16 encoded */
2315   int nByte,              /* Maximum length of zSql in bytes. */
2316   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
2317   const void **pzTail     /* OUT: Pointer to unused portion of zSql */
2318 );
2319 int sqlite3_prepare16_v2(
2320   sqlite3 *db,            /* Database handle */
2321   const void *zSql,       /* SQL statement, UTF-16 encoded */
2322   int nByte,              /* Maximum length of zSql in bytes. */
2323   sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
2324   const void **pzTail     /* OUT: Pointer to unused portion of zSql */
2325 );
2326
2327 /*
2328 ** CAPI3REF: Retrieving Statement SQL {H13100} <H13000>
2329 **
2330 ** This interface can be used to retrieve a saved copy of the original
2331 ** SQL text used to create a [prepared statement] if that statement was
2332 ** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
2333 **
2334 ** Requirements:
2335 ** [H13101] [H13102] [H13103]
2336 */
2337 const char *sqlite3_sql(sqlite3_stmt *pStmt);
2338
2339 /*
2340 ** CAPI3REF: Dynamically Typed Value Object {H15000} <S20200>
2341 ** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
2342 **
2343 ** SQLite uses the sqlite3_value object to represent all values
2344 ** that can be stored in a database table. SQLite uses dynamic typing
2345 ** for the values it stores. Values stored in sqlite3_value objects
2346 ** can be integers, floating point values, strings, BLOBs, or NULL.
2347 **
2348 ** An sqlite3_value object may be either "protected" or "unprotected".
2349 ** Some interfaces require a protected sqlite3_value.  Other interfaces
2350 ** will accept either a protected or an unprotected sqlite3_value.
2351 ** Every interface that accepts sqlite3_value arguments specifies
2352 ** whether or not it requires a protected sqlite3_value.
2353 **
2354 ** The terms "protected" and "unprotected" refer to whether or not
2355 ** a mutex is held.  A internal mutex is held for a protected
2356 ** sqlite3_value object but no mutex is held for an unprotected
2357 ** sqlite3_value object.  If SQLite is compiled to be single-threaded
2358 ** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
2359 ** or if SQLite is run in one of reduced mutex modes 
2360 ** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
2361 ** then there is no distinction between protected and unprotected
2362 ** sqlite3_value objects and they can be used interchangeably.  However,
2363 ** for maximum code portability it is recommended that applications
2364 ** still make the distinction between between protected and unprotected
2365 ** sqlite3_value objects even when not strictly required.
2366 **
2367 ** The sqlite3_value objects that are passed as parameters into the
2368 ** implementation of [application-defined SQL functions] are protected.
2369 ** The sqlite3_value object returned by
2370 ** [sqlite3_column_value()] is unprotected.
2371 ** Unprotected sqlite3_value objects may only be used with
2372 ** [sqlite3_result_value()] and [sqlite3_bind_value()].
2373 ** The [sqlite3_value_blob | sqlite3_value_type()] family of
2374 ** interfaces require protected sqlite3_value objects.
2375 */
2376 typedef struct Mem sqlite3_value;
2377
2378 /*
2379 ** CAPI3REF: SQL Function Context Object {H16001} <S20200>
2380 **
2381 ** The context in which an SQL function executes is stored in an
2382 ** sqlite3_context object.  A pointer to an sqlite3_context object
2383 ** is always first parameter to [application-defined SQL functions].
2384 ** The application-defined SQL function implementation will pass this
2385 ** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
2386 ** [sqlite3_aggregate_context()], [sqlite3_user_data()],
2387 ** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
2388 ** and/or [sqlite3_set_auxdata()].
2389 */
2390 typedef struct sqlite3_context sqlite3_context;
2391
2392 /*
2393 ** CAPI3REF: Binding Values To Prepared Statements {H13500} <S70300>
2394 ** KEYWORDS: {host parameter} {host parameters} {host parameter name}
2395 ** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
2396 **
2397 ** In the SQL strings input to [sqlite3_prepare_v2()] and its variants,
2398 ** literals may be replaced by a [parameter] in one of these forms:
2399 **
2400 ** <ul>
2401 ** <li>  ?
2402 ** <li>  ?NNN
2403 ** <li>  :VVV
2404 ** <li>  @VVV
2405 ** <li>  $VVV
2406 ** </ul>
2407 **
2408 ** In the parameter forms shown above NNN is an integer literal,
2409 ** and VVV is an alpha-numeric parameter name. The values of these
2410 ** parameters (also called "host parameter names" or "SQL parameters")
2411 ** can be set using the sqlite3_bind_*() routines defined here.
2412 **
2413 ** The first argument to the sqlite3_bind_*() routines is always
2414 ** a pointer to the [sqlite3_stmt] object returned from
2415 ** [sqlite3_prepare_v2()] or its variants.
2416 **
2417 ** The second argument is the index of the SQL parameter to be set.
2418 ** The leftmost SQL parameter has an index of 1.  When the same named
2419 ** SQL parameter is used more than once, second and subsequent
2420 ** occurrences have the same index as the first occurrence.
2421 ** The index for named parameters can be looked up using the
2422 ** [sqlite3_bind_parameter_index()] API if desired.  The index
2423 ** for "?NNN" parameters is the value of NNN.
2424 ** The NNN value must be between 1 and the [sqlite3_limit()]
2425 ** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
2426 **
2427 ** The third argument is the value to bind to the parameter.
2428 **
2429 ** In those routines that have a fourth argument, its value is the
2430 ** number of bytes in the parameter.  To be clear: the value is the
2431 ** number of <u>bytes</u> in the value, not the number of characters.
2432 ** If the fourth parameter is negative, the length of the string is
2433 ** the number of bytes up to the first zero terminator.
2434 **
2435 ** The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
2436 ** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
2437 ** string after SQLite has finished with it. If the fifth argument is
2438 ** the special value [SQLITE_STATIC], then SQLite assumes that the
2439 ** information is in static, unmanaged space and does not need to be freed.
2440 ** If the fifth argument has the value [SQLITE_TRANSIENT], then
2441 ** SQLite makes its own private copy of the data immediately, before
2442 ** the sqlite3_bind_*() routine returns.
2443 **
2444 ** The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
2445 ** is filled with zeroes.  A zeroblob uses a fixed amount of memory
2446 ** (just an integer to hold its size) while it is being processed.
2447 ** Zeroblobs are intended to serve as placeholders for BLOBs whose
2448 ** content is later written using
2449 ** [sqlite3_blob_open | incremental BLOB I/O] routines.
2450 ** A negative value for the zeroblob results in a zero-length BLOB.
2451 **
2452 ** The sqlite3_bind_*() routines must be called after
2453 ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
2454 ** before [sqlite3_step()].
2455 ** Bindings are not cleared by the [sqlite3_reset()] routine.
2456 ** Unbound parameters are interpreted as NULL.
2457 **
2458 ** These routines return [SQLITE_OK] on success or an error code if
2459 ** anything goes wrong.  [SQLITE_RANGE] is returned if the parameter
2460 ** index is out of range.  [SQLITE_NOMEM] is returned if malloc() fails.
2461 ** [SQLITE_MISUSE] might be returned if these routines are called on a
2462 ** virtual machine that is the wrong state or which has already been finalized.
2463 ** Detection of misuse is unreliable.  Applications should not depend
2464 ** on SQLITE_MISUSE returns.  SQLITE_MISUSE is intended to indicate a
2465 ** a logic error in the application.  Future versions of SQLite might
2466 ** panic rather than return SQLITE_MISUSE.
2467 **
2468 ** See also: [sqlite3_bind_parameter_count()],
2469 ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
2470 **
2471 ** Requirements:
2472 ** [H13506] [H13509] [H13512] [H13515] [H13518] [H13521] [H13524] [H13527]
2473 ** [H13530] [H13533] [H13536] [H13539] [H13542] [H13545] [H13548] [H13551]
2474 **
2475 */
2476 int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
2477 int sqlite3_bind_double(sqlite3_stmt*, int, double);
2478 int sqlite3_bind_int(sqlite3_stmt*, int, int);
2479 int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
2480 int sqlite3_bind_null(sqlite3_stmt*, int);
2481 int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
2482 int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
2483 int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
2484 int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
2485
2486 /*
2487 ** CAPI3REF: Number Of SQL Parameters {H13600} <S70300>
2488 **
2489 ** This routine can be used to find the number of [SQL parameters]
2490 ** in a [prepared statement].  SQL parameters are tokens of the
2491 ** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
2492 ** placeholders for values that are [sqlite3_bind_blob | bound]
2493 ** to the parameters at a later time.
2494 **
2495 ** This routine actually returns the index of the largest (rightmost)
2496 ** parameter. For all forms except ?NNN, this will correspond to the
2497 ** number of unique parameters.  If parameters of the ?NNN are used,
2498 ** there may be gaps in the list.
2499 **
2500 ** See also: [sqlite3_bind_blob|sqlite3_bind()],
2501 ** [sqlite3_bind_parameter_name()], and
2502 ** [sqlite3_bind_parameter_index()].
2503 **
2504 ** Requirements:
2505 ** [H13601]
2506 */
2507 int sqlite3_bind_parameter_count(sqlite3_stmt*);
2508
2509 /*
2510 ** CAPI3REF: Name Of A Host Parameter {H13620} <S70300>
2511 **
2512 ** This routine returns a pointer to the name of the n-th
2513 ** [SQL parameter] in a [prepared statement].
2514 ** SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
2515 ** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
2516 ** respectively.
2517 ** In other words, the initial ":" or "$" or "@" or "?"
2518 ** is included as part of the name.
2519 ** Parameters of the form "?" without a following integer have no name
2520 ** and are also referred to as "anonymous parameters".
2521 **
2522 ** The first host parameter has an index of 1, not 0.
2523 **
2524 ** If the value n is out of range or if the n-th parameter is
2525 ** nameless, then NULL is returned.  The returned string is
2526 ** always in UTF-8 encoding even if the named parameter was
2527 ** originally specified as UTF-16 in [sqlite3_prepare16()] or
2528 ** [sqlite3_prepare16_v2()].
2529 **
2530 ** See also: [sqlite3_bind_blob|sqlite3_bind()],
2531 ** [sqlite3_bind_parameter_count()], and
2532 ** [sqlite3_bind_parameter_index()].
2533 **
2534 ** Requirements:
2535 ** [H13621]
2536 */
2537 const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
2538
2539 /*
2540 ** CAPI3REF: Index Of A Parameter With A Given Name {H13640} <S70300>
2541 **
2542 ** Return the index of an SQL parameter given its name.  The
2543 ** index value returned is suitable for use as the second
2544 ** parameter to [sqlite3_bind_blob|sqlite3_bind()].  A zero
2545 ** is returned if no matching parameter is found.  The parameter
2546 ** name must be given in UTF-8 even if the original statement
2547 ** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
2548 **
2549 ** See also: [sqlite3_bind_blob|sqlite3_bind()],
2550 ** [sqlite3_bind_parameter_count()], and
2551 ** [sqlite3_bind_parameter_index()].
2552 **
2553 ** Requirements:
2554 ** [H13641]
2555 */
2556 int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
2557
2558 /*
2559 ** CAPI3REF: Reset All Bindings On A Prepared Statement {H13660} <S70300>
2560 **
2561 ** Contrary to the intuition of many, [sqlite3_reset()] does not reset
2562 ** the [sqlite3_bind_blob | bindings] on a [prepared statement].
2563 ** Use this routine to reset all host parameters to NULL.
2564 **
2565 ** Requirements:
2566 ** [H13661]
2567 */
2568 int sqlite3_clear_bindings(sqlite3_stmt*);
2569
2570 /*
2571 ** CAPI3REF: Number Of Columns In A Result Set {H13710} <S10700>
2572 **
2573 ** Return the number of columns in the result set returned by the
2574 ** [prepared statement]. This routine returns 0 if pStmt is an SQL
2575 ** statement that does not return data (for example an [UPDATE]).
2576 **
2577 ** Requirements:
2578 ** [H13711]
2579 */
2580 int sqlite3_column_count(sqlite3_stmt *pStmt);
2581
2582 /*
2583 ** CAPI3REF: Column Names In A Result Set {H13720} <S10700>
2584 **
2585 ** These routines return the name assigned to a particular column
2586 ** in the result set of a [SELECT] statement.  The sqlite3_column_name()
2587 ** interface returns a pointer to a zero-terminated UTF-8 string
2588 ** and sqlite3_column_name16() returns a pointer to a zero-terminated
2589 ** UTF-16 string.  The first parameter is the [prepared statement]
2590 ** that implements the [SELECT] statement. The second parameter is the
2591 ** column number.  The leftmost column is number 0.
2592 **
2593 ** The returned string pointer is valid until either the [prepared statement]
2594 ** is destroyed by [sqlite3_finalize()] or until the next call to
2595 ** sqlite3_column_name() or sqlite3_column_name16() on the same column.
2596 **
2597 ** If sqlite3_malloc() fails during the processing of either routine
2598 ** (for example during a conversion from UTF-8 to UTF-16) then a
2599 ** NULL pointer is returned.
2600 **
2601 ** The name of a result column is the value of the "AS" clause for
2602 ** that column, if there is an AS clause.  If there is no AS clause
2603 ** then the name of the column is unspecified and may change from
2604 ** one release of SQLite to the next.
2605 **
2606 ** Requirements:
2607 ** [H13721] [H13723] [H13724] [H13725] [H13726] [H13727]
2608 */
2609 const char *sqlite3_column_name(sqlite3_stmt*, int N);
2610 const void *sqlite3_column_name16(sqlite3_stmt*, int N);
2611
2612 /*
2613 ** CAPI3REF: Source Of Data In A Query Result {H13740} <S10700>
2614 **
2615 ** These routines provide a means to determine what column of what
2616 ** table in which database a result of a [SELECT] statement comes from.
2617 ** The name of the database or table or column can be returned as
2618 ** either a UTF-8 or UTF-16 string.  The _database_ routines return
2619 ** the database name, the _table_ routines return the table name, and
2620 ** the origin_ routines return the column name.
2621 ** The returned string is valid until the [prepared statement] is destroyed
2622 ** using [sqlite3_finalize()] or until the same information is requested
2623 ** again in a different encoding.
2624 **
2625 ** The names returned are the original un-aliased names of the
2626 ** database, table, and column.
2627 **
2628 ** The first argument to the following calls is a [prepared statement].
2629 ** These functions return information about the Nth column returned by
2630 ** the statement, where N is the second function argument.
2631 **
2632 ** If the Nth column returned by the statement is an expression or
2633 ** subquery and is not a column value, then all of these functions return
2634 ** NULL.  These routine might also return NULL if a memory allocation error
2635 ** occurs.  Otherwise, they return the name of the attached database, table
2636 ** and column that query result column was extracted from.
2637 **
2638 ** As with all other SQLite APIs, those postfixed with "16" return
2639 ** UTF-16 encoded strings, the other functions return UTF-8. {END}
2640 **
2641 ** These APIs are only available if the library was compiled with the
2642 ** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol defined.
2643 **
2644 ** {A13751}
2645 ** If two or more threads call one or more of these routines against the same
2646 ** prepared statement and column at the same time then the results are
2647 ** undefined.
2648 **
2649 ** Requirements:
2650 ** [H13741] [H13742] [H13743] [H13744] [H13745] [H13746] [H13748]
2651 **
2652 ** If two or more threads call one or more
2653 ** [sqlite3_column_database_name | column metadata interfaces]
2654 ** for the same [prepared statement] and result column
2655 ** at the same time then the results are undefined.
2656 */
2657 const char *sqlite3_column_database_name(sqlite3_stmt*,int);
2658 const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
2659 const char *sqlite3_column_table_name(sqlite3_stmt*,int);
2660 const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
2661 const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
2662 const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
2663
2664 /*
2665 ** CAPI3REF: Declared Datatype Of A Query Result {H13760} <S10700>
2666 **
2667 ** The first parameter is a [prepared statement].
2668 ** If this statement is a [SELECT] statement and the Nth column of the
2669 ** returned result set of that [SELECT] is a table column (not an
2670 ** expression or subquery) then the declared type of the table
2671 ** column is returned.  If the Nth column of the result set is an
2672 ** expression or subquery, then a NULL pointer is returned.
2673 ** The returned string is always UTF-8 encoded. {END}
2674 **
2675 ** For example, given the database schema:
2676 **
2677 ** CREATE TABLE t1(c1 VARIANT);
2678 **
2679 ** and the following statement to be compiled:
2680 **
2681 ** SELECT c1 + 1, c1 FROM t1;
2682 **
2683 ** this routine would return the string "VARIANT" for the second result
2684 ** column (i==1), and a NULL pointer for the first result column (i==0).
2685 **
2686 ** SQLite uses dynamic run-time typing.  So just because a column
2687 ** is declared to contain a particular type does not mean that the
2688 ** data stored in that column is of the declared type.  SQLite is
2689 ** strongly typed, but the typing is dynamic not static.  Type
2690 ** is associated with individual values, not with the containers
2691 ** used to hold those values.
2692 **
2693 ** Requirements:
2694 ** [H13761] [H13762] [H13763]
2695 */
2696 const char *sqlite3_column_decltype(sqlite3_stmt*,int);
2697 const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
2698
2699 /*
2700 ** CAPI3REF: Evaluate An SQL Statement {H13200} <S10000>
2701 **
2702 ** After a [prepared statement] has been prepared using either
2703 ** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
2704 ** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
2705 ** must be called one or more times to evaluate the statement.
2706 **
2707 ** The details of the behavior of the sqlite3_step() interface depend
2708 ** on whether the statement was prepared using the newer "v2" interface
2709 ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
2710 ** interface [sqlite3_prepare()] and [sqlite3_prepare16()].  The use of the
2711 ** new "v2" interface is recommended for new applications but the legacy
2712 ** interface will continue to be supported.
2713 **
2714 ** In the legacy interface, the return value will be either [SQLITE_BUSY],
2715 ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
2716 ** With the "v2" interface, any of the other [result codes] or
2717 ** [extended result codes] might be returned as well.
2718 **
2719 ** [SQLITE_BUSY] means that the database engine was unable to acquire the
2720 ** database locks it needs to do its job.  If the statement is a [COMMIT]
2721 ** or occurs outside of an explicit transaction, then you can retry the
2722 ** statement.  If the statement is not a [COMMIT] and occurs within a
2723 ** explicit transaction then you should rollback the transaction before
2724 ** continuing.
2725 **
2726 ** [SQLITE_DONE] means that the statement has finished executing
2727 ** successfully.  sqlite3_step() should not be called again on this virtual
2728 ** machine without first calling [sqlite3_reset()] to reset the virtual
2729 ** machine back to its initial state.
2730 **
2731 ** If the SQL statement being executed returns any data, then [SQLITE_ROW]
2732 ** is returned each time a new row of data is ready for processing by the
2733 ** caller. The values may be accessed using the [column access functions].
2734 ** sqlite3_step() is called again to retrieve the next row of data.
2735 **
2736 ** [SQLITE_ERROR] means that a run-time error (such as a constraint
2737 ** violation) has occurred.  sqlite3_step() should not be called again on
2738 ** the VM. More information may be found by calling [sqlite3_errmsg()].
2739 ** With the legacy interface, a more specific error code (for example,
2740 ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
2741 ** can be obtained by calling [sqlite3_reset()] on the
2742 ** [prepared statement].  In the "v2" interface,
2743 ** the more specific error code is returned directly by sqlite3_step().
2744 **
2745 ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
2746 ** Perhaps it was called on a [prepared statement] that has
2747 ** already been [sqlite3_finalize | finalized] or on one that had
2748 ** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could
2749 ** be the case that the same database connection is being used by two or
2750 ** more threads at the same moment in time.
2751 **
2752 ** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
2753 ** API always returns a generic error code, [SQLITE_ERROR], following any
2754 ** error other than [SQLITE_BUSY] and [SQLITE_MISUSE].  You must call
2755 ** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
2756 ** specific [error codes] that better describes the error.
2757 ** We admit that this is a goofy design.  The problem has been fixed
2758 ** with the "v2" interface.  If you prepare all of your SQL statements
2759 ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
2760 ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
2761 ** then the more specific [error codes] are returned directly
2762 ** by sqlite3_step().  The use of the "v2" interface is recommended.
2763 **
2764 ** Requirements:
2765 ** [H13202] [H15304] [H15306] [H15308] [H15310]
2766 */
2767 int sqlite3_step(sqlite3_stmt*);
2768
2769 /*
2770 ** CAPI3REF: Number of columns in a result set {H13770} <S10700>
2771 **
2772 ** Returns the number of values in the current row of the result set.
2773 **
2774 ** Requirements:
2775 ** [H13771] [H13772]
2776 */
2777 int sqlite3_data_count(sqlite3_stmt *pStmt);
2778
2779 /*
2780 ** CAPI3REF: Fundamental Datatypes {H10265} <S10110><S10120>
2781 ** KEYWORDS: SQLITE_TEXT
2782 **
2783 ** {H10266} Every value in SQLite has one of five fundamental datatypes:
2784 **
2785 ** <ul>
2786 ** <li> 64-bit signed integer
2787 ** <li> 64-bit IEEE floating point number
2788 ** <li> string
2789 ** <li> BLOB
2790 ** <li> NULL
2791 ** </ul> {END}
2792 **
2793 ** These constants are codes for each of those types.
2794 **
2795 ** Note that the SQLITE_TEXT constant was also used in SQLite version 2
2796 ** for a completely different meaning.  Software that links against both
2797 ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
2798 ** SQLITE_TEXT.
2799 */
2800 #define SQLITE_INTEGER  1
2801 #define SQLITE_FLOAT    2
2802 #define SQLITE_BLOB     4
2803 #define SQLITE_NULL     5
2804 #ifdef SQLITE_TEXT
2805 # undef SQLITE_TEXT
2806 #else
2807 # define SQLITE_TEXT     3
2808 #endif
2809 #define SQLITE3_TEXT     3
2810
2811 /*
2812 ** CAPI3REF: Result Values From A Query {H13800} <S10700>
2813 ** KEYWORDS: {column access functions}
2814 **
2815 ** These routines form the "result set query" interface.
2816 **
2817 ** These routines return information about a single column of the current
2818 ** result row of a query.  In every case the first argument is a pointer
2819 ** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
2820 ** that was returned from [sqlite3_prepare_v2()] or one of its variants)
2821 ** and the second argument is the index of the column for which information
2822 ** should be returned.  The leftmost column of the result set has the index 0.
2823 **
2824 ** If the SQL statement does not currently point to a valid row, or if the
2825 ** column index is out of range, the result is undefined.
2826 ** These routines may only be called when the most recent call to
2827 ** [sqlite3_step()] has returned [SQLITE_ROW] and neither
2828 ** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
2829 ** If any of these routines are called after [sqlite3_reset()] or
2830 ** [sqlite3_finalize()] or after [sqlite3_step()] has returned
2831 ** something other than [SQLITE_ROW], the results are undefined.
2832 ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
2833 ** are called from a different thread while any of these routines
2834 ** are pending, then the results are undefined.
2835 **
2836 ** The sqlite3_column_type() routine returns the
2837 ** [SQLITE_INTEGER | datatype code] for the initial data type
2838 ** of the result column.  The returned value is one of [SQLITE_INTEGER],
2839 ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].  The value
2840 ** returned by sqlite3_column_type() is only meaningful if no type
2841 ** conversions have occurred as described below.  After a type conversion,
2842 ** the value returned by sqlite3_column_type() is undefined.  Future
2843 ** versions of SQLite may change the behavior of sqlite3_column_type()
2844 ** following a type conversion.
2845 **
2846 ** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
2847 ** routine returns the number of bytes in that BLOB or string.
2848 ** If the result is a UTF-16 string, then sqlite3_column_bytes() converts
2849 ** the string to UTF-8 and then returns the number of bytes.
2850 ** If the result is a numeric value then sqlite3_column_bytes() uses
2851 ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
2852 ** the number of bytes in that string.
2853 ** The value returned does not include the zero terminator at the end
2854 ** of the string.  For clarity: the value returned is the number of
2855 ** bytes in the string, not the number of characters.
2856 **
2857 ** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
2858 ** even empty strings, are always zero terminated.  The return
2859 ** value from sqlite3_column_blob() for a zero-length BLOB is an arbitrary
2860 ** pointer, possibly even a NULL pointer.
2861 **
2862 ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
2863 ** but leaves the result in UTF-16 in native byte order instead of UTF-8.
2864 ** The zero terminator is not included in this count.
2865 **
2866 ** The object returned by [sqlite3_column_value()] is an
2867 ** [unprotected sqlite3_value] object.  An unprotected sqlite3_value object
2868 ** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
2869 ** If the [unprotected sqlite3_value] object returned by
2870 ** [sqlite3_column_value()] is used in any other way, including calls
2871 ** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
2872 ** or [sqlite3_value_bytes()], then the behavior is undefined.
2873 **
2874 ** These routines attempt to convert the value where appropriate.  For
2875 ** example, if the internal representation is FLOAT and a text result
2876 ** is requested, [sqlite3_snprintf()] is used internally to perform the
2877 ** conversion automatically.  The following table details the conversions
2878 ** that are applied:
2879 **
2880 ** <blockquote>
2881 ** <table border="1">
2882 ** <tr><th> Internal<br>Type <th> Requested<br>Type <th>  Conversion
2883 **
2884 ** <tr><td>  NULL    <td> INTEGER   <td> Result is 0
2885 ** <tr><td>  NULL    <td>  FLOAT    <td> Result is 0.0
2886 ** <tr><td>  NULL    <td>   TEXT    <td> Result is NULL pointer
2887 ** <tr><td>  NULL    <td>   BLOB    <td> Result is NULL pointer
2888 ** <tr><td> INTEGER  <td>  FLOAT    <td> Convert from integer to float
2889 ** <tr><td> INTEGER  <td>   TEXT    <td> ASCII rendering of the integer
2890 ** <tr><td> INTEGER  <td>   BLOB    <td> Same as INTEGER->TEXT
2891 ** <tr><td>  FLOAT   <td> INTEGER   <td> Convert from float to integer
2892 ** <tr><td>  FLOAT   <td>   TEXT    <td> ASCII rendering of the float
2893 ** <tr><td>  FLOAT   <td>   BLOB    <td> Same as FLOAT->TEXT
2894 ** <tr><td>  TEXT    <td> INTEGER   <td> Use atoi()
2895 ** <tr><td>  TEXT    <td>  FLOAT    <td> Use atof()
2896 ** <tr><td>  TEXT    <td>   BLOB    <td> No change
2897 ** <tr><td>  BLOB    <td> INTEGER   <td> Convert to TEXT then use atoi()
2898 ** <tr><td>  BLOB    <td>  FLOAT    <td> Convert to TEXT then use atof()
2899 ** <tr><td>  BLOB    <td>   TEXT    <td> Add a zero terminator if needed
2900 ** </table>
2901 ** </blockquote>
2902 **
2903 ** The table above makes reference to standard C library functions atoi()
2904 ** and atof().  SQLite does not really use these functions.  It has its
2905 ** own equivalent internal routines.  The atoi() and atof() names are
2906 ** used in the table for brevity and because they are familiar to most
2907 ** C programmers.
2908 **
2909 ** Note that when type conversions occur, pointers returned by prior
2910 ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
2911 ** sqlite3_column_text16() may be invalidated.
2912 ** Type conversions and pointer invalidations might occur
2913 ** in the following cases:
2914 **
2915 ** <ul>
2916 ** <li> The initial content is a BLOB and sqlite3_column_text() or
2917 **      sqlite3_column_text16() is called.  A zero-terminator might
2918 **      need to be added to the string.</li>
2919 ** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
2920 **      sqlite3_column_text16() is called.  The content must be converted
2921 **      to UTF-16.</li>
2922 ** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
2923 **      sqlite3_column_text() is called.  The content must be converted
2924 **      to UTF-8.</li>
2925 ** </ul>
2926 **
2927 ** Conversions between UTF-16be and UTF-16le are always done in place and do
2928 ** not invalidate a prior pointer, though of course the content of the buffer
2929 ** that the prior pointer points to will have been modified.  Other kinds
2930 ** of conversion are done in place when it is possible, but sometimes they
2931 ** are not possible and in those cases prior pointers are invalidated.
2932 **
2933 ** The safest and easiest to remember policy is to invoke these routines
2934 ** in one of the following ways:
2935 **
2936 ** <ul>
2937 **  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
2938 **  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
2939 **  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
2940 ** </ul>
2941 **
2942 ** In other words, you should call sqlite3_column_text(),
2943 ** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
2944 ** into the desired format, then invoke sqlite3_column_bytes() or
2945 ** sqlite3_column_bytes16() to find the size of the result.  Do not mix calls
2946 ** to sqlite3_column_text() or sqlite3_column_blob() with calls to
2947 ** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
2948 ** with calls to sqlite3_column_bytes().
2949 **
2950 ** The pointers returned are valid until a type conversion occurs as
2951 ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
2952 ** [sqlite3_finalize()] is called.  The memory space used to hold strings
2953 ** and BLOBs is freed automatically.  Do <b>not</b> pass the pointers returned
2954 ** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
2955 ** [sqlite3_free()].
2956 **
2957 ** If a memory allocation error occurs during the evaluation of any
2958 ** of these routines, a default value is returned.  The default value
2959 ** is either the integer 0, the floating point number 0.0, or a NULL
2960 ** pointer.  Subsequent calls to [sqlite3_errcode()] will return
2961 ** [SQLITE_NOMEM].
2962 **
2963 ** Requirements:
2964 ** [H13803] [H13806] [H13809] [H13812] [H13815] [H13818] [H13821] [H13824]
2965 ** [H13827] [H13830]
2966 */
2967 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
2968 int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
2969 int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
2970 double sqlite3_column_double(sqlite3_stmt*, int iCol);
2971 int sqlite3_column_int(sqlite3_stmt*, int iCol);
2972 sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
2973 const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
2974 const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
2975 int sqlite3_column_type(sqlite3_stmt*, int iCol);
2976 sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
2977
2978 /*
2979 ** CAPI3REF: Destroy A Prepared Statement Object {H13300} <S70300><S30100>
2980 **
2981 ** The sqlite3_finalize() function is called to delete a [prepared statement].
2982 ** If the statement was executed successfully or not executed at all, then
2983 ** SQLITE_OK is returned. If execution of the statement failed then an
2984 ** [error code] or [extended error code] is returned.
2985 **
2986 ** This routine can be called at any point during the execution of the
2987 ** [prepared statement].  If the virtual machine has not
2988 ** completed execution when this routine is called, that is like
2989 ** encountering an error or an [sqlite3_interrupt | interrupt].
2990 ** Incomplete updates may be rolled back and transactions canceled,
2991 ** depending on the circumstances, and the
2992 ** [error code] returned will be [SQLITE_ABORT].
2993 **
2994 ** Requirements:
2995 ** [H11302] [H11304]
2996 */
2997 int sqlite3_finalize(sqlite3_stmt *pStmt);
2998
2999 /*
3000 ** CAPI3REF: Reset A Prepared Statement Object {H13330} <S70300>
3001 **
3002 ** The sqlite3_reset() function is called to reset a [prepared statement]
3003 ** object back to its initial state, ready to be re-executed.
3004 ** Any SQL statement variables that had values bound to them using
3005 ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
3006 ** Use [sqlite3_clear_bindings()] to reset the bindings.
3007 **
3008 ** {H11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S
3009 **          back to the beginning of its program.
3010 **
3011 ** {H11334} If the most recent call to [sqlite3_step(S)] for the
3012 **          [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
3013 **          or if [sqlite3_step(S)] has never before been called on S,
3014 **          then [sqlite3_reset(S)] returns [SQLITE_OK].
3015 **
3016 ** {H11336} If the most recent call to [sqlite3_step(S)] for the
3017 **          [prepared statement] S indicated an error, then
3018 **          [sqlite3_reset(S)] returns an appropriate [error code].
3019 **
3020 ** {H11338} The [sqlite3_reset(S)] interface does not change the values
3021 **          of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
3022 */
3023 int sqlite3_reset(sqlite3_stmt *pStmt);
3024
3025 /*
3026 ** CAPI3REF: Create Or Redefine SQL Functions {H16100} <S20200>
3027 ** KEYWORDS: {function creation routines}
3028 ** KEYWORDS: {application-defined SQL function}
3029 ** KEYWORDS: {application-defined SQL functions}
3030 **
3031 ** These two functions (collectively known as "function creation routines")
3032 ** are used to add SQL functions or aggregates or to redefine the behavior
3033 ** of existing SQL functions or aggregates.  The only difference between the
3034 ** two is that the second parameter, the name of the (scalar) function or
3035 ** aggregate, is encoded in UTF-8 for sqlite3_create_function() and UTF-16
3036 ** for sqlite3_create_function16().
3037 **
3038 ** The first parameter is the [database connection] to which the SQL
3039 ** function is to be added.  If a single program uses more than one database
3040 ** connection internally, then SQL functions must be added individually to
3041 ** each database connection.
3042 **
3043 ** The second parameter is the name of the SQL function to be created or
3044 ** redefined.  The length of the name is limited to 255 bytes, exclusive of
3045 ** the zero-terminator.  Note that the name length limit is in bytes, not
3046 ** characters.  Any attempt to create a function with a longer name
3047 ** will result in [SQLITE_ERROR] being returned.
3048 **
3049 ** The third parameter (nArg)
3050 ** is the number of arguments that the SQL function or
3051 ** aggregate takes. If this parameter is negative, then the SQL function or
3052 ** aggregate may take any number of arguments.
3053 **
3054 ** The fourth parameter, eTextRep, specifies what
3055 ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
3056 ** its parameters.  Any SQL function implementation should be able to work
3057 ** work with UTF-8, UTF-16le, or UTF-16be.  But some implementations may be
3058 ** more efficient with one encoding than another.  It is allowed to
3059 ** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
3060 ** times with the same function but with different values of eTextRep.
3061 ** When multiple implementations of the same function are available, SQLite
3062 ** will pick the one that involves the least amount of data conversion.
3063 ** If there is only a single implementation which does not care what text
3064 ** encoding is used, then the fourth argument should be [SQLITE_ANY].
3065 **
3066 ** The fifth parameter is an arbitrary pointer.  The implementation of the
3067 ** function can gain access to this pointer using [sqlite3_user_data()].
3068 **
3069 ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
3070 ** pointers to C-language functions that implement the SQL function or
3071 ** aggregate. A scalar SQL function requires an implementation of the xFunc
3072 ** callback only, NULL pointers should be passed as the xStep and xFinal
3073 ** parameters. An aggregate SQL function requires an implementation of xStep
3074 ** and xFinal and NULL should be passed for xFunc. To delete an existing
3075 ** SQL function or aggregate, pass NULL for all three function callbacks.
3076 **
3077 ** It is permitted to register multiple implementations of the same
3078 ** functions with the same name but with either differing numbers of
3079 ** arguments or differing preferred text encodings.  SQLite will use
3080 ** the implementation most closely matches the way in which the
3081 ** SQL function is used.  A function implementation with a non-negative
3082 ** nArg parameter is a better match than a function implementation with
3083 ** a negative nArg.  A function where the preferred text encoding
3084 ** matches the database encoding is a better
3085 ** match than a function where the encoding is different.  
3086 ** A function where the encoding difference is between UTF16le and UTF16be
3087 ** is a closer match than a function where the encoding difference is
3088 ** between UTF8 and UTF16.
3089 **
3090 ** Built-in functions may be overloaded by new application-defined functions.
3091 ** The first application-defined function with a given name overrides all
3092 ** built-in functions in the same [database connection] with the same name.
3093 ** Subsequent application-defined functions of the same name only override 
3094 ** prior application-defined functions that are an exact match for the
3095 ** number of parameters and preferred encoding.
3096 **
3097 ** An application-defined function is permitted to call other
3098 ** SQLite interfaces.  However, such calls must not
3099 ** close the database connection nor finalize or reset the prepared
3100 ** statement in which the function is running.
3101 **
3102 ** Requirements:
3103 ** [H16103] [H16106] [H16109] [H16112] [H16118] [H16121] [H16124] [H16127]
3104 ** [H16130] [H16133] [H16136] [H16139] [H16142]
3105 */
3106 int sqlite3_create_function(
3107   sqlite3 *db,
3108   const char *zFunctionName,
3109   int nArg,
3110   int eTextRep,
3111   void *pApp,
3112   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
3113   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
3114   void (*xFinal)(sqlite3_context*)
3115 );
3116 int sqlite3_create_function16(
3117   sqlite3 *db,
3118   const void *zFunctionName,
3119   int nArg,
3120   int eTextRep,
3121   void *pApp,
3122   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
3123   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
3124   void (*xFinal)(sqlite3_context*)
3125 );
3126
3127 /*
3128 ** CAPI3REF: Text Encodings {H10267} <S50200> <H16100>
3129 **
3130 ** These constant define integer codes that represent the various
3131 ** text encodings supported by SQLite.
3132 */
3133 #define SQLITE_UTF8           1
3134 #define SQLITE_UTF16LE        2
3135 #define SQLITE_UTF16BE        3
3136 #define SQLITE_UTF16          4    /* Use native byte order */
3137 #define SQLITE_ANY            5    /* sqlite3_create_function only */
3138 #define SQLITE_UTF16_ALIGNED  8    /* sqlite3_create_collation only */
3139
3140 /*
3141 ** CAPI3REF: Deprecated Functions
3142 ** DEPRECATED
3143 **
3144 ** These functions are [deprecated].  In order to maintain
3145 ** backwards compatibility with older code, these functions continue 
3146 ** to be supported.  However, new applications should avoid
3147 ** the use of these functions.  To help encourage people to avoid
3148 ** using these functions, we are not going to tell you what they do.
3149 */
3150 #ifndef SQLITE_OMIT_DEPRECATED
3151 SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
3152 SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
3153 SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
3154 SQLITE_DEPRECATED int sqlite3_global_recover(void);
3155 SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
3156 SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
3157 #endif
3158
3159 /*
3160 ** CAPI3REF: Obtaining SQL Function Parameter Values {H15100} <S20200>
3161 **
3162 ** The C-language implementation of SQL functions and aggregates uses
3163 ** this set of interface routines to access the parameter values on
3164 ** the function or aggregate.
3165 **
3166 ** The xFunc (for scalar functions) or xStep (for aggregates) parameters
3167 ** to [sqlite3_create_function()] and [sqlite3_create_function16()]
3168 ** define callbacks that implement the SQL functions and aggregates.
3169 ** The 4th parameter to these callbacks is an array of pointers to
3170 ** [protected sqlite3_value] objects.  There is one [sqlite3_value] object for
3171 ** each parameter to the SQL function.  These routines are used to
3172 ** extract values from the [sqlite3_value] objects.
3173 **
3174 ** These routines work only with [protected sqlite3_value] objects.
3175 ** Any attempt to use these routines on an [unprotected sqlite3_value]
3176 ** object results in undefined behavior.
3177 **
3178 ** These routines work just like the corresponding [column access functions]
3179 ** except that  these routines take a single [protected sqlite3_value] object
3180 ** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
3181 **
3182 ** The sqlite3_value_text16() interface extracts a UTF-16 string
3183 ** in the native byte-order of the host machine.  The
3184 ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
3185 ** extract UTF-16 strings as big-endian and little-endian respectively.
3186 **
3187 ** The sqlite3_value_numeric_type() interface attempts to apply
3188 ** numeric affinity to the value.  This means that an attempt is
3189 ** made to convert the value to an integer or floating point.  If
3190 ** such a conversion is possible without loss of information (in other
3191 ** words, if the value is a string that looks like a number)
3192 ** then the conversion is performed.  Otherwise no conversion occurs.
3193 ** The [SQLITE_INTEGER | datatype] after conversion is returned.
3194 **
3195 ** Please pay particular attention to the fact that the pointer returned
3196 ** from [sqlite3_value_blob()], [sqlite3_value_text()], or
3197 ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
3198 ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
3199 ** or [sqlite3_value_text16()].
3200 **
3201 ** These routines must be called from the same thread as
3202 ** the SQL function that supplied the [sqlite3_value*] parameters.
3203 **
3204 ** Requirements:
3205 ** [H15103] [H15106] [H15109] [H15112] [H15115] [H15118] [H15121] [H15124]
3206 ** [H15127] [H15130] [H15133] [H15136]
3207 */
3208 const void *sqlite3_value_blob(sqlite3_value*);
3209 int sqlite3_value_bytes(sqlite3_value*);
3210 int sqlite3_value_bytes16(sqlite3_value*);
3211 double sqlite3_value_double(sqlite3_value*);
3212 int sqlite3_value_int(sqlite3_value*);
3213 sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
3214 const unsigned char *sqlite3_value_text(sqlite3_value*);
3215 const void *sqlite3_value_text16(sqlite3_value*);
3216 const void *sqlite3_value_text16le(sqlite3_value*);
3217 const void *sqlite3_value_text16be(sqlite3_value*);
3218 int sqlite3_value_type(sqlite3_value*);
3219 int sqlite3_value_numeric_type(sqlite3_value*);
3220
3221 /*
3222 ** CAPI3REF: Obtain Aggregate Function Context {H16210} <S20200>
3223 **
3224 ** The implementation of aggregate SQL functions use this routine to allocate
3225 ** a structure for storing their state.
3226 **
3227 ** The first time the sqlite3_aggregate_context() routine is called for a
3228 ** particular aggregate, SQLite allocates nBytes of memory, zeroes out that
3229 ** memory, and returns a pointer to it. On second and subsequent calls to
3230 ** sqlite3_aggregate_context() for the same aggregate function index,
3231 ** the same buffer is returned. The implementation of the aggregate can use
3232 ** the returned buffer to accumulate data.
3233 **
3234 ** SQLite automatically frees the allocated buffer when the aggregate
3235 ** query concludes.
3236 **
3237 ** The first parameter should be a copy of the
3238 ** [sqlite3_context | SQL function context] that is the first parameter
3239 ** to the callback routine that implements the aggregate function.
3240 **
3241 ** This routine must be called from the same thread in which
3242 ** the aggregate SQL function is running.
3243 **
3244 ** Requirements:
3245 ** [H16211] [H16213] [H16215] [H16217]
3246 */
3247 void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
3248
3249 /*
3250 ** CAPI3REF: User Data For Functions {H16240} <S20200>
3251 **
3252 ** The sqlite3_user_data() interface returns a copy of
3253 ** the pointer that was the pUserData parameter (the 5th parameter)
3254 ** of the [sqlite3_create_function()]
3255 ** and [sqlite3_create_function16()] routines that originally
3256 ** registered the application defined function. {END}
3257 **
3258 ** This routine must be called from the same thread in which
3259 ** the application-defined function is running.
3260 **
3261 ** Requirements:
3262 ** [H16243]
3263 */
3264 void *sqlite3_user_data(sqlite3_context*);
3265
3266 /*
3267 ** CAPI3REF: Database Connection For Functions {H16250} <S60600><S20200>
3268 **
3269 ** The sqlite3_context_db_handle() interface returns a copy of
3270 ** the pointer to the [database connection] (the 1st parameter)
3271 ** of the [sqlite3_create_function()]
3272 ** and [sqlite3_create_function16()] routines that originally
3273 ** registered the application defined function.
3274 **
3275 ** Requirements:
3276 ** [H16253]
3277 */
3278 sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
3279
3280 /*
3281 ** CAPI3REF: Function Auxiliary Data {H16270} <S20200>
3282 **
3283 ** The following two functions may be used by scalar SQL functions to
3284 ** associate metadata with argument values. If the same value is passed to
3285 ** multiple invocations of the same SQL function during query execution, under
3286 ** some circumstances the associated metadata may be preserved. This may
3287 ** be used, for example, to add a regular-expression matching scalar
3288 ** function. The compiled version of the regular expression is stored as
3289 ** metadata associated with the SQL value passed as the regular expression
3290 ** pattern.  The compiled regular expression can be reused on multiple
3291 ** invocations of the same function so that the original pattern string
3292 ** does not need to be recompiled on each invocation.
3293 **
3294 ** The sqlite3_get_auxdata() interface returns a pointer to the metadata
3295 ** associated by the sqlite3_set_auxdata() function with the Nth argument
3296 ** value to the application-defined function. If no metadata has been ever
3297 ** been set for the Nth argument of the function, or if the corresponding
3298 ** function parameter has changed since the meta-data was set,
3299 ** then sqlite3_get_auxdata() returns a NULL pointer.
3300 **
3301 ** The sqlite3_set_auxdata() interface saves the metadata
3302 ** pointed to by its 3rd parameter as the metadata for the N-th
3303 ** argument of the application-defined function.  Subsequent
3304 ** calls to sqlite3_get_auxdata() might return this data, if it has
3305 ** not been destroyed.
3306 ** If it is not NULL, SQLite will invoke the destructor
3307 ** function given by the 4th parameter to sqlite3_set_auxdata() on
3308 ** the metadata when the corresponding function parameter changes
3309 ** or when the SQL statement completes, whichever comes first.
3310 **
3311 ** SQLite is free to call the destructor and drop metadata on any
3312 ** parameter of any function at any time.  The only guarantee is that
3313 ** the destructor will be called before the metadata is dropped.
3314 **
3315 ** In practice, metadata is preserved between function calls for
3316 ** expressions that are constant at compile time. This includes literal
3317 ** values and SQL variables.
3318 **
3319 ** These routines must be called from the same thread in which
3320 ** the SQL function is running.
3321 **
3322 ** Requirements:
3323 ** [H16272] [H16274] [H16276] [H16277] [H16278] [H16279]
3324 */
3325 void *sqlite3_get_auxdata(sqlite3_context*, int N);
3326 void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
3327
3328
3329 /*
3330 ** CAPI3REF: Constants Defining Special Destructor Behavior {H10280} <S30100>
3331 **
3332 ** These are special values for the destructor that is passed in as the
3333 ** final argument to routines like [sqlite3_result_blob()].  If the destructor
3334 ** argument is SQLITE_STATIC, it means that the content pointer is constant
3335 ** and will never change.  It does not need to be destroyed.  The
3336 ** SQLITE_TRANSIENT value means that the content will likely change in
3337 ** the near future and that SQLite should make its own private copy of
3338 ** the content before returning.
3339 **
3340 ** The typedef is necessary to work around problems in certain
3341 ** C++ compilers.  See ticket #2191.
3342 */
3343 typedef void (*sqlite3_destructor_type)(void*);
3344 #define SQLITE_STATIC      ((sqlite3_destructor_type)0)
3345 #define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)
3346
3347 /*
3348 ** CAPI3REF: Setting The Result Of An SQL Function {H16400} <S20200>
3349 **
3350 ** These routines are used by the xFunc or xFinal callbacks that
3351 ** implement SQL functions and aggregates.  See
3352 ** [sqlite3_create_function()] and [sqlite3_create_function16()]
3353 ** for additional information.
3354 **
3355 ** These functions work very much like the [parameter binding] family of
3356 ** functions used to bind values to host parameters in prepared statements.
3357 ** Refer to the [SQL parameter] documentation for additional information.
3358 **
3359 ** The sqlite3_result_blob() interface sets the result from
3360 ** an application-defined function to be the BLOB whose content is pointed
3361 ** to by the second parameter and which is N bytes long where N is the
3362 ** third parameter.
3363 **
3364 ** The sqlite3_result_zeroblob() interfaces set the result of
3365 ** the application-defined function to be a BLOB containing all zero
3366 ** bytes and N bytes in size, where N is the value of the 2nd parameter.
3367 **
3368 ** The sqlite3_result_double() interface sets the result from
3369 ** an application-defined function to be a floating point value specified
3370 ** by its 2nd argument.
3371 **
3372 ** The sqlite3_result_error() and sqlite3_result_error16() functions
3373 ** cause the implemented SQL function to throw an exception.
3374 ** SQLite uses the string pointed to by the
3375 ** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
3376 ** as the text of an error message.  SQLite interprets the error
3377 ** message string from sqlite3_result_error() as UTF-8. SQLite
3378 ** interprets the string from sqlite3_result_error16() as UTF-16 in native
3379 ** byte order.  If the third parameter to sqlite3_result_error()
3380 ** or sqlite3_result_error16() is negative then SQLite takes as the error
3381 ** message all text up through the first zero character.
3382 ** If the third parameter to sqlite3_result_error() or
3383 ** sqlite3_result_error16() is non-negative then SQLite takes that many
3384 ** bytes (not characters) from the 2nd parameter as the error message.
3385 ** The sqlite3_result_error() and sqlite3_result_error16()
3386 ** routines make a private copy of the error message text before
3387 ** they return.  Hence, the calling function can deallocate or
3388 ** modify the text after they return without harm.
3389 ** The sqlite3_result_error_code() function changes the error code
3390 ** returned by SQLite as a result of an error in a function.  By default,
3391 ** the error code is SQLITE_ERROR.  A subsequent call to sqlite3_result_error()
3392 ** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
3393 **
3394 ** The sqlite3_result_toobig() interface causes SQLite to throw an error
3395 ** indicating that a string or BLOB is to long to represent.
3396 **
3397 ** The sqlite3_result_nomem() interface causes SQLite to throw an error
3398 ** indicating that a memory allocation failed.
3399 **
3400 ** The sqlite3_result_int() interface sets the return value
3401 ** of the application-defined function to be the 32-bit signed integer
3402 ** value given in the 2nd argument.
3403 ** The sqlite3_result_int64() interface sets the return value
3404 ** of the application-defined function to be the 64-bit signed integer