capi3ref.html

嵌入式数据库sqlite 3.5.9的文档

</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>
<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_temp_directory"></a>
<h2>Name Of The Folder Holding Temporary Files</h2>
<blockquote><pre>
SQLITE_EXTERN char *sqlite3_temp_directory;

</pre></blockquote>
<p>
If this global variable is made to point to a string which is
the name of a folder (a.ka. directory), then all temporary files
created by SQLite will be placed in that directory.  If this variable
is NULL pointer, then SQLite does a search for an appropriate temporary
file directory.</p>

<p>It is not safe to modify this variable once a database connection
has been opened.  It is intended that this variable be set once
as part of process initialization and before any SQLite interface
routines have been call and remain unchanged thereafter.
</p>
<hr>
<a name="sqlite3_vfs"></a>
<h2>OS Interface Object</h2>
<blockquote><pre>
typedef struct sqlite3_vfs sqlite3_vfs;
struct sqlite3_vfs {
  int iVersion;            /* Structure version number */
  int szOsFile;            /* Size of subclassed sqlite3_file */
  int mxPathname;          /* Maximum file pathname length */
  sqlite3_vfs *pNext;      /* Next registered VFS */
  const char *zName;       /* Name of this virtual file system */
  void *pAppData;          /* Pointer to application-specific data */
  int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
               int flags, int *pOutFlags);
  int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
  int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);
  int (*xGetTempname)(sqlite3_vfs*, int nOut, char *zOut);
  int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
  void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
  void (*xDlClose)(sqlite3_vfs*, void*);
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  int (*xSleep)(sqlite3_vfs*, int microseconds);
  int (*xCurrentTime)(sqlite3_vfs*, double*);
  /* New fields may be appended in figure versions.  The iVersion
  ** value will increment whenever this happens. */
};

</pre></blockquote>
<p>
An instance of this object defines the interface between the
SQLite core and the underlying operating system.  The "vfs"
in the name of the object stands for "virtual file system".</p>

<p>The iVersion field is initially 1 but may be larger for future
versions of SQLite.  Additional fields may be appended to this
object when the iVersion value is increased.</p>

<p>The szOsFile field is the size of the subclassed 
<a href="#sqlite3_file">sqlite3_file</a>
structure used by this VFS.  mxPathname is the maximum length of
a pathname in this VFS.</p>

<p>Registered sqlite3_vfs objects are kept on a linked list formed by
the pNext pointer.  The 
<a href="#sqlite3_vfs_find">sqlite3_vfs_register()</a>
and 
<a href="#sqlite3_vfs_find">sqlite3_vfs_unregister()</a> interfaces manage this list
in a thread-safe way.  The 
<a href="#sqlite3_vfs_find">sqlite3_vfs_find()</a> interface
searches the list.</p>

<p>The pNext field is the only field in the sqlite3_vfs
structure that SQLite will ever modify.  SQLite will only access
or modify this field while holding a particular static mutex.
The application should never modify anything within the sqlite3_vfs
object once the object has been registered.</p>

<p>The zName field holds the name of the VFS module.  The name must
be unique across all VFS modules.</p>

<p> SQLite will guarantee that the zFilename string passed to
xOpen() is a full pathname as generated by xFullPathname() and
that the string will be valid and unchanged until xClose() is
called. So the 
<a href="#sqlite3_file">sqlite3_file</a> can store a pointer to the
filename if it needs to remember the filename for some reason.</p>

<p> The flags argument to xOpen() includes all bits set in
the flags argument to 
<a href="#sqlite3_open">sqlite3_open_v2()</a>.  Or if 
<a href="#sqlite3_open">sqlite3_open()</a>
or 
<a href="#sqlite3_open">sqlite3_open16()</a> is used, then flags includes at least

<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_READWRITE</a> | 
<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_CREATE</a>.
If xOpen() opens a file read-only then it sets *pOutFlags to
include 
<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_READONLY</a>.  Other bits in *pOutFlags may be
set.</p>

<p> SQLite will also add one of the following flags to the xOpen()
call, depending on the object being opened:</p>

