/*** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors**** This routine identifies a callback function that might be invoked** whenever an attempt is made to open a database table ** that another thread or process has locked.** If the busy callback is NULL, then [SQLITE_BUSY]** (or sometimes [SQLITE_IOERR_BLOCKED])** is returned immediately upon encountering the lock.** If the busy callback is not NULL, then the** callback will be invoked with two arguments.  The** first argument to the handler is a copy of the void* pointer which** is the third argument to this routine.  The second argument to** the handler is the number of times that the busy handler has** been invoked for this locking event. If the** busy callback returns 0, then no additional attempts are made to** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.** If the callback returns non-zero, then another attempt is made to open the** database for reading and the cycle repeats.**** The presence of a busy handler does not guarantee that** it will be invoked when there is lock contention.** If SQLite determines that invoking the busy handler could result in** a deadlock, it will return [SQLITE_BUSY] instead.** Consider a scenario where one process is holding a read lock that** it is trying to promote to a reserved lock and** a second process is holding a reserved lock that it is trying** to promote to an exclusive lock.  The first process cannot proceed** because it is blocked by the second and the second process cannot** proceed because it is blocked by the first.  If both processes** invoke the busy handlers, neither will make any progress.  Therefore,** SQLite returns [SQLITE_BUSY] for the first process, hoping that this** will induce the first process to release its read lock and allow** the second process to proceed.**** The default busy callback is NULL.**** The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED] when** SQLite is in the middle of a large transaction where all the** changes will not fit into the in-memory cache.  SQLite will** already hold a RESERVED lock on the database file, but it needs** to promote this lock to EXCLUSIVE so that it can spill cache** pages into the database file without harm to concurrent** readers.  If it is unable to promote the lock, then the in-memory** cache will be left in an inconsistent state and so the error** code is promoted from the relatively benign [SQLITE_BUSY] to** the more severe [SQLITE_IOERR_BLOCKED].  This error code promotion** forces an automatic rollback of the changes. See the** <a href="http://www.sqlite.org/cvstrac/wiki?p=CorruptionFollowingBusyError">** CorruptionFollowingBusyError</a> wiki page for a discussion of why** this is important.**	** Sqlite is re-entrant, so the busy handler may start a new query. ** (It is not clear why anyone would every want to do this, but it** is allowed, in theory.)  But the busy handler may not close the** database.  Closing the database from a busy handler will delete ** data structures out from under the executing query and will ** probably result in a segmentation fault or other runtime error.**** There can only be a single busy handler defined for each database** connection.  Setting a new busy handler clears any previous one.** Note that calling [sqlite3_busy_timeout()] will also set or clear** the busy handler.**** When operating in [sqlite3_enable_shared_cache | shared cache mode],** only a single busy handler can be defined for each database file.** So if two database connections share a single cache, then changing** the busy handler on one connection will also change the busy** handler in the other connection.  The busy handler is invoked** in the thread that was running when the SQLITE_BUSY was hit.*/int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);/*** CAPI3REF: Set A Busy Timeout**** This routine sets a busy handler that sleeps for a while when a** table is locked.  The handler will sleep multiple times until ** at least "ms" milliseconds of sleeping have been done.  After** "ms" milliseconds of sleeping, the handler returns 0 which** causes [sqlite3_step()] to return [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].**** Calling this routine with an argument less than or equal to zero** turns off all busy handlers.**** There can only be a single busy handler for a particular database** connection.  If another busy handler was defined  ** (using [sqlite3_busy_handler()]) prior to calling** this routine, that other busy handler is cleared.*/int sqlite3_busy_timeout(sqlite3*, int ms);/*** CAPI3REF: Convenience Routines For Running Queries**** This next routine is a convenience wrapper around [sqlite3_exec()].** Instead of invoking a user-supplied callback for each row of the** result, this routine remembers each row of the result in memory** obtained from [sqlite3_malloc()], then returns all of the result after the** query has finished. **** As an example, suppose the query result where this table:**** <blockquote><pre>**        Name        | Age**        -----------------------**        Alice       | 43**        Bob         | 28**        Cindy       | 21** </pre></blockquote>**** If the 3rd argument were &azResult then after the function returns** azResult will contain the following data:**** <blockquote><pre>**        azResult&#91;0] = "Name";**        azResult&#91;1] = "Age";**        azResult&#91;2] = "Alice";**        azResult&#91;3] = "43";**        azResult&#91;4] = "Bob";**        azResult&#91;5] = "28";**        azResult&#91;6] = "Cindy";**        azResult&#91;7] = "21";** </pre></blockquote>**** Notice that there is an extra row of data containing the column** headers.  But the *nrow return value is still 3.  *ncolumn is** set to 2.  In general, the number of values inserted into azResult** will be ((*nrow) + 1)*(*ncolumn).**** After the calling function has finished using the result, it should ** pass the result data pointer to sqlite3_free_table() in order to ** release the memory that was malloc-ed.  Because of the way the ** [sqlite3_malloc()] happens, the calling function must not try to call ** [sqlite3_free()] directly.  Only [sqlite3_free_table()] is able to release ** the memory properly and safely.**** The return value of this routine is the same as from [sqlite3_exec()].*/int sqlite3_get_table(  sqlite3*,              /* An open database */  const char *sql,       /* SQL to be executed */  char ***resultp,       /* Result written to a char *[]  that this points to */  int *nrow,             /* Number of result rows written here */  int *ncolumn,          /* Number of result columns written here */  char **errmsg          /* Error msg written here */);void sqlite3_free_table(char **result);/*** CAPI3REF: Formatted String Printing Functions**** These routines are workalikes of the "printf()" family of functions** from the standard C library.**** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their** results into memory obtained from [sqlite3_malloc()].** The strings returned by these two routines should be** released by [sqlite3_free()].  Both routines return a** NULL pointer if [sqlite3_malloc()] is unable to allocate enough** memory to hold the resulting string.**** In sqlite3_snprintf() routine is similar to "snprintf()" from** the standard C library.  The result is written into the** buffer supplied as the second parameter whose size is given by** the first parameter.  Note that the order of the** first two parameters is reversed from snprintf().  This is an** historical accident that cannot be fixed without breaking** backwards compatibility.  Note also that sqlite3_snprintf()** returns a pointer to its buffer instead of the number of** characters actually written into the buffer.  We admit that** the number of characters written would be a more useful return** value but we cannot change the implementation of sqlite3_snprintf()** now without breaking compatibility.**** As long as the buffer size is greater than zero, sqlite3_snprintf()** guarantees that the buffer is always zero-terminated.  The first** parameter "n" is the total size of the buffer, including space for** the zero terminator.  So the longest string that can be completely** written will be n-1 characters.**** These routines all implement some additional formatting** options that are useful for constructing SQL statements.** All of the usual printf formatting options apply.  In addition, there** is are "%q", "%Q", and "%z" options.**** The %q option works like %s in that it substitutes a null-terminated** string from the argument list.  But %q also doubles every '\'' character.** %q is designed for use inside a string literal.  By doubling each '\''** character it escapes that character and allows it to be inserted into** the string.**** For example, so some string variable contains text as follows:**** <blockquote><pre>**  char *zText = "It's a happy day!";** </pre></blockquote>**** One can use this text in an SQL statement as follows:**** <blockquote><pre>**  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);**  sqlite3_exec(db, zSQL, 0, 0, 0);**  sqlite3_free(zSQL);** </pre></blockquote>**** Because the %q format string is used, the '\'' character in zText** is escaped and the SQL generated is as follows:**** <blockquote><pre>**  INSERT INTO table1 VALUES('It''s a happy day!')** </pre></blockquote>**** This is correct.  Had we used %s instead of %q, the generated SQL** would have looked like this:**** <blockquote><pre>**  INSERT INTO table1 VALUES('It's a happy day!');** </pre></blockquote>**** This second example is an SQL syntax error.  As a general rule you** should always use %q instead of %s when inserting text into a string ** literal.**** The %Q option works like %q except it also adds single quotes around** the outside of the total string.  Or if the parameter in the argument** list is a NULL pointer, %Q substitutes the text "NULL" (without single** quotes) in place of the %Q option.  So, for example, one could say:**** <blockquote><pre>**  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);**  sqlite3_exec(db, zSQL, 0, 0, 0);**  sqlite3_free(zSQL);** </pre></blockquote>**** The code above will render a correct SQL statement in the zSQL** variable even if the zText variable is a NULL pointer.**** The "%z" formatting option works exactly like "%s" with the** addition that after the string has been read and copied into** the result, [sqlite3_free()] is called on the input string.*/char *sqlite3_mprintf(const char*,...);char *sqlite3_vmprintf(const char*, va_list);char *sqlite3_snprintf(int,char*,const char*, ...);/*** CAPI3REF: Memory Allocation Subsystem**** The SQLite core uses these three routines for all of its own** internal memory allocation needs. (See the exception below.)**** The default implementation** of the memory allocation subsystem uses the malloc(), realloc()** and free() provided by the standard C library.  However, if ** SQLite is compiled with the following C preprocessor macro**** <blockquote> SQLITE_MEMORY_SIZE=<i>NNN</i> </blockquote>**** where <i>NNN</i> is an integer, then SQLite create a static** array of at least <i>NNN</i> bytes in size and use that array** for all of its dynamic memory allocation needs.**** In SQLite version 3.5.0 and 3.5.1, it was possible to define** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in** implementation of these routines to be omitted.  That capability** is no longer provided.  Only built-in memory allocators can be** used.**** <b>Exception:</b> The windows OS interface layer calls** the system malloc() and free() directly when converting** filenames between the UTF-8 encoding used by SQLite** and whatever filename encoding is used by the particular windows** installation.  Memory allocation errors are detected, but** they are reported back as [SQLITE_CANTOPEN] or** [SQLITE_IOERR] rather than [SQLITE_NOMEM].*/void *sqlite3_malloc(int);void *sqlite3_realloc(void*, int);void sqlite3_free(void*);/*** CAPI3REF: Memory Allocator Statistics**** In addition to the basic three allocation routines ** [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()],** the memory allocation subsystem included with the SQLite** sources provides the interfaces shown below.**** The first of these two routines returns the amount of memory ** currently outstanding (malloced but not freed).  The second** returns the largest instantaneous amount of outstanding** memory.  The highwater mark is reset if the argument is** true.