标准文件控制操作码

小巧。快速。可靠。
三选二。

SQLite C 接口

#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
#define SQLITE_FCNTL_LOCK_TIMEOUT           34
#define SQLITE_FCNTL_DATA_VERSION           35
#define SQLITE_FCNTL_SIZE_LIMIT             36
#define SQLITE_FCNTL_CKPT_DONE              37
#define SQLITE_FCNTL_RESERVE_BYTES          38
#define SQLITE_FCNTL_CKPT_START             39
#define SQLITE_FCNTL_EXTERNAL_READER        40
#define SQLITE_FCNTL_CKSM_FILE              41
#define SQLITE_FCNTL_RESET_CACHE            42

这些整数常量是 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 使用 SQLITE_DEBUG 编译时可用。
SQLITE_FCNTL_SIZE_HINT 操作码用于 SQLite 向 VFS 层提示数据库文件在当前事务中将增长到多大。此提示并非保证准确，但通常接近实际值。底层 VFS 可能会根据此提示预分配数据库文件空间，以帮助数据库文件的写入速度更快。
SQLITE_FCNTL_SIZE_LIMIT 操作码用于实现 sqlite3_deserialize() 的内存中 VFS，以设置内存中数据库的大小上限。参数是指向 sqlite3_int64 的指针。如果指向的整数为负数，则将其填充为当前限制。否则，限制将设置为指向的整数的值和当前数据库大小中的较大者。指向的整数设置为新的限制。
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。或者，如果未调用 xSync 方法（因为用户已使用 PRAGMA synchronous=OFF 配置 SQLite），则会调用它来代替 xSync 方法。在大多数情况下，与此文件控制一起传递的参数指针为 NULL。但是，如果数据库文件正在作为多数据库提交的一部分进行同步，则该参数指向一个以空字符结尾的字符串，其中包含事务的超级日志文件名。不需要此信号的 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 模式会导致这些文件在关闭后仍然存在。在包含数据库文件的目录上没有写入权限的其他进程想要读取数据库文件时，持久化文件很有用，因为 WAL 和共享内存文件必须存在才能读取数据库。
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 shim 和最终底层 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 shim 时，此操作码仅查找最上面的 shim。
每当解析 PRAGMA 语句时，都会将 SQLITE_FCNTL_PRAGMA 文件控制发送到与 PRAGMA 语句引用的数据库文件相对应的打开的 sqlite3_file 对象。 SQLITE_FCNTL_PRAGMA 文件控制的参数是字符串指针数组 (char**) ，其中数组的第二个元素是 PRAGMA 的名称，第三个元素是 PRAGMA 的参数或 PRAGMA 没有参数时的 NULL。 SQLITE_FCNTL_PRAGMA 文件控制的处理程序可以选择使 char** 参数的第一个元素指向从 sqlite3_mprintf() 或等效项获取的字符串，该字符串将成为 PRAGMA 的结果或 PRAGMA 失败时的错误消息。如果 SQLITE_FCNTL_PRAGMA 文件控制返回 SQLITE_NOTFOUND，则继续进行正常的 PRAGMA 处理。如果 SQLITE_FCNTL_PRAGMA 文件控制返回 SQLITE_OK，则解析器假设 VFS 已自行处理 PRAGMA，并且如果结果字符串为 NULL，则解析器生成一个无操作的准备好的语句，或者如果字符串为非 NULL，则返回结果字符串的副本。如果 SQLITE_FCNTL_PRAGMA 文件控制返回除 SQLITE_OK 或 SQLITE_NOTFOUND 之外的任何结果代码，则表示 VFS 在处理 PRAGMA 时遇到错误，并且 PRAGMA 的编译失败并出现错误。 SQLITE_FCNTL_PRAGMA 文件控制发生在 PRAGMA 语句分析的开始，因此它能够覆盖内置的 PRAGMA 语句。
SQLITE_FCNTL_BUSYHANDLER 文件控制可能由 SQLite 在数据库文件句柄打开后不久调用，以便为自定义 VFS 提供对连接的繁忙处理程序回调的访问权限。参数为 (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 活动跟踪 shim 使用。参数是一个以零结尾的字符串。如果启用了 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_COMMIT_ATOMIC_WRITE 操作码导致自上次成功调用 SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 以来执行的所有写入操作都原子地执行。此文件控制仅当所有写入都成功执行并已提交到持久存储时才返回 SQLITE_OK。无论是否成功，此文件控制都会使文件描述符退出批处理写入模式，以便所有后续写入操作都是独立的。SQLite 永远不会在没有先成功调用 SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 的情况下调用 SQLITE_FCNTL_COMMIT_ATOMIC_WRITE。
SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 操作码导致自上次成功调用 SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 以来执行的所有写入操作都回滚。此文件控制使文件描述符退出批处理写入模式，以便所有后续写入操作都是独立的。SQLite 永远不会在没有先成功调用 SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 的情况下调用 SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE。
SQLITE_FCNTL_LOCK_TIMEOUT 操作码用于配置 VFS，使其在尝试使用 VFS 的 xLock 或 xShmLock 方法获取文件锁时，最多阻塞 M 毫秒然后失败。参数是指向 32 位有符号整数的指针，该整数包含要设置为 M 的值。在返回之前，32 位有符号整数将被覆盖为 M 的先前值。
SQLITE_FCNTL_DATA_VERSION 操作码用于检测数据库文件的更改。参数是指向 32 位无符号整数的指针。将页面的“数据版本”写入指针。每当对相应的数据库文件进行任何更改时，“数据版本”都会发生变化，无论是通过同一数据库连接上的 SQL 语句，还是通过可能在其他进程中的单独数据库连接提交的事务。 sqlite3_total_changes() 接口可用于查找连接上的任何数据库是否已更改，但该接口对 TEMP 和 MAIN 的更改都有响应，并且没有提供仅检测 MAIN 更改的机制。此外， sqlite3_total_changes() 接口仅响应内部更改，并省略其他数据库连接所做的更改。 PRAGMA data_version 命令提供了一种检测由于其他数据库连接而发生的单个附加数据库的更改的机制，但省略了由调用它的数据库连接实现的更改。此文件控制是检测内部或外部发生的与特定附加数据库关联的更改的唯一机制。
SQLITE_FCNTL_CKPT_START 操作码是在 wal 模式下的检查点内在客户端开始将页面从 wal 文件复制到数据库文件之前调用的。
SQLITE_FCNTL_CKPT_DONE 操作码是在 wal 模式下的检查点内在客户端完成将页面从 wal 文件复制到数据库文件之后但在 *-shm 文件更新以记录页面已检查点的事实之前调用的。
实验性的 SQLITE_FCNTL_EXTERNAL_READER 操作码用于检测另一个进程中是否存在数据库客户端以及数据库上是否打开了 wal 模式事务。它仅在 unix 上可用。与此文件控制一起传递的 (void*) 参数应是指向 (int) 类型值的指针。如果数据库是 wal 模式数据库并且在另一个进程中至少存在一个客户端当前在数据库上打开 SQL 事务，则整数设置为 1。如果数据库不是 wal 模式数据库，或者在任何其他进程中都没有此类连接，则将其设置为 0。此操作码不能用于检测当前进程中打开的事务，只能检测其他进程中的事务。
SQLITE_FCNTL_CKSM_FILE 操作码仅供校验和 VFS shim 内部使用。
如果当前没有在数据库上打开事务，并且数据库不是临时数据库，则 SQLITE_FCNTL_RESET_CACHE 文件控制将清除内存中页面缓存的内容。如果存在打开的事务，或者如果数据库是临时数据库，则此操作码是空操作，而不是错误。

另请参阅对象、常量和函数列表。