Small. Fast. Reliable.
Choose any three.
关于 网站地图 文档 下载 许可 新闻 支持

SQLite C 接口

操作系统接口，文件虚拟方法对象
OS Interface File Virtual Methods Object

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 *pResOut);
  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
  int (*xSectorSize)(sqlite3_file*);
  int (*xDeviceCharacteristics)(sqlite3_file*);
  /* 上面的方法在第一版中有效  Methods above are valid for version 1 */
  int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
  int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
  void (*xShmBarrier)(sqlite3_file*);
  int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
  /* 上面的方法在第二版中有效  Methods above are valid for version 2 */
  int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
  int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
  /* 上面的方法在第三版中有效  Methods above are valid for version 3 */
  /* 未来的发行版中可能会加入更多方法。  Additional methods may be added in future releases */
};

每一个sqlite3_vfs.xOpen方法打开的文件都保存在一个sqlite3_file对象中（通常是sqlite3_file对象的子类）并且包含一个指向这个对象实例的指针。这个对象定义了用于完成sqlite3_file表示的文件的上的各种操作的函数。
Every file opened by the sqlite3_vfs.xOpen method populates an sqlite3_file object (or, more commonly, a subclass of the sqlite3_file object) with a pointer to an instance of this object. This object defines the methods used to perform various operations against the open file represented by the sqlite3_file object.

如果sqlite3_vfs.xOpen函数将sqlite3_file.pMethods属性设置为一个非NULL指针，那么即使sqlite3_vfs.xOpen失败了，也会执行sqlite3_io_methods.xClose方法。阻止sqlite3_vfs.xOpen失败后的xClose调用的唯一方法就是sqlite3_vfs.xOpen将sqlite3_file.pMethods设置为NULL。
If the sqlite3_vfs.xOpen method sets the sqlite3_file.pMethods element to a non-NULL pointer, then the sqlite3_io_methods.xClose method may be invoked even if the sqlite3_vfs.xOpen reported that it failed. The only way to prevent a call to xClose following a failed sqlite3_vfs.xOpen is for the sqlite3_vfs.xOpen to set the sqlite3_file.pMethods element to NULL.

xSync的标志参数可以是SQLITE_SYNC_NORMAL或SQLITE_SYNC_FULL。第一个选择时标准的fsync()。第二个选择是Mac OS X风格的fullsync。可以或一个SQLITE_SYNC_DATAONLY标志，表示只有文件的数据会同步，而inode不会同步。
The flags argument to xSync may be one of SQLITE_SYNC_NORMAL or SQLITE_SYNC_FULL. The first choice is the normal fsync(). The second choice is a Mac OS X style fullsync. The SQLITE_SYNC_DATAONLY flag may be ORed in to indicate that only the data of the file and not its inode needs to be synced.

xLock() 和 xUnlock()的整数值可以是下列之一：
The integer values to xLock() and xUnlock() are one of

xLock()增加锁。xUnlock()减少锁。xCheckReservedLock()方法用来检查当前线程或者其它线程上是否有数据库连接持有这个文件的RESERVED锁、PENDING锁或EXCLUSIVE锁。如果存在这些锁，那么会返回true，否则是false。
xLock() increases the lock. xUnlock() decreases the lock. The xCheckReservedLock() method checks whether any database connection, either in this process or in some other process, is holding a RESERVED, PENDING, or EXCLUSIVE lock on the file. It returns true if such a lock exists and false otherwise.

xFileControl()方法是一个通用接口，这个接口允许自定义的VFS实现通过sqlite3_file_control()接口直接控制打开的文件。第二个参数“op”是一个整数操作码。第三个参数是一个通用指针，可以指向一个包含参数或返回值空间的结构体。 xFileControl()可以用来启用带超时的阻塞锁，可以修改锁策略（例如使用点文件锁），可以查询锁的状态，还可以破坏旧锁。SQLite保留了小于100的所有操作码以留作自用。这里是小于100的可用的操作码列表。应用程序如果定义一个自定义的xFileControl方法需要使用大于100的操作码，以防止冲突。VFS实现对于不认识的控制操作码，应当返回SQLITE_NOTFOUND。
The xFileControl() method is a generic interface that allows custom VFS implementations to directly control an open file using the sqlite3_file_control() interface. The second "op" argument is an integer opcode. The third argument is a generic pointer intended to point 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 all opcodes less than 100 for its own use. A list of opcodes less than 100 is available. Applications that define a custom xFileControl method should use opcodes greater than 100 to avoid conflicts. VFS implementations should return SQLITE_NOTFOUND for file control opcodes that they do not recognize.

xSectorSize()方法可以返回文件所在的设备的扇区大小。扇区大小是在不影响其它字节的情况下可以写入文件的最小尺寸。xDeviceCharacteristics()方法返回一个位向量来描述底层设备的行为：
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:

SQLITE_IOCAP_ATOMIC属性表示任意尺寸的写入都是原子的。SQLITE_IOCAP_ATOMICnnn值表示写入一个nnn字节的块，并且地址对齐为nnn的倍数时是原子的。SQLITE_IOCAP_SAFE_APPEND表示当向文件追加数据时，会首先写入数据，然后才扩大文件尺寸，永远不会颠倒。SQLITE_IOCAP_SEQUENTIAL属性表示信息写入磁盘的顺序和调用xWrite()一致。
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().

如果xRead() 返回SQLITE_IOERR_SHORT_READ，那么缓存中未读取的部分会被填入零。一个VFS如果不支持zero-fill short reads，也同样可以运行，但是无法zero-fill short reads最终可能会导致数据库损坏。
If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill in the unread portions of the buffer with zeros. A VFS that fails to zero-fill short reads might seem to work. However, failure to zero-fill short reads will eventually lead to database corruption.

另行参见Objects、Constants和Functions的列表。
See also lists of Objects, Constants, and Functions.