capi3ref.html

sqlite的帮助文档

<dd>This option specifies a static memory buffer that SQLite will use
for all of its dynamic memory allocation needs beyond those provided
for by <a href="#SQLITE_CONFIG_GETMALLOC">SQLITE_CONFIG_SCRATCH</a> and <a href="#SQLITE_CONFIG_GETMALLOC">SQLITE_CONFIG_PAGECACHE</a>.
There are three arguments: A pointer to the memory, the number of
bytes in the memory buffer, and the minimum allocation size.  If
the first pointer (the memory pointer) is NULL, then SQLite reverts
to using its default memory allocator (the system malloc() implementation),
undoing any prior invocation of <a href="#SQLITE_CONFIG_GETMALLOC">SQLITE_CONFIG_MALLOC</a>.  If the
memory pointer is not NULL and either <a href="compile.html#enable_memsys3">SQLITE_ENABLE_MEMSYS3</a> or
<a href="compile.html#enable_memsys5">SQLITE_ENABLE_MEMSYS5</a> are defined, then the alternative memory
allocator is engaged to handle all of SQLites memory allocation needs.</dd></p>

<p><dt>SQLITE_CONFIG_MUTEX</dt>
<dd>This option takes a single argument which is a pointer to an
instance of the <a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a> structure.  The argument specifies
alternative low-level mutex routines to be used in place
the mutex routines built into SQLite.</dd></p>

<p><dt>SQLITE_CONFIG_GETMUTEX</dt>
<dd>This option takes a single argument which is a pointer to an
instance of the <a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a> structure.  The
<a href="#sqlite3_mutex_methods">sqlite3_mutex_methods</a>
structure is filled with the currently defined mutex routines.
This option can be used to overload the default mutex allocation
routines with a wrapper used to track mutex usage for performance
profiling or testing, for example.</dd></p>

<p><dt>SQLITE_CONFIG_LOOKASIDE</dt>
<dd>This option takes two arguments that determine the default
memory allcation lookaside optimization.  The first argument is the
size of each lookaside buffer slot and the second is the number of
slots allocated to each database connection.</dd></p>

<p></dl>
</p><hr><a name="SQLITE_DBCONFIG_LOOKASIDE"></a>
<h2>Configuration Options</h2><blockquote><pre>#define SQLITE_DBCONFIG_LOOKASIDE    1001  /* void* int int */
</pre></blockquote><p><b>Important:</b> This interface is <a href="capi3ref.html">experimental</a> and is subject to change without notice.</p><p>
These constants are the available integer configuration options that
can be passed as the second argument to the <a href="#sqlite3_db_config">sqlite3_db_config()</a> interface.</p>

<p>New configuration options may be added in future releases of SQLite.
Existing configuration options might be discontinued.  Applications
should check the return code from <a href="#sqlite3_db_config">sqlite3_db_config()</a> to make sure that
the call worked.  The <a href="#sqlite3_db_config">sqlite3_db_config()</a> interface will return a
non-zero <a href="#SQLITE_ABORT">error code</a> if a discontinued or unsupported configuration option
is invoked.</p>

