**          lock clears or until the cumulative sleep time reported back**          by xSleep() exceeds N milliseconds.*/int sqlite3_busy_timeout(sqlite3*, int ms);/*** CAPI3REF: Convenience Routines For Running Queries {F12370}**** Definition: A <b>result table</b> is memory data structure created by the** [sqlite3_get_table()] interface.  A result table records the** complete query results from one or more queries.**** The table conceptually has a number of rows and columns.  But** these numbers are not part of the result table itself.  These** numbers are obtained separately.  Let N be the number of rows** and M be the number of columns.**** A result table is an array of pointers to zero-terminated** UTF-8 strings.  There are (N+1)*M elements in the array.  ** The first M pointers point to zero-terminated strings that ** contain the names of the columns.** The remaining entries all point to query results.  NULL** values are give a NULL pointer.  All other values are in** their UTF-8 zero-terminated string representation as returned by** [sqlite3_column_text()].**** A result table might consists of one or more memory allocations.** It is not safe to pass a result table directly to [sqlite3_free()].** A result table should be deallocated using [sqlite3_free_table()].**** As an example of the result table format, suppose a query result** is as follows:**** <blockquote><pre>**        Name        | Age**        -----------------------**        Alice       | 43**        Bob         | 28**        Cindy       | 21** </pre></blockquote>**** There are two column (M==2) and three rows (N==3).  Thus the** result table has 8 entries.  Suppose the result table is stored** in an array names azResult.  Then azResult holds this content:**** <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>**** The sqlite3_get_table() function evaluates one or more** semicolon-separated SQL statements in the zero-terminated UTF-8** string of its 2nd parameter.  It returns a result table to the** pointer given in its 3rd parameter.**** After the calling function has finished using the result, it should ** pass the pointer to the result table to sqlite3_free_table() in order to ** release the memory that was malloc-ed.  Because of the way the ** [sqlite3_malloc()] happens within sqlite3_get_table(), 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 sqlite3_get_table() interface is implemented as a wrapper around** [sqlite3_exec()].  The sqlite3_get_table() routine does not have access** to any internal data structures of SQLite.  It uses only the public** interface defined here.  As a consequence, errors that occur in the** wrapper layer outside of the internal [sqlite3_exec()] call are not** reflected in subsequent calls to [sqlite3_errcode()] or** [sqlite3_errmsg()].**** INVARIANTS:**** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then**          it frees the result table under construction, aborts the**          query in process, skips any subsequent queries, sets the**          *resultp output pointer to NULL and returns [SQLITE_NOMEM].**** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL**          then [sqlite3_get_table()] write the number of columns in the**          result set of the query into *ncolumn if the query is**          successful (if the function returns SQLITE_OK).**** {F12374} If the nrow parameter to [sqlite3_get_table()] is not NULL**          then [sqlite3_get_table()] write the number of rows in the**          result set of the query into *nrow if the query is**          successful (if the function returns SQLITE_OK).**** {F12376} The [sqlite3_get_table()] function sets its *ncolumn value**          to the number of columns in the result set of the query in the**          sql parameter, or to zero if the query in sql has an empty**          result set.*/int sqlite3_get_table(  sqlite3*,             /* An open database */  const char *sql,      /* SQL to be evaluated */  char ***pResult,      /* Results of the query */  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 {F17400}**** 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. {END}  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. {END}**** INVARIANTS:**** {F17403}  The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces**           return either pointers to zero-terminated UTF-8 strings held in**           memory obtained from [sqlite3_malloc()] or NULL pointers if**           a call to [sqlite3_malloc()] fails.**** {F17406}  The [sqlite3_snprintf()] interface writes a zero-terminated**           UTF-8 string into the buffer pointed to by the second parameter**           provided that the first parameter is greater than zero.**** {F17407}  The [sqlite3_snprintf()] interface does not writes slots of**           its output buffer (the second parameter) outside the range**           of 0 through N-1 (where N is the first parameter)**           regardless of the length of the string**           requested by the format specification.**   */char *sqlite3_mprintf(const char*,...);char *sqlite3_vmprintf(const char*, va_list);char *sqlite3_snprintf(int,char*,const char*, ...);/*** CAPI3REF: Memory Allocation Subsystem {F17300}**** The SQLite core  uses these three routines for all of its own** internal memory allocation needs. "Core" in the previous sentence** does not include operating-system specific VFS implementation.  The** windows VFS uses native malloc and free for some operations.**** The sqlite3_malloc() routine returns a pointer to a block** of memory at least N bytes in length, where N is the parameter.** If sqlite3_malloc() is unable to obtain sufficient free** memory, it returns a NULL pointer.  If the parameter N to** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns** a NULL pointer.**** Calling sqlite3_free() with a pointer previously returned** by sqlite3_malloc() or sqlite3_realloc() releases that memory so** that it might be reused.  The sqlite3_free() routine is** a no-op if is called with a NULL pointer.  Passing a NULL pointer** to sqlite3_free() is harmless.  After being freed, memory** should neither be read nor written.  Even reading previously freed** memory might result in a segmentation fault or other severe error.** Memory corruption, a segmentation fault, or other severe error** might result if sqlite3_free() is called with a non-NULL pointer that** was not obtained from sqlite3_malloc() or sqlite3_free().**** The sqlite3_realloc() interface attempts to resize a** prior memory allocation to be at least N bytes, where N is the** second parameter.  The memory allocation to be resized is the first** parameter.  If the first parameter to sqlite3_realloc()** is a NULL pointer then its behavior is identical to calling** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().** If the second parameter to sqlite3_realloc() is zero or** negative then the behavior is exactly the same as calling** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().** Sqlite3_realloc() returns a pointer to a memory allocation** of at least N bytes in size or NULL if sufficient memory is unavailable.** If M is the size of the prior allocation, then min(N,M) bytes** of the prior allocation are copied into the beginning of buffer returned** by sqlite3_realloc() and the prior allocation is freed.** If sqlite3_realloc() returns NULL, then the prior allocation** is not freed.**** The memory returned by sqlite3_malloc() and sqlite3_realloc()** is always aligned to at least an 8 byte boundary. {END}**** The default implementation** of the memory allocation subsystem uses the malloc(), realloc()** and free() provided by the standard C library. {F17382} 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. {END}  Additional** memory allocator options may be added in future releases.**** 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.**** 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].**** INVARIANTS:**** {F17303}  The [sqlite3_malloc(N)] interface returns either a pointer to **           newly checked-out block of at least N bytes of memory**           that is 8-byte aligned, **           or it returns NULL if it is unable to ful