Standard File Control Opcodes

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

, 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

SQLITE_FCNTL_FILE_POINTER

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

opcode is used to obtain a pointer to the

SQLITE_FCNTL_JOURNAL_POINTER

object associated with a particular database connection. See also

The

SQLITE_FCNTL_JOURNAL_POINTER

opcode is used to obtain a pointer to the

SQLITE_FCNTL_FILE_POINTER

object associated with the journal file (either the

rollback journal

or the

write-ahead log

) for a particular database connection. See also

The SQLITE_FCNTL_SYNC_OMITTED file-control is no longer used.

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

SQLITE_FCNTL_COMMIT_PHASETWO

with this opcode as doing so may disrupt the operation of the specialized VFSes that do require it.

The

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

SQLITE_FCNTL_WIN32_AV_RETRY

with this opcode as doing so may disrupt the operation of the specialized VFSes that do require it.

The

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

SQLITE_FCNTL_POWERSAFE_OVERWRITE

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

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

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 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

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 opcode 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

statement is parsed, an

file control is sent to the open

object corresponding to the database file to which the pragma statement refers. The argument to the

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

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

file control returns

SQLITE_NOTFOUND

, then normal

processing continues. If the

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

file control returns any result code other than

SQLITE_OK

SQLITE_NOTFOUND

, that means that the VFS encountered an error while handling the

and the compilation of the PRAGMA fails with an error. The

file control occurs at the beginning of pragma statement analysis and so it is able to override built-in

SQLITE_FCNTL_TEMPFILENAME

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

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_NULL_IO

opcode sets the low-level file descriptor or file handle for the

object such that it will no longer read or write to the database file.

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_COMMIT_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

. 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

SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE

, SQLite will make no VFS interface calls on the same

SQLITE_FCNTL_COMMIT_ATOMIC_WRITE

file descriptor except for calls to the xWrite method and the xFileControl method with

SQLITE_FCNTL_SIZE_HINT

The

opcode causes all write operations since the previous successful call to

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_ROLLBACK_ATOMIC_WRITE

The

opcode causes all write operations since the previous successful call to

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_LOCK_TIMEOUT

The

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_BLOCK_ON_CONNECT

opcode is used to configure the VFS to block when taking a SHARED lock to connect to a wal mode database. This is used to implement the functionality associated with SQLITE_SETLK_BLOCK_ON_CONNECT.

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.

The

SQLITE_FCNTL_FILESTAT

opcode returns low-level diagnostic information about the

objects used access the database and journal files for the given schema. The fourth parameter to