<p><dl>
<dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
<dd>This option takes three additional arguments that determine the
<a href="malloc.html#lookaside">lookaside memory allocator</a> configuration for the <a href="#sqlite3">database connection</a>.
The first argument (the third parameter to <a href="#sqlite3_db_config">sqlite3_db_config()</a> is a
pointer to a memory buffer to use for lookaside memory.  The first
argument may be NULL in which case SQLite will allocate the lookaside
buffer itself using <a href="#sqlite3_free">sqlite3_malloc()</a>.  The second argument is the
size of each lookaside buffer slot and the third argument is the number of
slots.  The size of the buffer in the first argument must be greater than
or equal to the product of the second and third arguments.</dd></p>

<p></dl>
</p><hr><a name="SQLITE_ABORT"></a>
<h2>Result Codes</h2><blockquote><pre>#define SQLITE_OK           0   /* Successful result */
/* beginning-of-error-codes */
#define SQLITE_ERROR        1   /* SQL error or missing database */
#define SQLITE_INTERNAL     2   /* Internal logic error in SQLite */
#define SQLITE_PERM         3   /* Access permission denied */
#define SQLITE_ABORT        4   /* Callback routine requested an abort */
#define SQLITE_BUSY         5   /* The database file is locked */
#define SQLITE_LOCKED       6   /* A table in the database is locked */
#define SQLITE_NOMEM        7   /* A malloc() failed */
#define SQLITE_READONLY     8   /* Attempt to write a readonly database */
#define SQLITE_INTERRUPT    9   /* Operation terminated by sqlite3_interrupt()*/
#define SQLITE_IOERR       10   /* Some kind of disk I/O error occurred */
#define SQLITE_CORRUPT     11   /* The database disk image is malformed */
#define SQLITE_NOTFOUND    12   /* NOT USED. Table or record not found */
#define SQLITE_FULL        13   /* Insertion failed because database is full */
#define SQLITE_CANTOPEN    14   /* Unable to open the database file */
#define SQLITE_PROTOCOL    15   /* NOT USED. Database lock protocol error */
#define SQLITE_EMPTY       16   /* Database is empty */
#define SQLITE_SCHEMA      17   /* The database schema changed */
#define SQLITE_TOOBIG      18   /* String or BLOB exceeds size limit */
#define SQLITE_CONSTRAINT  19   /* Abort due to constraint violation */
#define SQLITE_MISMATCH    20   /* Data type mismatch */
#define SQLITE_MISUSE      21   /* Library used incorrectly */
#define SQLITE_NOLFS       22   /* Uses OS features not supported on host */
#define SQLITE_AUTH        23   /* Authorization denied */
#define SQLITE_FORMAT      24   /* Auxiliary database format error */
#define SQLITE_RANGE       25   /* 2nd parameter to sqlite3_bind out of range */
#define SQLITE_NOTADB      26   /* File opened that is not a database file */
#define SQLITE_ROW         100  /* sqlite3_step() has another row ready */
#define SQLITE_DONE        101  /* sqlite3_step() has finished executing */
/* end-of-error-codes */
</pre></blockquote><p>
Many SQLite functions return an integer result code from the set shown
here in order to indicates success or failure.</p>

<p>New error codes may be added in future versions of SQLite.</p>

<p>See also: <a href="#SQLITE_IOERR_ACCESS">extended result codes</a>
</p><hr><a name="SQLITE_IOERR_ACCESS"></a>
<h2>Extended Result Codes</h2><blockquote><pre>#define SQLITE_IOERR_READ              (SQLITE_IOERR | (1&lt;&lt;8))
#define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2&lt;&lt;8))
#define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3&lt;&lt;8))
#define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4&lt;&lt;8))
#define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5&lt;&lt;8))
#define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6&lt;&lt;8))
#define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7&lt;&lt;8))
#define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8&lt;&lt;8))
#define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9&lt;&lt;8))
#define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10&lt;&lt;8))
#define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11&lt;&lt;8))
#define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12&lt;&lt;8))
#define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13&lt;&lt;8))
#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14&lt;&lt;8))
#define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15&lt;&lt;8))
</pre></blockquote><p>
In its default configuration, SQLite API routines return one of 26 integer
<a href="#SQLITE_ABORT">result codes</a>.  However, experience has shown that many of
these result codes are too coarse-grained.  They do not provide as
much information about problems as programmers might like.  In an effort to
address this, newer versions of SQLite (version 3.3.8 and later) include
support for additional result codes that provide more detailed information
about errors. The extended result codes are enabled or disabled
on a per database connection basis using the
<a href="#sqlite3_extended_result_codes">sqlite3_extended_result_codes()</a> API.</p>

<p>Some of the available extended result codes are listed here.
One may expect the number of extended result codes will be expand
over time.  Software that uses extended result codes should expect
to see new result codes in future releases of SQLite.</p>

<p>The SQLITE_OK result code will never be extended.  It will always
be exactly zero.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">H10223</td> 
<td valign="top">
The symbolic name for an extended result code shall contains
a related primary result code as a prefix.</td></tr>
<tr><td valign="top">H10224</td> 
<td valign="top">
Primary result code names shall contain a single "_" character.</td></tr>
<tr><td valign="top">H10225</td> 
<td valign="top">
Extended result code names shall contain two or more "_" characters.</td></tr>
<tr><td valign="top">H10226</td> 
<td valign="top">
The numeric value of an extended result code shall contain the