34to35.html

嵌入式数据库sqlite 3.5.9的文档

<a href="c3ref/file.html">sqlite3_file</a> object is an abstract base class defined as follows:
</p>

<blockquote><pre>

typedef struct sqlite3_file sqlite3_file;
struct sqlite3_file {
  const struct sqlite3_io_methods *pMethods;
};

</pre></blockquote>
<p>
  Each VFS implementation will subclass the 
<a href="c3ref/file.html">sqlite3_file</a> by adding
  additional fields at the end to hold whatever information the VFS
  needs to know about an open file.  It does not matter what information
  is stored as long as the total size of the structure does not exceed
  the szOsFile value recorded in the 
<a href="c3ref/vfs.html">sqlite3_vfs</a> object.
</p>

<p>
  The 
<a href="c3ref/io_methods.html">sqlite3_io_methods</a> object is a structure that contains pointers
  to methods for reading, writing, and otherwise dealing with files.
  This object is defined as follows:
</p>

<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>
  The iVersion field of 
<a href="c3ref/io_methods.html">sqlite3_io_methods</a> is provided as insurance
  against future enhancements.  The iVersion value should always be
  1 for SQLite version 3.5.
</p>

<p>
  The xClose method closes the file.  The space for the 
<a href="c3ref/file.html">sqlite3_file</a>
  structure is deallocated by the caller.  But if the 
<a href="c3ref/file.html">sqlite3_file</a>
  contains pointers to other allocated memory or resources, those
  allocations should be released by the xClose method.
</p>

<p>
  The xRead method reads iAmt bytes from the file beginning at a byte
  offset to iOfst.  The data read is stored in the pointer of the
  second parameter.  xRead returns the 
<a href="c3ref/c_abort.html">SQLITE_OK</a> on success,
  
<a href="c3ref/c_ioerr_blocked.html">SQLITE_IOERR_SHORT_READ</a> if it was not able to read the full number
  of bytes because it reached end-of-file, or 
<a href="c3ref/c_ioerr_blocked.html">SQLITE_IOERR_READ</a> for
  any other error.
</p>

<p>
  The xWrite method writes iAmt bytes of data from the second parameter
  into the file beginning at an offset of iOfst bytes.  If the size of
  the file is less than iOfst bytes prior to the write, then xWrite should
  ensure that the file is extended with zeros up to iOfst bytes prior
  to beginning its write.  xWrite continues to extends the file as
  necessary so that the size of the file is at least iAmt+iOfst bytes 
  at the conclusion of the xWrite call.  The xWrite method returns
  
<a href="c3ref/c_abort.html">SQLITE_OK</a> on success.  If the write cannot complete because the
  underlying storage medium is full, then 
<a href="c3ref/c_abort.html">SQLITE_FULL</a> is returned.
  
<a href="c3ref/c_ioerr_blocked.html">SQLITE_IOERR_WRITE</a> should be returned for any other error.
</p>

<p>
  The xTruncate method truncates a file to be nByte bytes in length.
  If the file is already nByte bytes or less in length then this
  method is a no-op.  The xTruncate method returns 
<a href="c3ref/c_abort.html">SQLITE_OK</a> on
  success and 
<a href="c3ref/c_ioerr_blocked.html">SQLITE_IOERR_TRUNCATE</a> if anything goes wrong.
</p>

<p>
  The xSync method is used to force previously written data out of
  operating system cache and into non-volatile memory.  The second
  parameter is usually 
<a href="c3ref/c_sync_dataonly.html">SQLITE_SYNC_NORMAL</a>.  If the second parameter
  is 
<a href="c3ref/c_sync_dataonly.html">SQLITE_SYNC_FULL</a> then the xSync method should make sure that
  data has also been flushed through the disk controllers cache.
  The 
<a href="c3ref/c_sync_dataonly.html">SQLITE_SYNC_FULL</a> parameter is the equivalent of the F_FULLSYNC
  ioctl() on Mac OS X. The xSync method returns
  
<a href="c3ref/c_abort.html">SQLITE_OK</a> on success and 
<a href="c3ref/c_ioerr_blocked.html">SQLITE_IOERR_FSYNC</a> if anything goes wrong.
</p>

<p>
  The xFileSize() method determines the current size of the file
  in bytes and writes that value into *pSize.  It returns 
<a href="c3ref/c_abort.html">SQLITE_OK</a>
  on success and 
<a href="c3ref/c_ioerr_blocked.html">SQLITE_IOERR_FSTAT</a> if something goes wrong.
</p>

<p>
  The xLock and xUnlock methods are used to set and clear file locks.
  SQLite supports five levels of file locks, in order:
  <ul>
  <li> 
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_NONE</a>
  <li> 
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a>
  <li> 
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_RESERVED</a>
  <li> 
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_PENDING</a>
  <li> 
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_EXCLUSIVE</a>
  </ul>
  The underlying implementation can support some subset of these locking
  levels as long as it meets the other requirements of this paragraph.
  The locking level is specified as the second argument to both xLock
  and xUnlock.  The xLock method increases the locking level to the
  specified locking level or higher.  The xUnlock method decreases the
  locking level to no lower than the level specified.  
  
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_NONE</a> means that the file is unlocked.  
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a>
  gives permission to read the file.  Multiple database connections can
  hold 
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a> at the same time.
  
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_RESERVED</a> is like 
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a> in that its is permission
  to read the file.  But only a single connection can hold a reserved lock
  at any point in time.  The 
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_PENDING</a> is also permission to
  read the file.  Other connections can continue to read the file as well,
  but no other connection is allowed to escalate a lock from none to shared.
  
