Standard File Control Opcodes

#define SQLITE_FCNTL_LOCKSTATE               1
#define SQLITE_FCNTL_GET_LOCKPROXYFILE       2
#define SQLITE_FCNTL_SET_LOCKPROXYFILE       3
#define SQLITE_FCNTL_LAST_ERRNO              4
#define SQLITE_FCNTL_SIZE_HINT               5
#define SQLITE_FCNTL_CHUNK_SIZE              6
#define SQLITE_FCNTL_FILE_POINTER            7
#define SQLITE_FCNTL_SYNC_OMITTED            8
#define SQLITE_FCNTL_WIN32_AV_RETRY          9
#define SQLITE_FCNTL_PERSIST_WAL            10
#define SQLITE_FCNTL_OVERWRITE              11
#define SQLITE_FCNTL_VFSNAME                12
#define SQLITE_FCNTL_POWERSAFE_OVERWRITE    13
#define SQLITE_FCNTL_PRAGMA                 14
#define SQLITE_FCNTL_BUSYHANDLER            15
#define SQLITE_FCNTL_TEMPFILENAME           16
#define SQLITE_FCNTL_MMAP_SIZE              18
#define SQLITE_FCNTL_TRACE                  19
#define SQLITE_FCNTL_HAS_MOVED              20
#define SQLITE_FCNTL_SYNC                   21
#define SQLITE_FCNTL_COMMIT_PHASETWO        22
#define SQLITE_FCNTL_WIN32_SET_HANDLE       23
#define SQLITE_FCNTL_WAL_BLOCK              24
#define SQLITE_FCNTL_ZIPVFS                 25
#define SQLITE_FCNTL_RBU                    26
#define SQLITE_FCNTL_VFS_POINTER            27
#define SQLITE_FCNTL_JOURNAL_POINTER        28
#define SQLITE_FCNTL_WIN32_GET_HANDLE       29
#define SQLITE_FCNTL_PDB                    30
#define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE     31
#define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE    32
#define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE  33

这些整数常量是sqlite3_io_methods对象的xFileControl方法和sqlite3_file_control() 接口的操作码。

• SQLITE_FCNTL_LOCKSTATE操作码用于调试。此操作码会导致xFileControl方法将锁的当前状态（SQLITE_LOCK_NONE，SQLITE_LOCK_SHARED，SQLITE_LOCK_RESERVED，SQLITE_LOCK_PENDING或SQLITE_LOCK_EXCLUSIVE之一）写入pArg参数指向的整数中。此功能在测试期间使用，仅在使用SQLITE_TEST编译时选项时才可用。

• SQLITE使用SQLITE_FCNTL_SIZE_HINT操作码为VFS层提供数据库文件在当前事务期间增长的大小。这个提示并不保证准确，但通常很接近。底层VFS可能会根据此提示选择预先分配数据库文件空间，以帮助更快地写入数据库文件。

• SQLITE_FCNTL_CHUNK_SIZE操作码用于请求VFS以用户指定大小的区块扩展和截断数据库文件。sqlite3_file_control() 的第四个参数应该指向一个包含用于指定数据库的新块大小的整数（类型为int）。以大块（每次1MB）分配数据库文件空间可能会减少文件系统碎片并提高某些系统的性能。

• SQLITE_FCNTL_FILE_POINTER操作码用于获取指向与特定数据库连接关联的sqlite3_file对象的指针。另请参阅SQLITE_FCNTL_JOURNAL_POINTER。

• SQLITE_FCNTL_JOURNAL_POINTER操作码用于获取指向与特定数据库连接的日志文件（回滚日志或预写日志）关联的sqlite3_file对象的指针。另请参阅SQLITE_FCNTL_FILE_POINTER。

• 不再使用。

• SQLITE_FCNTL_SYNC操作码由SQLite在内部生成，并在数据库文件描述符上调用xSync方法之前立即发送到VFS。或者，如果因为用户使用PRAGMA synchronous = OFF配置了SQLite而未调用xSync方法，则会调用xSync方法来代替xSync方法。在大多数情况下，通过此文件控制传递的指针参数为NULL。但是，如果数据库文件正在作为多数据库提交的一部分进行同步，则参数指向包含事务master-journal文件名的以nul结尾的字符串。不需要这个信号的VFS应该默默地忽略这个操作码。应用程序不应该用此操作码调用sqlite3_file_control()，因为这样做可能会破坏确实需要它的专用VFS的操作。

• SQLITE_FCNTL_COMMIT_PHASETWO操作码由SQLite在内部生成，并在立即提交事务后但在数据库解锁之前发送至VFS。不需要这个信号的VFS应该默默地忽略这个操作码。应用程序不应该用此操作码调用sqlite3_file_control()，因为这样做可能会破坏确实需要它的专用VFS的操作。