<p><ul>
<li>  
<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_MAIN_DB</a>
<li>  
<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_MAIN_JOURNAL</a>
<li>  
<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_TEMP_DB</a>
<li>  
<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_TEMP_JOURNAL</a>
<li>  
<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_TRANSIENT_DB</a>
<li>  
<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_SUBJOURNAL</a>
<li>  
<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_MASTER_JOURNAL</a>
</ul></p>

<p>The file I/O implementation can use the object type flags to
changes the way it deals with files.  For example, an application
that does not care about crash recovery or rollback might make
the open of a journal file a no-op.  Writes to this journal would
also be no-ops, and any attempt to read the journal would return
SQLITE_IOERR.  Or the implementation might recognize that a database
file will be doing page-aligned sector reads and writes in a random
order and set up its I/O subsystem accordingly.</p>

<p>SQLite might also add one of the following flags to the xOpen
method:</p>

<p><ul>
<li> 
<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_DELETEONCLOSE</a>
<li> 
<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_EXCLUSIVE</a>
</ul></p>

<p> The 
<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_DELETEONCLOSE</a> flag means the file should be
deleted when it is closed. The 
<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_DELETEONCLOSE</a>
will be set for TEMP  databases, journals and for subjournals.
 The 
<a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_EXCLUSIVE</a> flag means the file should be opened
for exclusive access.  This flag is set for all files except
for the main database file.</p>

<p> At least szOsFile bytes of memory are allocated by SQLite
to hold the  
<a href="#sqlite3_file">sqlite3_file</a> structure passed as the third
argument to xOpen.  The xOpen method does not have to
allocate the structure; it should just fill it in.</p>

<p> The flags argument to xAccess() may be 
<a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_EXISTS</a>
to test for the existance of a file,
or 
<a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_READWRITE</a> to test to see
if a file is readable and writable, or 
<a href="#SQLITE_ACCESS_EXISTS">SQLITE_ACCESS_READ</a>
to test to see if a file is at least readable. The file can be a
directory.</p>

<p> SQLite will always allocate at least mxPathname+1 bytes for
the output buffers for xGetTempname and xFullPathname. The exact
size of the output buffer is also passed as a parameter to both
methods. If the output buffer is not large enough, SQLITE_CANTOPEN
should be returned. As this is handled as a fatal error by SQLite,
vfs implementations should endeavor to prevent this by setting
mxPathname to a sufficiently large value.</p>

<p>The xRandomness(), xSleep(), and xCurrentTime() interfaces
are not strictly a part of the filesystem, but they are
included in the VFS structure for completeness.
The xRandomness() function attempts to return nBytes bytes
of good-quality randomness into zOut.  The return value is
the actual number of bytes of randomness obtained.  The
xSleep() method causes the calling thread to sleep for at
least the number of microseconds given.  The xCurrentTime()
method returns a Julian Day Number for the current date and
time.
</p>
<hr>
<a name="sqlite3_aggregate_context"></a>
<h2>Obtain Aggregate Function Context</h2>
<blockquote><pre>
void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);

</pre></blockquote>
<p>
The implementation of aggregate SQL functions use this routine to allocate
a structure for storing their state.
The first time the sqlite3_aggregate_context() routine is
is called for a particular aggregate, SQLite allocates nBytes of memory
zeros that memory, and returns a pointer to it.
On second and subsequent calls to sqlite3_aggregate_context()
for the same aggregate function index, the same buffer is returned.
The implementation
of the aggregate can use the returned buffer to accumulate data.</p>

<p>SQLite automatically frees the allocated buffer when the aggregate
query concludes.</p>

<p>The first parameter should be a copy of the

<a href="#sqlite3_context">SQL function context</a> that is the first
parameter to the callback routine that implements the aggregate
function.</p>

<p>This routine must be called from the same thread in which
the aggregate SQL function is running.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F16211</td> 
<td valign="top">
The first invocation of 
<a href="#sqlite3_aggregate_context">sqlite3_aggregate_context(C,N)</a> for
a particular instance of an aggregate function (for a particular
context C) causes SQLite to allocation N bytes of memory,
zero that memory, and return a pointer to the allocationed
memory.</td></tr>
<tr><td valign="top">F16213</td> 
<td valign="top">
If a memory allocation error occurs during

