sqlite/man/SQLITE_FCNTL_LOCKSTATE.3

.Dd December 19, 2018
.Dt SQLITE_FCNTL_LOCKSTATE 3
.Os
.Sh NAME
.Nm SQLITE_FCNTL_LOCKSTATE ,
.Nm SQLITE_FCNTL_GET_LOCKPROXYFILE ,
.Nm SQLITE_FCNTL_SET_LOCKPROXYFILE ,
.Nm SQLITE_FCNTL_LAST_ERRNO ,
.Nm SQLITE_FCNTL_SIZE_HINT ,
.Nm SQLITE_FCNTL_CHUNK_SIZE ,
.Nm SQLITE_FCNTL_FILE_POINTER ,
.Nm SQLITE_FCNTL_SYNC_OMITTED ,
.Nm SQLITE_FCNTL_WIN32_AV_RETRY ,
.Nm SQLITE_FCNTL_PERSIST_WAL ,
.Nm SQLITE_FCNTL_OVERWRITE ,
.Nm SQLITE_FCNTL_VFSNAME ,
.Nm SQLITE_FCNTL_POWERSAFE_OVERWRITE ,
.Nm SQLITE_FCNTL_PRAGMA ,
.Nm SQLITE_FCNTL_BUSYHANDLER ,
.Nm SQLITE_FCNTL_TEMPFILENAME ,
.Nm SQLITE_FCNTL_MMAP_SIZE ,
.Nm SQLITE_FCNTL_TRACE ,
.Nm SQLITE_FCNTL_HAS_MOVED ,
.Nm SQLITE_FCNTL_SYNC ,
.Nm SQLITE_FCNTL_COMMIT_PHASETWO ,
.Nm SQLITE_FCNTL_WIN32_SET_HANDLE ,
.Nm SQLITE_FCNTL_WAL_BLOCK ,
.Nm SQLITE_FCNTL_ZIPVFS ,
.Nm SQLITE_FCNTL_RBU ,
.Nm SQLITE_FCNTL_VFS_POINTER ,
.Nm SQLITE_FCNTL_JOURNAL_POINTER ,
.Nm SQLITE_FCNTL_WIN32_GET_HANDLE ,
.Nm SQLITE_FCNTL_PDB ,
.Nm SQLITE_FCNTL_BEGIN_ATOMIC_WRITE ,
.Nm SQLITE_FCNTL_COMMIT_ATOMIC_WRITE ,
.Nm SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE ,
.Nm SQLITE_FCNTL_LOCK_TIMEOUT ,
.Nm SQLITE_FCNTL_DATA_VERSION
.Nd Standard File Control Opcodes
.Sh SYNOPSIS
.Fd #define SQLITE_FCNTL_LOCKSTATE
.Fd #define SQLITE_FCNTL_GET_LOCKPROXYFILE
.Fd #define SQLITE_FCNTL_SET_LOCKPROXYFILE
.Fd #define SQLITE_FCNTL_LAST_ERRNO
.Fd #define SQLITE_FCNTL_SIZE_HINT
.Fd #define SQLITE_FCNTL_CHUNK_SIZE
.Fd #define SQLITE_FCNTL_FILE_POINTER
.Fd #define SQLITE_FCNTL_SYNC_OMITTED
.Fd #define SQLITE_FCNTL_WIN32_AV_RETRY
.Fd #define SQLITE_FCNTL_PERSIST_WAL
.Fd #define SQLITE_FCNTL_OVERWRITE
.Fd #define SQLITE_FCNTL_VFSNAME
.Fd #define SQLITE_FCNTL_POWERSAFE_OVERWRITE
.Fd #define SQLITE_FCNTL_PRAGMA
.Fd #define SQLITE_FCNTL_BUSYHANDLER
.Fd #define SQLITE_FCNTL_TEMPFILENAME
.Fd #define SQLITE_FCNTL_MMAP_SIZE
.Fd #define SQLITE_FCNTL_TRACE
.Fd #define SQLITE_FCNTL_HAS_MOVED
.Fd #define SQLITE_FCNTL_SYNC
.Fd #define SQLITE_FCNTL_COMMIT_PHASETWO
.Fd #define SQLITE_FCNTL_WIN32_SET_HANDLE
.Fd #define SQLITE_FCNTL_WAL_BLOCK
.Fd #define SQLITE_FCNTL_ZIPVFS
.Fd #define SQLITE_FCNTL_RBU
.Fd #define SQLITE_FCNTL_VFS_POINTER
.Fd #define SQLITE_FCNTL_JOURNAL_POINTER
.Fd #define SQLITE_FCNTL_WIN32_GET_HANDLE
.Fd #define SQLITE_FCNTL_PDB
.Fd #define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE
.Fd #define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE
.Fd #define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE
.Fd #define SQLITE_FCNTL_LOCK_TIMEOUT
.Fd #define SQLITE_FCNTL_DATA_VERSION
.Sh DESCRIPTION
These integer constants are opcodes for the xFileControl method of
the sqlite3_io_methods object and for the sqlite3_file_control()
interface.
.Bl -bullet
.It
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.
.It
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.
.It
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.
.It
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.
.It
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.
.It
No longer in use.
.It
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.
.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.
.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.
.It
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.
.It
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.
.It
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.
.It
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.
.It
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.
.It
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.
.It
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.
.It
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.
.It
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.
.It
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.
.It
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.
.It
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.
.It
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.
.It
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.
.It
The SQLITE_FCNTL_ZIPVFS opcode is implemented by
zipvfs only.
All other VFS should return SQLITE_NOTFOUND for this opcode.
.It
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.
.It
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.
.It
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.
.It
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.
.It
The SQLITE_FCNTL_LOCK_TIMEOUT opcode causes
attempts to obtain a file lock using the xLock or xShmLock methods
of the VFS to wait for up to M milliseconds before failing, where M
is the single unsigned integer parameter.
.It
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 provide 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.
.El
.Pp
.Sh SEE ALSO
.Xr sqlite3_file 3 ,
.Xr sqlite3_file_control 3 ,
.Xr sqlite3_malloc 3 ,
.Xr sqlite3_io_methods 3 ,
.Xr sqlite3_malloc 3 ,
.Xr sqlite3_mprintf 3 ,
.Xr sqlite3_total_changes 3 ,
.Xr sqlite3_vfs 3 ,
.Xr SQLITE_FCNTL_LOCKSTATE 3 ,
.Xr SQLITE_IOCAP_ATOMIC 3 ,
.Xr SQLITE_LOCK_NONE 3 ,
.Xr SQLITE_OK 3