• SQLITE_FCNTL_WIN32_AV_RETRY操作码用于为Windows VFS的某些磁盘I / O操作配置自动重试计数和间隔，以便在出现防病毒程序时提供强健性。默认情况下，Windows VFS将重试文件读取，文件写入和文件删除操作，最多10次，第一次重试前延迟25毫秒，随后每次重试延迟25毫秒。这个操作码允许调整这两个值（10个重试和25个毫秒的延迟）。对于同一进程中的所有数据库连接，值都会更改。参数是一个指向两个整数数组的指针，其中第一个整数是新的重试计数，第二个整数是延迟。如果任一整数是负数，那么设置不会改变，而是将该设置的先前值写入数组条目，从而允许询问当前的重试设置。zDbName参数被忽略。

• SQLITE_FCNTL_PERSIST_WAL操作码用于设置或查询持久性预写日志设置。默认情况下，当与数据库的最新连接关闭时，用于事务控制的辅助写入日志和共享内存文件将自动删除。设置永久WAL模式会导致这些文件在关闭后保留。当其他包含数据库文件的目录没有写权限的进程想要读取数据库文件时，保持文件很有用，因为WAL和共享内存文件必须存在才能使数据库可读。这个操作码的sqlite3_file_control()的第四个参数应该是一个指向整数的指针。该整数为0表示禁用永久WAL模式，为1表示启用永久WAL模式。如果整数是-1，

• SQLITE_FCNTL_POWERSAFE_OVERWRITE操作码用于设置或查询持久性“powersafe-overwrite”或“PSOW”设置。PSOW设置确定xDeviceCharacteristics方法的SQLITE_IOCAP_POWERSAFE_OVERWRITE位。这个操作码的sqlite3_file_control()的第四个参数应该是一个指向整数的指针。该整数为0可禁用零伤害模式或1可启用零伤害模式。如果整数是-1，那么它会被当前的零伤害模式设置覆盖。

• SQLITE_FCNTL_OVERWRITE操作码由SQLite在打开写入事务后调用，以表明除非由于某种原因回滚，否则整个数据库文件将被当前事务覆盖。这由VACUUM操作使用。

• SQLITE_FCNTL_VFSNAME操作码可用于获取VFS堆栈中所有VFS的名称。名称是所有VFS填充，最终的底层VFS被写入从sqlite3_malloc()获取的内存中，结果存储在sqlite3_file_control()的第四个参数指向的char *变量中。调用者负责在完成时释放内存。与所有文件控制操作一样，不能保证这实际上会做任何事情。如果没有实现这个文件控制，调用者应该将char *变量初始化为NULL指针。该文件控制仅用于诊断用途。

• SQLITE_FCNTL_VFS_POINTER操作码找到一个指向当前正在使用的顶级VFS的指针。sqlite3_file_control（db，SQLITE_FCNTL_VFS_POINTER，X）中的参数X必须是“sqlite3_vfs **”类型。这个操作码会将* X设置为指向顶级VFS的指针。当堆栈中有多个VFS垫片时，此操作码仅查找最上面的垫片。

• 无论何时分析PRAGMA语句，都会将SQLITE_FCNTL_PRAGMA文件控件发送到与pragma语句引用的数据库文件对应的打开sqlite3_file对象。SQLITE_FCNTL_PRAGMA文件控件的参数是一个指向字符串（char **）的指针数组，其中数组的第二个元素是该杂注的名称，第三个元素是该杂注的参数或NULL，如果该杂注没有论据。用于SQLITE_FCNTL_PRAGMA文件控制的处理程序可以选择性地将char **参数的第一个元素指向从sqlite3_mprintf()或等效项获取的字符串，如果该编译指示失败，该字符串将成为该编译指示或错误消息的结果。如果SQLITE_FCNTL_PRAGMA文件控件返回SQLITE_NOTFOUND，则继续正常的PRAGMA处理。如果SQLITE_FCNTL_PRAGMA文件控件返回SQLITE_OK，则解析器假定VFS已经处理了PRAGMA本身，并且解析器在结果字符串为NULL时生成无操作预处理语句，或者如果字符串为非结果字符串，则返回结果字符串的副本-空值。如果SQLITE_FCNTL_PRAGMA文件控制返回除SQLITE_OK或SQLITE_NOTFOUND以外的任何结果代码，则意味着VFS在处理PRAGMA时遇到错误，并且编译PRAGMA失败并出现错误。SQLITE_FCNTL_PRAGMA文件控制发生在编译指示语句分析的开始处，因此它可以覆盖内置的PRAGMA语句。或者如果字符串非NULL，则返回结果字符串的副本。如果SQLITE_FCNTL_PRAGMA文件控制返回除SQLITE_OK或SQLITE_NOTFOUND以外的任何结果代码，则意味着VFS在处理PRAGMA时遇到错误，并且编译PRAGMA失败并出现错误。SQLITE_FCNTL_PRAGMA文件控制发生在编译指示语句分析的开始处，因此它可以覆盖内置的PRAGMA语句。或者如果字符串非NULL，则返回结果字符串的副本。如果SQLITE_FCNTL_PRAGMA文件控制返回除SQLITE_OK或SQLITE_NOTFOUND以外的任何结果代码，则意味着VFS在处理PRAGMA时遇到错误，并且编译PRAGMA失败并出现错误。SQLITE_FCNTL_PRAGMA文件控制发生在编译指示语句分析的开始处，因此它可以覆盖内置的PRAGMA语句。

