標準檔案控制操作碼 (Standard File Control Opcodes)

小巧、快速、可靠。
擇三。

SQLite C 介面

標準檔案控制操作碼 (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
#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_DEBUG 編譯 SQLite 時可用。
SQLite 使用 SQLITE_FCNTL_SIZE_HINT 操作碼向 VFS 層提示資料庫檔案在目前交易期間將增長的大小。此提示不保證準確，但通常很接近。底層 VFS 可以選擇根據此提示預先分配資料庫檔案空間，以幫助加快寫入資料庫檔案的速度。
實作 sqlite3_deserialize() 的記憶體內 VFS 使用 SQLITE_FCNTL_SIZE_LIMIT 操作碼來設定記憶體內資料庫大小的上限。參數是指向 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。或者，如果因為使用者已使用 PRAGMA synchronous=OFF 設定 SQLite 而未呼叫 xSync 方法，則會改為呼叫此操作碼。在大多數情況下，隨此檔案控制項傳遞的指標引數為 NULL。但是，如果資料庫檔案正作為多資料庫提交的一部分進行同步，則該引數會指向一個以 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 和共享記憶體檔案必須存在才能讀取資料庫。此操作碼的 sqlite3_file_control() 的第四個參數應是指向整數的指標。該整數為 0 表示停用持續性 WAL 模式，為 1 表示啟用持續性 WAL 模式。如果整數為 -1，則會覆寫為目前的 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可能會對其調用 SQLITE_FCNTL_BUSYHANDLER 檔案控制，以便為自定義 VFS 提供連線的 busy-handler 回呼函式。參數類型為 (void**) - 一個包含兩個 (void *) 值的陣列。第一個 (void *) 實際上指向一個類型為 (int (*)(void *)) 的函式。為了調用連線的 busy-handler，應該以陣列中的第二個 (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 鎖可能是有利的。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_FCNTL_BEGIN_ATOMIC_WRITE，SQLite 就永遠不會呼叫 SQLITE_FCNTL_COMMIT_ATOMIC_WRITE。
SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 操作碼會使自前一次成功呼叫 SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 以來的所有寫入操作都回復。此檔案控制項會將檔案描述符從批次寫入模式中取出，以便所有後續的寫入操作都是獨立的。沒有事先成功呼叫 SQLITE_FCNTL_BEGIN_ATOMIC_WRITE，SQLite 就永遠不會呼叫 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 操作碼僅供 checksum VFS shim 內部使用。
如果目前資料庫上沒有開啟的交易，且資料庫不是臨時資料庫，則 SQLITE_FCNTL_RESET_CACHE 檔案控制會清除記憶體中頁面快取的內容。如果已開啟交易，或資料庫是臨時資料庫，則此操作碼為無效操作 (no-op)，而不是錯誤。

另請參閱物件、常數和函式列表。