NAME
SQLITE_FCNTL_LOCKSTATE,
SQLITE_FCNTL_GET_LOCKPROXYFILE,
SQLITE_FCNTL_SET_LOCKPROXYFILE,
SQLITE_FCNTL_LAST_ERRNO,
SQLITE_FCNTL_SIZE_HINT,
SQLITE_FCNTL_CHUNK_SIZE,
SQLITE_FCNTL_FILE_POINTER,
SQLITE_FCNTL_SYNC_OMITTED,
SQLITE_FCNTL_WIN32_AV_RETRY,
SQLITE_FCNTL_PERSIST_WAL,
SQLITE_FCNTL_OVERWRITE,
SQLITE_FCNTL_VFSNAME,
SQLITE_FCNTL_POWERSAFE_OVERWRITE,
SQLITE_FCNTL_PRAGMA,
SQLITE_FCNTL_BUSYHANDLER,
SQLITE_FCNTL_TEMPFILENAME,
SQLITE_FCNTL_MMAP_SIZE,
SQLITE_FCNTL_TRACE,
SQLITE_FCNTL_HAS_MOVED,
SQLITE_FCNTL_SYNC,
SQLITE_FCNTL_COMMIT_PHASETWO,
SQLITE_FCNTL_WIN32_SET_HANDLE,
SQLITE_FCNTL_WAL_BLOCK,
SQLITE_FCNTL_ZIPVFS,
SQLITE_FCNTL_RBU,
SQLITE_FCNTL_VFS_POINTER,
SQLITE_FCNTL_JOURNAL_POINTER,
SQLITE_FCNTL_WIN32_GET_HANDLE,
SQLITE_FCNTL_PDB —
Standard File
Control Opcodes
SYNOPSIS
#define SQLITE_FCNTL_LOCKSTATE
#define SQLITE_FCNTL_GET_LOCKPROXYFILE
#define SQLITE_FCNTL_SET_LOCKPROXYFILE
#define SQLITE_FCNTL_LAST_ERRNO
#define SQLITE_FCNTL_SIZE_HINT
#define SQLITE_FCNTL_CHUNK_SIZE
#define SQLITE_FCNTL_FILE_POINTER
#define SQLITE_FCNTL_SYNC_OMITTED
#define SQLITE_FCNTL_WIN32_AV_RETRY
#define SQLITE_FCNTL_PERSIST_WAL
#define SQLITE_FCNTL_OVERWRITE
#define SQLITE_FCNTL_VFSNAME
#define SQLITE_FCNTL_POWERSAFE_OVERWRITE
#define SQLITE_FCNTL_PRAGMA
#define SQLITE_FCNTL_BUSYHANDLER
#define SQLITE_FCNTL_TEMPFILENAME
#define SQLITE_FCNTL_MMAP_SIZE
#define SQLITE_FCNTL_TRACE
#define SQLITE_FCNTL_HAS_MOVED
#define SQLITE_FCNTL_SYNC
#define SQLITE_FCNTL_COMMIT_PHASETWO
#define SQLITE_FCNTL_WIN32_SET_HANDLE
#define SQLITE_FCNTL_WAL_BLOCK
#define SQLITE_FCNTL_ZIPVFS
#define SQLITE_FCNTL_RBU
#define SQLITE_FCNTL_VFS_POINTER
#define SQLITE_FCNTL_JOURNAL_POINTER
#define SQLITE_FCNTL_WIN32_GET_HANDLE
#define SQLITE_FCNTL_PDB
DESCRIPTION
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 i 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 <em>not</em> 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
sqlite3_file(3),
sqlite3_file_control(3),
sqlite3_malloc(3),
sqlite3_io_methods(3),
sqlite3_malloc(3),
sqlite3_mprintf(3),
sqlite3_vfs(3),
SQLITE_FCNTL_LOCKSTATE(3),
SQLITE_IOCAP_ATOMIC(3),
SQLITE_LOCK_NONE(3),
SQLITE_OK(3)