• SQLite_FCNTL_BUSYHANDLER文件控制可以在SQLite打开数据库文件后立即调用，以便提供一个自定义的VFS来访问连接busy-handler回调。参数是类型(void **) - 两个(void *) 值的数组。第一个(void *)实际上指向类型的函数(int (*)(void *))。为了调用连接忙处理程序，应该使用数组中的第二个(void *)作为唯一参数来调用此函数。如果它返回非零值，那么操作应该重试。如果返回零，则自定义VFS应放弃当前操作。

• 应用程序可以调用SQLITE_FCNTL_TEMPFILENAME文件控制，让SQLite使用相同的算法生成临时文件名，以便为TEMP表和其他内部用途生成临时文件名。参数应该是一个char **，它将填充从sqlite3_malloc()获取的写入内存的文件名。调用者应该在结果上调用sqlite3_free()以避免内存泄漏。

• SQLITE_FCNTL_MMAP_SIZE文件控件用于查询或设置将用于内存映射 I/O 的最大字节数。该参数是指向sqlite3_int64类型值的指针，该值是文件到内存映射的建议最大字节数。指针被旧值覆盖。如果最初指向的值是负数，则限制不会更改，因此可以通过传入指向负数的指针来查询当前限制。该文件控制在内部用于实现PRAGMA mmap_size。

• SQLITE_FCNTL_TRACE文件控件向VFS提供有关SQLite堆栈的更高层正在做什么的建议信息。该文件控制由一些VFS活动追踪垫片使用。该参数是一个以零结尾的字符串。如果启用了SQLITE_USE_FCNTL_TRACE编译时选项，则SQLite堆栈中的更高层可能会生成此文件控件的实例。

• SQLITE_FCNTL_HAS_MOVED文件控件将其参数解释为指向整数的指针，并根据文件是否从第一次打开后被重命名，移动或删除而将布尔值写入该整数。

• SQLITE_FCNTL_WIN32_GET_HANDLE操作码可用于获取与文件句柄关联的基础本机文件句柄。该文件控制将其参数解释为指向本机文件句柄的指针，并将结果值写入该文件句柄。

• SQLITE_FCNTL_WIN32_SET_HANDLE操作码用于调试。该操作码使xFileControl方法将文件句柄与pArg参数指向的文件句柄交换。此功能在测试过程中使用，只有在定义SQLITE_TEST时才需要支持。

• SQLITE_FCNTL_WAL_BLOCK是VFS层的一个信号，如果锁不是立即可用的话，阻塞下一个WAL锁可能是有利的。WAL子系统在极少数情况下发出此信号，以解决优先倒置问题。应用程序应该不使用此文件控制。

• SQLITE_FCNTL_ZIPVFS操作码仅由zipvfs实现。所有其他VFS应该为此操作码返回SQLITE_NOTFOUND。

• SQLITE_FCNTL_RBU操作码仅由RBU扩展使用的特殊VFS实现。所有其他VFS应该为此操作码返回SQLITE_NOTFOUND。

• 如果SQLITE_FCNTL_BEGIN_ATOMIC_WRITE操作码返回SQLITE_OK，则文件描述符被置于“批处理写入模式”，这意味着所有后续写入操作将被延迟并在下一个SQLITE_FCNTL_COMMIT_ATOMIC_WRITE处以原子方式完成。不支持批量原子写入的系统将返回SQLITE_NOTFOUND。在成功完成SQLITE_FCNTL_BEGIN_ATOMIC_WRITE之后，在关闭SQLITE_FCNTL_COMMIT_ATOMIC_WRITE或SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE之前，SQLite将不会在相同的sqlite3_file文件描述符上调用VFS接口调用，除了调用xWrite方法和使用SQLITE_FCNTL_SIZE_HINT调用xFileControl方法。

• 自上次成功调用SQLITE_FCNTL_BEGIN_ATOMIC_WRITE以自动执行以来，SQLITE_FCNTL_COMMIT_ATOMIC_WRITE操作码将导致所有写入操作。当且仅当写入全部成功执行并且已被提交到永久存储器时，此文件控制返回SQLITE_OK。无论它是否成功，此文件控制都会将文件描述符从批处理写入模式中移出，以便所有后续写入操作都是独立的。没有事先成功调用SQLITE_FCNTL_BEGIN_ATOMIC_WRITE，SQLite将永远不会调用SQLITE_FCNTL_COMMIT_ATOMIC_WRITE。

• 自上一次成功调用SQLITE_FCNTL_BEGIN_ATOMIC_WRITE以来，SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE操作码将导致所有写操作被回滚。此文件控制将文件描述符从批处理写入模式中移出，以便所有后续写入操作都是独立的。没有事先成功调用SQLITE_FCNTL_BEGIN_ATOMIC_WRITE，SQLite将永远不会调用SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE。