Standard File Control Opcodes

From 63847496f14c813a5d80efd5b7de0f1294ffe1e3 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 13 Apr 2024 16:07:11 +0200 Subject: Adding upstream version 3.45.1. Signed-off-by: Daniel Baumann --- www/c3ref/c_fcntl_begin_atomic_write.html | 545 ++++++++++++++++++++++++++++++ 1 file changed, 545 insertions(+) create mode 100644 www/c3ref/c_fcntl_begin_atomic_write.html (limited to 'www/c3ref/c_fcntl_begin_atomic_write.html') diff --git a/www/c3ref/c_fcntl_begin_atomic_write.html b/www/c3ref/c_fcntl_begin_atomic_write.html new file mode 100644 index 0000000..76d6e5a --- /dev/null +++ b/www/c3ref/c_fcntl_begin_atomic_write.html @@ -0,0 +1,545 @@ + + + + + +Standard File Control Opcodes + + + +

+ +

+Small. Fast. Reliable.
Choose any three. +

+ + +

+ +

+ + +

SQLite C Interface

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
+

+These integer constants are opcodes for the xFileControl method +of the sqlite3_io_methods object and for the sqlite3_file_control() +interface.

+ +

+ +The SQLITE_FCNTL_LOCKSTATE opcode is used for debugging. This +opcode causes the xFileControl method to write the current state of +the lock (one of SQLITE_LOCK_NONE, SQLITE_LOCK_SHARED, +SQLITE_LOCK_RESERVED, SQLITE_LOCK_PENDING, or SQLITE_LOCK_EXCLUSIVE) +into an integer that the pArg argument points to. +This capability is only available if SQLite is compiled with SQLITE_DEBUG.
+ +
+ +The SQLITE_FCNTL_SIZE_HINT opcode is used by SQLite to give the VFS +layer a hint of how large the database file will grow to be during the +current transaction. This hint is not guaranteed to be accurate but it +is often close. The underlying VFS might choose to preallocate database +file space based on this hint in order to help writes to the database +file run faster.
+ +
+ +The SQLITE_FCNTL_SIZE_LIMIT opcode is used by in-memory VFS that +implements sqlite3_deserialize() to set an upper bound on the size +of the in-memory database. The argument is a pointer to a sqlite3_int64. +If the integer pointed to is negative, then it is filled in with the +current limit. Otherwise the limit is set to the larger of the value +of the integer pointed to and the current database size. The integer +pointed to is set to the new limit.
+ +
+ +The SQLITE_FCNTL_CHUNK_SIZE opcode is used to request that the VFS +extends and truncates the database file in chunks of a size specified +by the user. The fourth argument to sqlite3_file_control() should +point to an integer (type int) containing the new chunk-size to use +for the nominated database. Allocating database file space in large +chunks (say 1MB at a time), may reduce file-system fragmentation and +improve performance on some systems.
+ +
+ +The SQLITE_FCNTL_FILE_POINTER opcode is used to obtain a pointer +to the sqlite3_file object associated with a particular database +connection. See also SQLITE_FCNTL_JOURNAL_POINTER.
+ +
+ +The SQLITE_FCNTL_JOURNAL_POINTER opcode is used to obtain a pointer +to the sqlite3_file object associated with the journal file (either +the rollback journal or the write-ahead log) for a particular database +connection. See also SQLITE_FCNTL_FILE_POINTER.
+ +
+ +No longer in use.
+ +
+ +The SQLITE_FCNTL_SYNC opcode is generated internally by SQLite and +sent to the VFS immediately before the xSync method is invoked on a +database file descriptor. Or, if the xSync method is not invoked +because the user has configured SQLite with +PRAGMA synchronous=OFF it is invoked in place +of the xSync method. In most cases, the pointer argument passed with +this file-control is NULL. However, if the database file is being synced +as part of a multi-database commit, the argument points to a nul-terminated +string containing the transactions super-journal file name. VFSes that +do not need this signal should silently ignore this opcode. Applications +should not call sqlite3_file_control() with this opcode as doing so may +disrupt the operation of the specialized VFSes that do require it.
+ +
+ +The SQLITE_FCNTL_COMMIT_PHASETWO opcode is generated internally by SQLite +and sent to the VFS after a transaction has been committed immediately +but before the database is unlocked. VFSes that do not need this signal +should silently ignore this opcode. Applications should not call +sqlite3_file_control() with this opcode as doing so may disrupt the +operation of the specialized VFSes that do require it.
+ +
+ +The SQLITE_FCNTL_WIN32_AV_RETRY opcode is used to configure automatic +retry counts and intervals for certain disk I/O operations for the +windows VFS in order to provide robustness in the presence of +anti-virus programs. By default, the windows VFS will retry file read, +file write, and file delete operations up to 10 times, with a delay +of 25 milliseconds before the first retry and with the delay increasing +by an additional 25 milliseconds with each subsequent retry. This +opcode allows these two values (10 retries and 25 milliseconds of delay) +to be adjusted. The values are changed for all database connections +within the same process. The argument is a pointer to an array of two +integers where the first integer is the new retry count and the second +integer is the delay. If either integer is negative, then the setting +is not changed but instead the prior value of that setting is written +into the array entry, allowing the current retry settings to be +interrogated. The zDbName parameter is ignored.
+ +
+ +The SQLITE_FCNTL_PERSIST_WAL opcode is used to set or query the +persistent Write Ahead Log setting. By default, the auxiliary +write ahead log (WAL file) and shared memory +files used for transaction control +are automatically deleted when the latest connection to the database +closes. Setting persistent WAL mode causes those files to persist after +close. Persisting the files is useful when other processes that do not +have write permission on the directory containing the database file want +to read the database file, as the WAL and shared memory files must exist +in order for the database to be readable. The fourth parameter to +sqlite3_file_control() for this opcode should be a pointer to an integer. +That integer is 0 to disable persistent WAL mode or 1 to enable persistent +WAL mode. If the integer is -1, then it is overwritten with the current +WAL persistence setting.
+ +
+ +The SQLITE_FCNTL_POWERSAFE_OVERWRITE opcode is used to set or query the +persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting +determines the SQLITE_IOCAP_POWERSAFE_OVERWRITE bit of the +xDeviceCharacteristics methods. The fourth parameter to +sqlite3_file_control() for this opcode should be a pointer to an integer. +That integer is 0 to disable zero-damage mode or 1 to enable zero-damage +mode. If the integer is -1, then it is overwritten with the current +zero-damage mode setting.
+ +
+ +The SQLITE_FCNTL_OVERWRITE opcode is invoked by SQLite after opening +a write transaction to indicate that, unless it is rolled back for some +reason, the entire database file will be overwritten by the current +transaction. This is used by VACUUM operations.
+ +
+ +The SQLITE_FCNTL_VFSNAME opcode can be used to obtain the names of +all VFSes in the VFS stack. The names are of all VFS shims and the +final bottom-level VFS are written into memory obtained from +sqlite3_malloc() and the result is stored in the char* variable +that the fourth parameter of sqlite3_file_control() points to. +The caller is responsible for freeing the memory when done. As with +all file-control actions, there is no guarantee that this will actually +do anything. Callers should initialize the char* variable to a NULL +pointer in case this file-control is not implemented. This file-control +is intended for diagnostic use only.
+ +
+ +The SQLITE_FCNTL_VFS_POINTER opcode finds a pointer to the top-level +VFSes currently in use. The argument X in +sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be +of type "sqlite3_vfs **". This opcodes will set *X +to a pointer to the top-level VFS. +When there are multiple VFS shims in the stack, this opcode finds the +upper-most shim only.
+ +
+ +Whenever a PRAGMA statement is parsed, an SQLITE_FCNTL_PRAGMA +file control is sent to the open sqlite3_file object corresponding +to the database file to which the pragma statement refers. The argument +to the SQLITE_FCNTL_PRAGMA file control is an array of +pointers to strings (char**) in which the second element of the array +is the name of the pragma and the third element is the argument to the +pragma or NULL if the pragma has no argument. The handler for an +SQLITE_FCNTL_PRAGMA file control can optionally make the first element +of the char** argument point to a string obtained from sqlite3_mprintf() +or the equivalent and that string will become the result of the pragma or +the error message if the pragma fails. If the +SQLITE_FCNTL_PRAGMA file control returns SQLITE_NOTFOUND, then normal +PRAGMA processing continues. If the SQLITE_FCNTL_PRAGMA +file control returns SQLITE_OK, then the parser assumes that the +VFS has handled the PRAGMA itself and the parser generates a no-op +prepared statement if result string is NULL, or that returns a copy +of the result string if the string is non-NULL. +If the SQLITE_FCNTL_PRAGMA file control returns +any result code other than SQLITE_OK or SQLITE_NOTFOUND, that means +that the VFS encountered an error while handling the PRAGMA and the +compilation of the PRAGMA fails with an error. The SQLITE_FCNTL_PRAGMA +file control occurs at the beginning of pragma statement analysis and so +it is able to override built-in PRAGMA statements.
+ +
+ +The SQLITE_FCNTL_BUSYHANDLER +file-control may be invoked by SQLite on the database file handle +shortly after it is opened in order to provide a custom VFS with access +to the connection's busy-handler callback. The argument is of type (void**) +- an array of two (void *) values. The first (void *) actually points +to a function of type (int (*)(void *)). In order to invoke the connection's +busy-handler, this function should be invoked with the second (void *) in +the array as the only argument. If it returns non-zero, then the operation +should be retried. If it returns zero, the custom VFS should abandon the +current operation.
+ +
+ +Applications can invoke the SQLITE_FCNTL_TEMPFILENAME file-control +to have SQLite generate a +temporary filename using the same algorithm that is followed to generate +temporary filenames for TEMP tables and other internal uses. The +argument should be a char** which will be filled with the filename +written into memory obtained from sqlite3_malloc(). The caller should +invoke sqlite3_free() on the result to avoid a memory leak.
+ +
+ +The SQLITE_FCNTL_MMAP_SIZE file control is used to query or set the +maximum number of bytes that will be used for memory-mapped I/O. +The argument is a pointer to a value of type sqlite3_int64 that +is an advisory maximum number of bytes in the file to memory map. The +pointer is overwritten with the old value. The limit is not changed if +the value originally pointed to is negative, and so the current limit +can be queried by passing in a pointer to a negative number. This +file-control is used internally to implement PRAGMA mmap_size.
+ +
+ +The SQLITE_FCNTL_TRACE file control provides advisory information +to the VFS about what the higher layers of the SQLite stack are doing. +This file control is used by some VFS activity tracing shims. +The argument is a zero-terminated string. Higher layers in the +SQLite stack may generate instances of this file control if +the SQLITE_USE_FCNTL_TRACE compile-time option is enabled.
+ +
+ +The SQLITE_FCNTL_HAS_MOVED file control interprets its argument as a +pointer to an integer and it writes a boolean into that integer depending +on whether or not the file has been renamed, moved, or deleted since it +was first opened.
+ +
+ +The SQLITE_FCNTL_WIN32_GET_HANDLE opcode can be used to obtain the +underlying native file handle associated with a file handle. This file +control interprets its argument as a pointer to a native file handle and +writes the resulting value there.
+ +
+ +The SQLITE_FCNTL_WIN32_SET_HANDLE opcode is used for debugging. This +opcode causes the xFileControl method to swap the file handle with the one +pointed to by the pArg argument. This capability is used during testing +and only needs to be supported when SQLITE_TEST is defined.
+ +
+ +The SQLITE_FCNTL_WAL_BLOCK is a signal to the VFS layer that it might +be advantageous to block on the next WAL lock if the lock is not immediately +available. The WAL subsystem issues this signal during rare +circumstances in order to fix a problem with priority inversion. +Applications should not use this file-control.
+ +
+ +The SQLITE_FCNTL_ZIPVFS opcode is implemented by zipvfs only. All other +VFS should return SQLITE_NOTFOUND for this opcode.
+ +
+ +The SQLITE_FCNTL_RBU opcode is implemented by the special VFS used by +the RBU extension only. All other VFS should return SQLITE_NOTFOUND for +this opcode.
+ +
+ +If the SQLITE_FCNTL_BEGIN_ATOMIC_WRITE opcode returns SQLITE_OK, then +the file descriptor is placed in "batch write mode", which +means all subsequent write operations will be deferred and done +atomically at the next SQLITE_FCNTL_COMMIT_ATOMIC_WRITE. Systems +that do not support batch atomic writes will return SQLITE_NOTFOUND. +Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to +the closing SQLITE_FCNTL_COMMIT_ATOMIC_WRITE or +SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE, SQLite will make +no VFS interface calls on the same sqlite3_file file descriptor +except for calls to the xWrite method and the xFileControl method +with SQLITE_FCNTL_SIZE_HINT.
+ +
+ +The SQLITE_FCNTL_COMMIT_ATOMIC_WRITE opcode causes all write +operations since the previous successful call to +SQLITE_FCNTL_BEGIN_ATOMIC_WRITE to be performed atomically. +This file control returns SQLITE_OK if and only if the writes were +all performed successfully and have been committed to persistent storage. +Regardless of whether or not it is successful, this file control takes +the file descriptor out of batch write mode so that all subsequent +write operations are independent. +SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without +a prior successful call to SQLITE_FCNTL_BEGIN_ATOMIC_WRITE.
+ +
+ +The SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE opcode causes all write +operations since the previous successful call to +SQLITE_FCNTL_BEGIN_ATOMIC_WRITE to be rolled back. +This file control takes the file descriptor out of batch write mode +so that all subsequent write operations are independent. +SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without +a prior successful call to SQLITE_FCNTL_BEGIN_ATOMIC_WRITE.
+ +
+ +The SQLITE_FCNTL_LOCK_TIMEOUT opcode is used to configure a VFS +to block for up to M milliseconds before failing when attempting to +obtain a file lock using the xLock or xShmLock methods of the VFS. +The parameter is a pointer to a 32-bit signed integer that contains +the value that M is to be set to. Before returning, the 32-bit signed +integer is overwritten with the previous value of M.
+ +
+ +The SQLITE_FCNTL_DATA_VERSION opcode is used to detect changes to +a database file. The argument is a pointer to a 32-bit unsigned integer. +The "data version" for the pager is written into the pointer. The +"data version" changes whenever any change occurs to the corresponding +database file, either through SQL statements on the same database +connection or through transactions committed by separate database +connections possibly in other processes. The sqlite3_total_changes() +interface can be used to find if any database on the connection has changed, +but that interface responds to changes on TEMP as well as MAIN and does +not provide a mechanism to detect changes to MAIN only. Also, the +sqlite3_total_changes() interface responds to internal changes only and +omits changes made by other database connections. The +PRAGMA data_version command provides a mechanism to detect changes to +a single attached database that occur due to other database connections, +but omits changes implemented by the database connection on which it is +called. This file control is the only mechanism to detect changes that +happen either internally or externally and that are associated with +a particular attached database.
+ +
+ +The SQLITE_FCNTL_CKPT_START opcode is invoked from within a checkpoint +in wal mode before the client starts to copy pages from the wal +file to the database file.
+ +
+ +The SQLITE_FCNTL_CKPT_DONE opcode is invoked from within a checkpoint +in wal mode after the client has finished copying pages from the wal +file to the database file, but before the *-shm file is updated to +record the fact that the pages have been checkpointed.
+ +
+ +The EXPERIMENTAL SQLITE_FCNTL_EXTERNAL_READER opcode is used to detect +whether or not there is a database client in another process with a wal-mode +transaction open on the database or not. It is only available on unix.The +(void*) argument passed with this file-control should be a pointer to a +value of type (int). The integer value is set to 1 if the database is a wal +mode database and there exists at least one client in another process that +currently has an SQL transaction open on the database. It is set to 0 if +the database is not a wal-mode db, or if there is no such connection in any +other process. This opcode cannot be used to detect transactions opened +by clients within the current process, only within other processes.
+ +
+ +The SQLITE_FCNTL_CKSM_FILE opcode is for use internally by the +checksum VFS shim only.
+ +
+ +If there is currently no transaction open on the database, and the +database is not a temp db, then the SQLITE_FCNTL_RESET_CACHE file-control +purges the contents of the in-memory page cache. If there is an open +transaction, or if the db is a temp-db, this opcode is a no-op, not an error. +

See also lists of + Objects, + Constants, and + Functions.

+ -- cgit v1.2.3