<a href="c3ref/c_lock_exclusive.html">SQLITE_LOCK_EXCLUSIVE</a> is permission to write on the file.  Only a single
  connection can hold an exclusive lock and no other connection can hold
  any lock (other than "none") while one connection is hold an exclusive
  lock.  The xLock returns 
<a href="c3ref/c_abort.html">SQLITE_OK</a> on success, 
<a href="c3ref/c_abort.html">SQLITE_BUSY</a> if it
  is unable to obtain the lock, or 
<a href="c3ref/c_ioerr_blocked.html">SQLITE_IOERR_RDLOCK</a> if something else
  goes wrong.  The xUnlock method returns 
<a href="c3ref/c_abort.html">SQLITE_OK</a> on success and
  
<a href="c3ref/c_ioerr_blocked.html">SQLITE_IOERR_UNLOCK</a> for problems.
</p>

<p>
  The xCheckReservedLock method checks to see if another connection or
  another process is currently holding a reserved, pending, or exclusive
  lock on the file.  It returns true or false.
</p>

<p>
  The xFileControl() method is a generic interface that allows custom
  VFS implementations to directly control an open file using the
  (new and experimental)
  
<a href="c3ref/file_control.html">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="c3ref/c_fcntl_lockstate.html">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 returns the "sector size" of the underlying
  non-volatile media.  A "sector" is defined as the smallest unit of
  storage that can be written without disturbing adjacent storage.
  On a disk drive the "sector size" has until recently been 512 bytes,
  though there is a push to increase this value to 4KiB.  SQLite needs
  to know the sector size so that it can write a full sector at a
  time, and thus avoid corrupting adjacent storage space if a power
  lose occurs in the middle of a write.
</p>

<p>
  The xDeviceCharacteristics method returns an integer bit vector that
  defines any special properties that the underlying storage medium might
  have that SQLite can use to increase performance.  The allowed return
  is the bit-wise OR of the following values:
  <ul>
  <li> 
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC</a>
  <li> 
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC512</a>
  <li> 
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC1K</a>
  <li> 
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC2K</a>
  <li> 
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC4K</a>
  <li> 
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC8K</a>
  <li> 
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC16K</a>
  <li> 
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC32K</a>
  <li> 
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC64K</a>
  <li> 
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SAFE_APPEND</a>
  <li> 
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SEQUENTIAL</a>
  </ul>
  The 
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC</a> bit means that all writes to this device are
  atomic in the sense that either the entire write occurs or none of it
  occurs.  The other 
  
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC<i>nnn</i></a> values indicate that
  writes of aligned blocks of the indicated size are atomic.
  
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SAFE_APPEND</a> means that when extending a file with new
  data, the new data is written first and then the file size is updated.
  So if a power failure occurs, there is no chance that the file might have
  been extended with randomness.  The 
<a href="c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SEQUENTIAL</a> bit means
  that all writes occur in the order that they are issued and are not
  reordered by the underlying file system.
</p>

<h4>2.1.6 Checklist For Constructing A New VFS</h4>
<p>
  The preceding paragraphs contain a lot of information.
  To ease the task of constructing
  a new VFS for SQLite we offer the following implementation checklist:
</p>

<p>
  <ol>
  <li> Define an appropriate subclass of the 
<a href="c3ref/file.html">sqlite3_file</a> object.
  <li> Implement the methods required by the 
<a href="c3ref/io_methods.html">sqlite3_io_methods</a> object.
  <li> Create a static and 
       constant 
<a href="c3ref/io_methods.html">sqlite3_io_methods</a> object containing pointers
       to the methods from the previous step.
  <li> Implement the xOpen method that opens a file and populates an
       
<a href="c3ref/file.html">sqlite3_file</a> object, including setting pMethods to
       point to the 
<a href="c3ref/io_methods.html">sqlite3_io_methods</a> object from the previous step.
  <li> Implement the other methods required by 
<a href="c3ref/vfs.html">sqlite3_vfs</a>.
  <li> Define a static (but not constant) 
<a href="c3ref/vfs.html">sqlite3_vfs</a> structure that
       contains pointers to the xOpen method and the other methods and
       which contains the appropriate values for iVersion, szOsFile,
       mxPathname, zName, and pAppData.
  <li> Implement a procedure that calls 
<a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> and
       passes it a pointer to the 
<a href="c3ref/vfs.html">sqlite3_vfs</a> structure from the previous
       step.  This procedure is probably the only exported symbol in the
       source file that implements your VFS.
  </ol>
</p>

<p>