capi3ref.html

这是sqlite3.56的文档。拿来给大家阅读使用

</pre></blockquote>
<p>
An instance of the following opaque structure is used to
represent an blob-handle.  A blob-handle is created by

<a href="#sqlite3_blob_open">sqlite3_blob_open()</a> and destroyed by 
<a href="#sqlite3_blob_close">sqlite3_blob_close()</a>.
The 
<a href="#sqlite3_blob_read">sqlite3_blob_read()</a> and 
<a href="#sqlite3_blob_write">sqlite3_blob_write()</a> interfaces
can be used to read or write small subsections of the blob.
The 
<a href="#sqlite3_blob_bytes">sqlite3_blob_bytes()</a> interface returns the size of the
blob in bytes.
</p>
<hr>
<a name="sqlite3_context"></a>
<h2>SQL Function Context Object</h2>
<blockquote><pre>
typedef struct sqlite3_context sqlite3_context;

</pre></blockquote>
<p>
The context in which an SQL function executes is stored in an
sqlite3_context object.  A pointer to an sqlite3_context
object is always first parameter to application-defined SQL functions.
</p>
<hr>
<a name="sqlite3_file"></a>
<h2>OS Interface Open File Handle</h2>
<blockquote><pre>
typedef struct sqlite3_file sqlite3_file;
struct sqlite3_file {
  const struct sqlite3_io_methods *pMethods;  /* Methods for an open file */
};

</pre></blockquote>
<p>
An 
<a href="#sqlite3_file">sqlite3_file</a> object represents an open file in the OS
interface layer.  Individual OS interface implementations will
want to subclass this object by appending additional fields
for their own use.  The pMethods entry is a pointer to an

<a href="#sqlite3_io_methods">sqlite3_io_methods</a> object that defines methods for performing
I/O operations on the open file.
</p>
<hr>
<a name="sqlite3_io_methods"></a>
<h2>OS Interface File Virtual Methods Object</h2>
<blockquote><pre>
typedef struct sqlite3_io_methods sqlite3_io_methods;
struct sqlite3_io_methods {
  int iVersion;
  int (*xClose)(sqlite3_file*);
  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
  int (*xSync)(sqlite3_file*, int flags);
  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
  int (*xLock)(sqlite3_file*, int);
  int (*xUnlock)(sqlite3_file*, int);
  int (*xCheckReservedLock)(sqlite3_file*);
  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
  int (*xSectorSize)(sqlite3_file*);
  int (*xDeviceCharacteristics)(sqlite3_file*);
  /* Additional methods may be added in future releases */
};

</pre></blockquote>
<p>
Every file opened by the 
<a href="#sqlite3_vfs">sqlite3_vfs</a> xOpen method contains a pointer to
an instance of the this object.  This object defines the
methods used to perform various operations against the open file.</p>

<p>The flags argument to xSync may be one of 
<a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_NORMAL</a> or

<a href="#SQLITE_SYNC_DATAONLY">SQLITE_SYNC_FULL</a>.  The first choice is the normal fsync().
OS-X style fullsync.  The SQLITE_SYNC_DATA flag may be ORed in to
indicate that only the data of the file and not its inode needs to be
synced.</p>

<p>The integer values to xLock() and xUnlock() are one of
<ul>
<li> 
<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_NONE</a>,
<li> 
<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_SHARED</a>,
<li> 
<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_RESERVED</a>,
<li> 
<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_PENDING</a>, or
<li> 
<a href="#SQLITE_LOCK_EXCLUSIVE">SQLITE_LOCK_EXCLUSIVE</a>.
</ul>
xLock() increases the lock. xUnlock() decreases the lock.
The xCheckReservedLock() method looks
to see if any database connection, either in this
process or in some other process, is holding an RESERVED,
PENDING, or EXCLUSIVE lock on the file.  It returns true
if such a lock exists and false if not.</p>

<p>The xFileControl() method is a generic interface that allows custom
VFS implementations to directly control an open file using the

<a href="#sqlite3_file_control">sqlite3_file_control()</a> interface.  The second "op" argument
is an integer opcode.   The third
argument is a generic pointer which is intended to be a pointer
to a structure that may contain arguments or space in which to
write return values.  Potential uses for xFileControl() might be
functions to enable blocking locks with timeouts, to change the
locking strategy (for example to use dot-file locks), to inquire
about the status of a lock, or to break stale locks.  The SQLite
core reserves opcodes less than 100 for its own use.
A 
<a href="#SQLITE_FCNTL_LOCKSTATE">list of opcodes</a> less than 100 is available.
Applications that define a custom xFileControl method should use opcodes
greater than 100 to avoid conflicts.</p>

<p>The xSectorSize() method returns the sector size of the
device that underlies the file.  The sector size is the
minimum write that can be performed without disturbing
other bytes in the file.  The xDeviceCharacteristics()
method returns a bit vector describing behaviors of the
underlying device:</p>

<p><ul>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC512</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC1K</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC2K</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC4K</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC8K</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC16K</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC32K</a>
<li> 
<a href="#SQLITE_IOCAP_ATOMIC">SQLITE_IOCAP_ATOMIC64K</a>
<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>
<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_value"></a>
<h2>Dynamically Typed Value Object</h2>
<blockquote><pre>
typedef struct Mem sqlite3_value;

</pre></blockquote>
<p>
SQLite uses the sqlite3_value object to represent all values
that are or can be stored in a database table.
SQLite uses dynamic typing for the values it stores.
Values stored in sqlite3_value objects can be
be integers, floating point values, strings, BLOBs, or NULL.
</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 vfs modules 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 fields 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 are
also a no-op.  Any attempt to read the journal return SQLITE_IOERR.
Or the implementation might recognize the 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 is 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 byte 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 cause the calling thread to sleep for at
least the number of microseconds given.  The xCurrentTime()