capi3ref.html

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

<p>The cache is not required to perform any reference counting. A single
call to xUnpin() unpins the page regardless of the number of prior calls
to xFetch().</p>

<p>The xRekey() method is used to change the key value associated with the
page passed as the second argument from oldKey to newKey. If the cache
previously contains an entry associated with newKey, it should be
discarded. Any prior cache entry associated with newKey is guaranteed not
to be pinned.</p>

<p>When SQLite calls the xTruncate() method, the cache must discard all
existing cache entries with page numbers (keys) greater than or equal
to the value of the iLimit parameter passed to xTruncate(). If any
of these pages are pinned, they are implicitly unpinned, meaning that
they can be safely discarded.</p>

<p>The xDestroy() method is used to delete a cache allocated by xCreate().
All resources associated with the specified cache should be freed. After
calling the xDestroy() method, SQLite considers the <a href="#sqlite3_pcache">sqlite3_pcache*</a>
handle invalid, and will not use it with any other sqlite3_pcache_methods
functions.
</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.k.a. directory), then all temporary files
created by SQLite will be placed in that directory.  If this variable
is a NULL pointer, then SQLite performs a search for an appropriate
temporary file directory.</p>

<p>It is not safe to modify this variable once a <a href="#sqlite3">database connection</a>
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 *pResOut);
  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);
  void (*xDlClose)(sqlite3_vfs*, void*);
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  int (*xSleep)(sqlite3_vfs*, int microseconds);
  int (*xCurrentTime)(sqlite3_vfs*, double*);
  int (*xGetLastError)(sqlite3_vfs*, int, char *);
  /* New fields may be appended in figure versions.  The iVersion
  ** value will increment whenever this happens. */
};
</pre></blockquote><p>
An instance of the sqlite3_vfs 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 value of the iVersion field is initially 1 but may be larger in
future versions of SQLite.  Additional fields may be appended to this
object when the iVersion value is increased.  Note that the structure
of the sqlite3_vfs object changes in the transaction between
SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
modified.</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.  Neither the application code nor the VFS
implementation should use the pNext pointer.</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 parameter to xOpen
is either a NULL pointer or string obtained
from xFullPathname().  SQLite further guarantees that
the string will be valid and unchanged until xClose() is
called. Because of the previous sentense,
the <a href="#sqlite3_file">sqlite3_file</a> can safely store a pointer to the
filename if it needs to remember the filename for some reason.
If the zFilename parameter is xOpen is a NULL pointer then xOpen
must invite its own temporary name for the file.  Whenever the
xFilename parameter is NULL it will also be the case that the
flags parameter will include <a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_DELETEONCLOSE</a>.</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
change 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.</p>

<p>The <a href="#SQLITE_OPEN_CREATE">SQLITE_OPEN_EXCLUSIVE</a