<a href="#sqlite3_aggregate_context">sqlite3_aggregate_context(C,N)</a> then the function returns 0.</td></tr>
<tr><td valign="top">F16215</td> 
<td valign="top">
Second and subsequent invocations of

<a href="#sqlite3_aggregate_context">sqlite3_aggregate_context(C,N)</a> for the same context pointer C
ignore the N parameter and return a pointer to the same
block of memory returned by the first invocation.</td></tr>
<tr><td valign="top">F16217</td> 
<td valign="top">
The memory allocated by 
<a href="#sqlite3_aggregate_context">sqlite3_aggregate_context(C,N)</a> is
automatically freed on the next call to 
<a href="#sqlite3_reset">sqlite3_reset()</a>
or 
<a href="#sqlite3_finalize">sqlite3_finalize()</a> for the 
<a href="#sqlite3_stmt">prepared statement</a> containing
the aggregate function associated with context C.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_auto_extension"></a>
<h2>Make Arrangements To Automatically Load An Extension</h2>
<blockquote><pre>
int sqlite3_auto_extension(void *xEntryPoint);

</pre></blockquote>
<p>
 This function
registers an extension entry point that is automatically invoked
whenever a new database connection is opened using

<a href="#sqlite3_open">sqlite3_open()</a>, 
<a href="#sqlite3_open">sqlite3_open16()</a>, or 
<a href="#sqlite3_open">sqlite3_open_v2()</a>.</p>

<p>This API can be invoked at program startup in order to register
one or more statically linked extensions that will be available
to all new database connections.</p>

<p> Duplicate extensions are detected so calling this routine multiple
times with the same extension is harmless.</p>

<p> This routine stores a pointer to the extension in an array
that is obtained from sqlite_malloc(). If you run a memory leak
checker on your program and it reports a leak because of this
array, then invoke 
<a href="#sqlite3_reset_auto_extension">sqlite3_reset_auto_extension()</a> prior
to shutdown to free the memory.</p>

<p> Automatic extensions apply across all threads.</p>

<p>This interface is experimental and is subject to change or
removal in future releases of SQLite.
</p>
<hr>
<a name="sqlite3_bind_parameter_count"></a>
<h2>Number Of SQL Parameters</h2>
<blockquote><pre>
int sqlite3_bind_parameter_count(sqlite3_stmt*);

</pre></blockquote>
<p>
This routine can be used to find the number of SQL parameters
in a prepared statement.  SQL parameters are tokens of the
form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
place-holders for values that are 
<a href="#sqlite3_bind_blob">bound</a>
to the parameters at a later time.</p>

<p>This routine actually returns the index of the largest parameter.
For all forms except ?NNN, this will correspond to the number of
unique parameters.  If parameters of the ?NNN are used, there may
be gaps in the list.</p>

<p>See also: 
<a href="#sqlite3_bind_blob">sqlite3_bind()</a>,

<a href="#sqlite3_bind_parameter_name">sqlite3_bind_parameter_name()</a>, and

<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>.</p>

<p><h3>Invariants:</h3>
<table border="0" cellpadding="5" cellspacing="0">
<tr><td valign="top">F13601</td> 
<td valign="top">
The 
<a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count(S)</a> interface returns
the largest index of all SQL parameters in the

<a href="#sqlite3_stmt">prepared statement</a> S, or 0 if S
contains no SQL parameters.</td></tr>
</table>
</p>
<hr>
<a name="sqlite3_bind_parameter_index"></a>
<h2>Index Of A Parameter With A Given Name</h2>
<blockquote><pre>
int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);

</pre></blockquote>
<p>
Return the index of an SQL parameter given its name.  The
index value returned is suitable for use as the second
parameter to 
<a href="#sqlite3_bind_blob">sqlite3_bind()</a>.  A zero
is returned if no matching parameter is found.  The parameter
name must be given in UTF-8 even if the original statement
was prepared from UTF-16 text using 
<a href="#sqlite3_prepare">sqlite3_prepare16_v2()</a>.</p>

<p>See also: 
<a href="#sqlite3_bind_blob">sqlite3_bind()</a>,

<a href="#sqlite3_bind_parameter_count">sqlite3_bind_parameter_count()</a>, and

<a href="#sqlite3_bind_parameter_index">sqlite3_bind_parameter_index()</a>.</p>