OS Interface Object

typedef struct sqlite3_vfs sqlite3_vfs;
typedef void (*sqlite3_syscall_ptr)(void);
struct sqlite3_vfs {
  int iVersion;            /* Structure version number (currently 3) */
  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 *);
  /*
  ** The methods above are in version 1 of the sqlite_vfs object
  ** definition.  Those that follow are added in version 2 or later
  */
  int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
  /*
  ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
  ** Those below are for version 3 and greater.
  */
  int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
  sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
  const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
  /*
  ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
  ** New fields may be appended in future versions.  The iVersion
  ** value will increment whenever this happens. 
  */
};

sqlite3_vfs对象的一个​​实例定义了SQLite核心与底层操作系统之间的接口。对象名称中的“vfs”代表“虚拟文件系统”。有关更多信息，请参阅VFS文档。

iVersion字段的值最初为1，但在未来版本的SQLite中可能会更大。当iVersion值增加时，可以将其他字段附加到此对象。请注意sqlite3_vfs对象的结构在SQLite版本3.5.9和3.6.0之间的事务中发生变化，但iVersion字段未被修改。

szOsFile字段是此VFS使用的子类sqlite3_file结构的大小。mxPathname是此VFS中路径名的最大长度。

已注册的sqlite3_vfs对象保留在由pNext指针形成的链接列表中。sqlite3_vfs_register()和sqlite3_vfs_unregister()接口以线程安全的方式管理该列表。sqlite3_vfs_find()接口搜索列表。应用程序代码和VFS实现都不应该使用pNext指针。

pNext字段是SQLite将要修改的sqlite3_vfs结构中唯一的字段。SQLite只会在持有特定静态互斥锁的同时访问或修改此字段。一旦对象被注册，应用程序不应该修改sqlite3_vfs对象中的任何内容。

zName字段包含VFS模块的名称。该名称在所有VFS模块中必须是唯一的。

SQLite保证xOpen的zFilename参数是一个NULL指针，或者是从xFullPathname()中获得的字符串，并添加了一个可选的后缀。如果后缀添加到zFilename参数中，它将包含一个“ - ”字符，后面跟随不超过11​​个字母数字和/或“ - ”字符。SQLite进一步保证字符串在xClose()被调用之前是有效的和不变的。由于前面的语句，如果sqlite3_file出于某种原因需要记住文件名，它可以安全地存储指向文件名的指针。如果xOpen的zFilename参数是空指针，则xOpen必须为该文件创建其自己的临时名称。每当xFilename参数为NULL时，flag参数也将包含SQLITE_OPEN_DELETEONCLOSE。

xOpen()的flags参数包含在sqlite3_open_v2()的flags参数中设置的所有位。或者，如果使用sqlite3_open()或sqlite3_open16()，则标志至少包含SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE。如果xOpen()以只读方式打开文件，那么它将* pOutFlags设置为包含SQLITE_OPEN_READONLY。可以设置* pOutFlags中的其他位。

根据打开的对象，SQLite还会将以下标志之一添加到xOpen()调用中：

• SQLITE_OPEN_MAIN_DB

• SQLITE_OPEN_MAIN_JOURNAL

• SQLITE_OPEN_TEMP_DB

• SQLITE_OPEN_TEMP_JOURNAL

• SQLITE_OPEN_TRANSIENT_DB

• SQLITE_OPEN_SUBJOURNAL

• SQLITE_OPEN_MASTER_JOURNAL

• SQLITE_OPEN_WAL

文件I/O实现可以使用对象类型标志来改变它处理文件的方式。例如，不关心崩溃恢复或回滚的应用程序可能会使日志文件的打开为空操作。写入这本期刊也是没有意义的，任何阅读期刊的尝试都会返回SQLITE_IOERR。或者实现可能会认识到数据库文件将以随机顺序进行页面对齐的扇区读取和写入，并相应地设置其I/O子系统。

SQLite可能还会将以下标志之一添加到xOpen方法中：

• SQLITE_OPEN_DELETEONCLOSE

• SQLITE_OPEN_EXCLUSIVE

SQLITE_OPEN_DELETEONCLOSE标志表示该文件在关闭时应该被删除。SQLITE_OPEN_DELETEONCLOSE将设置为TEMP数据库及其日志，瞬态数据库和子日志。

SQLITE_OPEN_EXCLUSIVE标志始终与SQLITE_OPEN_CREATE标志一起使用，这两个标志都与POSIX open()API的O_EXCL和O_CREAT标志直接类似。与SQLITE_OPEN_CREATE配对使用时，SQLITE_OPEN_EXCLUSIVE标志用于指示始终创建该文件，并且如果该文件已存在，则为错误。它不用于指示文件应该打开以进行独占访问。

至少szOsFile字节的内存由SQLite分配，以保存作为第三个参数传递给xOpen的sqlite3_file结构。xOpen方法不必分配结构; 它应该只填写它。请注意，xOpen方法必须将sqlite3_file.pMethods设置为有效的sqlite3_io_methods对象或NULL。即使打开失败，xOpen也必须执行此操作。无论xOpen调用是成功还是失败，SQLite都希望sqlOpen_file.pMethods元素在xOpen返回后有效。

xAccess()的flags参数可以是SQLITE_ACCESS_EXISTS来测试文件的存在，或者SQLITE_ACCESS_READWRITE来测试文件是否可读和可写，或者SQLITE_ACCESS_READ来测试文件是否至少可读。该文件可以是一个目录。

SQLite将始终为输出缓冲区xFullPathname分配至少mxPathname + 1个字节。输出缓冲区的确切大小也作为参数传递给两种方法。如果输出缓冲区不够大，则应返回SQLITE_CANTOPEN。由于这被SQLite作为致命错误处理，所以vfs实现应尽量通过将mxPathname设置为足够大的值来防止这种情况。

xRandomness()，xSleep()，xCurrentTime()和xCurrentTimeInt64()接口并不严格地是文件系统的一部分，但为了完整性，它们包含在VFS结构中。xRandomness()函数试图将nBytes字节的高质量随机数返回到zOut。返回值是获得的随机性的实际字节数。xSleep()方法导致调用线程至少休眠至给定的微秒数。xCurrentTime()方法将当前日期和时间的Julian日数作为浮点值返回。xCurrentTimeInt64()方法以整数形式返回Julian天数乘以86400000（24小时内的毫秒数）。

SQLite内核不使用xSetSystemCall()，xGetSystemCall()和xNestSystemCall()接口。这些可选接口由一些VFS提供，以便于测试VFS代码。通过在其控制下的功能覆盖系统调用，测试程序可以模拟否则难以或不可能产生的故障和错误状况。可以被覆盖的系统调用集从一个VFS到另一个不同，并且从相同VFS的一个版本到下一个不同。使用这些接口的应用程序必须准备好使这些接口中的任何一个或所有接口为NULL或者从一个发行版更改为下一个接口的行为。如果VFS的iVersion小于3，则应用程序不得尝试访问任何这些方法。