34to35.html

嵌入式数据库sqlite 3.5.9的文档

  Once a VFS has been registered, it should never be modified.  If
  a change in behavior is required, a new VFS should be registered.
  The application could, perhaps, use 
<a href="c3ref/vfs_find.html">sqlite3_vfs_find()</a> to locate
  the old VFS, make a copy of the old VFS into a new 
<a href="c3ref/vfs.html">sqlite3_vfs</a>
  object, make the desired modifications to the new VFS, unregister
  the old VFS, the register the new VFS in its place.  Existing
  database connections would continue to use the old VFS even after
  it is unregistered, but new database connections would use the
  new VFS.
</p>

<h4>2.1.4 The VFS Object</h4>
<p>
  A VFS object is an instance of the following structure:
</p>

<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*, char *zOut);
  int (*xFullPathname)(sqlite3_vfs*, const char *zName, 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>
  To create a new VFS, an application fills in an instance of this
  structure with appropriate values and then calls 
<a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a>.
</p>

<p>
  The iVersion field of 
<a href="c3ref/vfs.html">sqlite3_vfs</a> should be 1 for SQLite version 3.5.0.
  This number may increase in future versions of SQLite if we have to
  modify the VFS object in some way.  We hope that this never happens,
  but the provision is made in case it does.
</p>

<p>
  The szOsFile field is the size in bytes of the structure that defines
  an open file: the 
<a href="c3ref/file.html">sqlite3_file</a> object.  This object will be described
  more fully below.  The point here is that each VFS implementation can
  define its own 
<a href="c3ref/file.html">sqlite3_file</a> object containing whatever information
  the VFS implementation needs to store about an open file.  SQLite needs
  to know how big this object is, however, in order to preallocate enough
  space to hold it.
</p>

<p>
  The mxPathname field is the maximum length of a file pathname that
  this VFS can use.  SQLite sometimes has to preallocate buffers of
  this size, so it should be as small as reasonably possible.  Some
  filesystems permit huge pathnames, but in practice pathnames rarely
  extend beyond 100 bytes or so.  You do not have to put the longest
  pathname that the underlying filesystem can handle here.  You only
  have to put the longest pathname that you want SQLite to be able to
  handle.  A few hundred is a good value in most cases.
</p>

<p>
  The pNext field is used internally by SQLite.  Specifically, SQLite
  uses this field to form a linked list of registered VFSes.
</p>

<p>
  The zName field is the symbolic name of the VFS.  This is the name 
  that the 
<a href="c3ref/vfs_find.html">sqlite3_vfs_find()</a> compares against when it is looking for
  a VFS.
</p>

<p>
  The pAppData pointer is unused by the SQLite core.  The pointer is
  available to store auxiliary information that a VFS information might
  want to carry around.
</p>

<p>
  The remaining fields of the 
<a href="c3ref/vfs.html">sqlite3_vfs</a> object all store pointer
  to functions that implement primitive operations.  We call these
  "methods".  The first methods, xOpen, is used to open files on
  the underlying storage media.  The result is an 
<a href="c3ref/file.html">sqlite3_file</a>
  object.  There are additional methods, defined by the 
<a href="c3ref/file.html">sqlite3_file</a>
  object itself that are used to read and write and close the file.
  The additional methods are detailed below.  The filename is in UTF-8.
  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="c3ref/file.html">sqlite3_file</a> can store a pointer to the
   filename if it needs to remember the filename for some reason.
   The flags argument to xOpen() is a copy of the flags argument
   to sqlite3_open_v2().  If sqlite3_open() or sqlite3_open16()
   is used, then flags is 
<a href="c3ref/c_open_create.html">SQLITE_OPEN_READWRITE</a> | 
<a href="c3ref/c_open_create.html">SQLITE_OPEN_CREATE</a>.
   If xOpen() opens a file read-only then it sets *pOutFlags to
   include 
<a href="c3ref/c_open_create.html">SQLITE_OPEN_READONLY</a>.  Other bits in *pOutFlags may be
   set.
   SQLite will also add one of the following flags to the xOpen()
   call, depending on the object being opened:
   <ul>
   <li>  
<a href="c3ref/c_open_create.html">SQLITE_OPEN_MAIN_DB</a>
   <li>  
<a href="c3ref/c_open_create.html">SQLITE_OPEN_MAIN_JOURNAL</a>
   <li>  
<a href="c3ref/c_open_create.html">SQLITE_OPEN_TEMP_DB</a>
   <li>  
<a href="c3ref/c_open_create.html">SQLITE_OPEN_TEMP_JOURNAL</a>
   <li>  
<a href="c3ref/c_open_create.html">SQLITE_OPEN_TRANSIENT_DB</a>
   <li>  
<a href="c3ref/c_open_create.html">SQLITE_OPEN_SUBJOURNAL</a>
   <li>  
<a href="c3ref/c_open_create.html">SQLITE_OPEN_MASTER_JOURNAL</a>
   </ul>
   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 returns 
<a href="c3ref/c_abort.html">SQLITE_IOERR</a>.
   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.
   SQLite might also add one of the following flags to the xOpen
   method:
   <ul>
   <li> 
<a href="c3ref/c_open_create.html">SQLITE_OPEN_DELETEONCLOSE</a>
   <li> 
<a href="c3ref/c_open_create.html">SQLITE_OPEN_EXCLUSIVE</a>
   </ul>
   The 
<a href="c3ref/c_open_create.html">SQLITE_OPEN_DELETEONCLOSE</a> flag means the file should be
   deleted when it is closed.  This will always be set for TEMP 
   databases and journals and for subjournals.  The 
   
<a href="c3ref/c_open_create.html">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.
   The 
<a href="c3ref/file.html">sqlite3_file</a> structure passed as the third argument to
   xOpen is allocated by the caller.  xOpen just fills it in.  The
   caller allocates a minimum of szOsFile bytes for the 
<a href="c3ref/file.html">sqlite3_file</a>
   structure.
</p>

<p>
  The differences between an 
<a href="c3ref/c_open_create.html">SQLITE_OPEN_TEMP_DB</a> database and an
  
<a href="c3ref/c_open_create.html">SQLITE_OPEN_TRANSIENT_DB</a> database is this:  The 
<a href="c3ref/c_open_create.html">SQLITE_OPEN_TEMP_DB</a>
  is used for explicitly declared and named TEMP tables (using the
  CREATE TEMP TABLE syntax) or for named tables in a temporary database
  that is created by opening a database with a filename that is an empty
  string.  An 
<a href="c3ref/c_open_create.html">SQLITE_OPEN_TRANSIENT_DB</a> holds an database table that
  SQLite creates automatically in order to evaluate a subquery or
  ORDER BY or GROUP BY clause.  Both TEMP_DB and TRANSIENT_DB databases
  are private and are deleted automatically.  TEMP_DB databases last
  for the duration of the database connection.  TRANSIENT_DB databases
  last only for the duration of a single SQL statement.
</p>

<p>
  The xDelete method is used delete a file.  The name of the file is
  given in the second parameter.  The filename will be in UTF-8.
  The VFS must convert the filename into whatever character representation
  the underlying operating system expects.  If the syncDir parameter is
  true, then the xDelete method should not return until the change
  to the directory contents for the directory containing the
  deleted file have been synced to disk in order to insure that the
  file does not "reappear" if a power failure occurs soon after.
</p>

<p>
  The xAccess method is used to check for access permissions on a file.
  The filename will be UTF-8 encoded.  The flags argument will be
  
<a href="c3ref/c_access_exists.html">SQLITE_ACCESS_EXISTS</a> to check for the existence of the file,
  
<a href="c3ref/c_access_exists.html">SQLITE_ACCESS_READWRITE</a> to check to see if the file is both readable
  and writable, or 
<a href="c3ref/c_access_exists.html">SQLITE_ACCESS_READ</a> to check to see if the file is
  at least readable.  The "file" named by the second parameter might
  be a directory or folder name.
</p>

<p>
  The xGetTempName method computes the name of a temporary file that
  SQLite can use.  The name should be written into the buffer given
  by the second parameter.  SQLite will size that buffer to hold
  at least mxPathname bytes.  The generated filename should be in UTF-8.
  To avoid security problems, the generated temporary filename should
  contain enough randomness to prevent an attacker from guessing the
  temporary filename in advance.
</p>

<p>
  The xFullPathname method is used to convert a relative pathname
  into a full pathname.  The resulting full pathname is written into
  the buffer provided by the third parameter.  SQLite will size the
  output buffer to at least mxPathname bytes.  Both the input and
  output names should be in UTF-8.
</p>

<p>
  The xDlOpen, xDlError, xDlSym, and xDlClose methods are all used for
  accessing shared libraries at run-time.  These methods may be omitted
  (and their pointers set to zero) if the library is compiled with
  SQLITE_OMIT_LOAD_EXTENSION or if the 
<a href="c3ref/enable_load_extension.html">sqlite3_enable_load_extension()</a>
  interface is never used to enable dynamic extension loading.  The
  xDlOpen method opens a shared library or DLL and returns a pointer to
  a handle.  NULL is returned if the open fails.  If the open fails,
  the xDlError method can be used to obtain a text error message.
  The message is written into the zErrMsg buffer of the third parameter
  which is at least nByte bytes in length.  The xDlSym returns a pointer
  to a symbol in the shared library.  The name of the symbol is given
  by the second parameter.  UTF-8 encoding is assumed.  If the symbol
  is not found a NULL pointer is returned.  The xDlClose routine closes
  the shared library.
</p>

<p>
  The xRandomness method is used exactly once to initialize the 
  pseudo-random number generator (PRNG) inside of SQLite.  Only
  the xRandomness method on the default VFS is used.  The xRandomness
  methods on other VFSes are never accessed by SQLite.
  The xRandomness routine requests that nByte bytes of randomness
  be written into zOut.  The routine returns the actual number of
  bytes of randomness obtained.  The quality of the randomness so obtained
  will determine the quality of the randomness generated by built-in 
  SQLite functions such as random() and randomblob().  SQLite also
  uses its PRNG to generate temporary file names..  On some platforms
  (ex: windows) SQLite assumes that temporary file names are unique
  without actually testing for collisions, so it is important to have
  good-quality randomness even if the random() and randomblob() 
  functions are never used.
</p>

<p>
  The xSleep method is used to suspend the calling thread for at
  least the number of microseconds given.  This method is used to
  implement the 
<a href="c3ref/sleep.html">sqlite3_sleep()</a> and 
<a href="c3ref/busy_timeout.html">sqlite3_busy_timeout()</a> APIs.
  In the case of 
<a href="c3ref/sleep.html">sqlite3_sleep()</a> the xSleep method of the default
  VFS is always used.  If the underlying system does not have a
  microsecond resolution sleep capability, then the sleep time should
  be rounded up.  xSleep returns this rounded-up value.
</p>

<p>
  The xCurrentTime method finds the current time and date and writes
  the result as double-precision floating point value into pointer
  provided by the second parameter.  The time and date is in
  coordinated universal time (UTC) and is a fractional julian day number.
</p>

<h4>2.1.5 The Open File Object</h4>
<p>
  The result of opening a file is an instance of an 
<a href="c3ref/file.html">sqlite3_file</a> object.
  The