capi3ref.html

sqlite3源码,适合作为嵌入式（embedded）

<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_SAFE_APPEND</a>
<li> <a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_SEQUENTIAL</a>
</ul></p>

<p>The SQLITE_IOCAP_ATOMIC property means that all writes of
any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values
mean that writes of blocks that are nnn bytes in size and
are aligned to an address which is an integer multiple of
nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means
that when data is appended to a file, the data is appended
first then the size of the file is extended, never the other
way around.  The SQLITE_IOCAP_SEQUENTIAL property means that
information is written to disk in the same order as calls
to xWrite().</p>

<p>If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
in the unread portions of the buffer with zeros.  A VFS that
fails to zero-fill short reads might seem to work.  However,
failure to zero-fill short reads will eventually lead to
database corruption.
</p><hr><a name="sqlite3_mem_methods"></a>
<h2>Memory Allocation Routines</h2><blockquote><pre>typedef struct sqlite3_mem_methods sqlite3_mem_methods;
struct sqlite3_mem_methods {
  void *(*xMalloc)(int);         /* Memory allocation function */
  void (*xFree)(void*);          /* Free a prior allocation */
  void *(*xRealloc)(void*,int);  /* Resize an allocation */
  int (*xSize)(void*);           /* Return the size of an allocation */
  int (*xRoundup)(int);          /* Round up request size to allocation size */
  int (*xInit)(void*);           /* Initialize the memory allocator */
  void (*xShutdown)(void*);      /* Deinitialize the memory allocator */
  void *pAppData;                /* Argument to xInit() and xShutdown() */
};
</pre></blockquote><p><b>Important:</b> This interface is <a href="capi3ref.html">experimental</a> and is subject to change without notice.</p><p>
An instance of this object defines the interface between SQLite
and low-level memory allocation routines.</p>

<p>This object is used in only one place in the SQLite interface.
A pointer to an instance of this object is the argument to
<a href="#sqlite3_config">sqlite3_config()</a> when the configuration option is
<a href="#SQLITE_CONFIG_GETMALLOC">SQLITE_CONFIG_MALLOC</a>.  By creating an instance of this object
and passing it to <a href="#sqlite3_config">sqlite3_config()</a> during configuration, an
application can specify an alternative memory allocation subsystem
for SQLite to use for all of its dynamic memory needs.</p>

<p>Note that SQLite comes with a built-in memory allocator that is
perfectly adequate for the overwhelming majority of applications
and that this object is only useful to a tiny minority of applications
with specialized memory allocation requirements.  This object is
also used during testing of SQLite in order to specify an alternative
memory allocator that simulates memory out-of-memory conditions in
order to verify that SQLite recovers gracefully from such
conditions.</p>

<p>The xMalloc, xFree, and xRealloc methods must work like the
malloc(), free(), and realloc() functions from the standard library.</p>

<p>xSize should return the allocated size of a memory allocation
previously obtained from xMalloc or xRealloc.  The allocated size
is always at least as big as the requested size but may be larger.</p>

<p>The xRoundup method returns what would be the allocated size of
a memory allocation given a particular requested size.  Most memory
allocators round up memory allocations at least to the next multiple
of 8.  Some allocators round up to a larger multiple or to a power of 2.</p>

<p>The xInit method initializes the memory allocator.  (For example,
it might allocate any require mutexes or initialize internal data
structures.  The xShutdown method is invoked (indirectly) by
<a href="#sqlite3_initialize">sqlite3_shutdown()</a> and should deallocate any resources acquired
by xInit.  The pAppData pointer is used as the only parameter to
xInit and xShutdown.
</p><hr><a name="sqlite3_module"></a>
<h2>Virtual Table Object</h2><blockquote><pre>struct sqlite3_module {
  int iVersion;
  int (*xCreate)(sqlite3*, void *pAux,
               int argc, const char *const*argv,
               sqlite3_vtab **ppVTab, char**);
  int (*xConnect)(sqlite3*, void *pAux,
               int argc, const char *const*argv,
               sqlite3_vtab **ppVTab, char**);
  int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
  int (*xDisconnect)(sqlite3_vtab *pVTab);
  int (*xDestroy)(sqlite3_vtab *pVTab);
  int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
  int (*xClose)(sqlite3_vtab_cursor*);
  int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
                int argc, sqlite3_value **argv);
  int (*xNext)(sqlite3_vtab_cursor*);
  int (*xEof)(sqlite3_vtab_cursor*);
  int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
  int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
  int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
  int (*xBegin)(sqlite3_vtab *pVTab);
  int (*xSync)(sqlite3_vtab *pVTab);
  int (*xCommit)(sqlite3_vtab *pVTab);
  int (*xRollback)(sqlite3_vtab *pVTab);
  int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
                       void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
                       void **ppArg);
  int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
};
</pre></blockquote><p><b>Important:</b> This interface is <a href="capi3ref.html">experimental</a> and is subject to change without notice.</p><p>
A module is a class of virtual tables.  Each module is defined
by an instance of the following structure.  This structure consists
mostly of methods for the module.</p>

<p>This interface is experimental and is subject to change or
removal in future releases of SQLite.
</p><hr><a name="sqlite3_mutex"></a>
<h2>Mutex Handle</h2><blockquote><pre>typedef struct sqlite3_mutex sqlite3_mutex;
</pre></blockquote><p>
The mutex module within SQLite defines <a href="#sqlite3_mutex">sqlite3_mutex</a> to be an
abstract type for a mutex object.  The SQLite core never looks
at the internal representation of an <a href="#sqlite3_mutex">sqlite3_mutex</a>.  It only
deals with pointers to the <a href="#sqlite3_mutex">sqlite3_mutex</a> object.</p>

<p>Mutexes are created using <a href="#sqlite3_mutex_alloc">sqlite3_mutex_alloc()</a>.
</p><hr><a name="sqlite3_mutex_methods"></a>
<h2>Mutex Methods Object</h2><blockquote><pre>typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
struct sqlite3_mutex_methods {
  int (*xMutexInit)(void);
  int (*xMutexEnd)(void);
  sqlite3_mutex *(*xMutexAlloc)(int);
  void (*xMutexFree)(sqlite3_mutex *);
  void (*xMutexEnter)(sqlite3_mutex *);
  int (*xMutexTry)(sqlite3_mutex *);
  void (*xMutexLeave)(sqlite3_mutex *);
  int (*xMutexHeld)(sqlite3_mutex *);
  int (*xMutexNotheld)(sqlite3_mutex *);
};
</pre></blockquote><p><b>Important:</b> This interface is <a href="capi3ref.html">experimental</a> and is subject to change without notice.</p><p>
An instance of this structure defines the low-level routines
used to allocate and use mutexes.</p>

<p>Usually, the default mutex implementations provided by SQLite are
sufficient, however the user has the option of substituting a custom
implementation for specialized deployments or systems for which SQLite
does not provide a suitable implementation. In this case, the user
creates and populates an instance of this structure to pass
to sqlite3_config() along with the <a href="#SQLITE_CONFIG_GETMALLOC">SQLITE_CONFIG_MUTEX</a> option.
Additionally, an instance of this structure can be used as an
output variable when querying the system for the current mutex
implementation, using the <a href="#SQLITE_CONFIG_GETMALLOC">SQLITE_CONFIG_GETMUTEX</a> option.</p>

<p>The xMutexInit method defined by this structure is invoked as