Small. Fast. Reliable.
Choose any three.
#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
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 used during testing and is only available when the SQLITE_TEST
compile-time option is used.
-
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_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 master-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 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 connections 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 connections
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.
-
Application 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.
See also lists of
Objects,
Constants, and
Functions.