326 lines
14 KiB
Groff
326 lines
14 KiB
Groff
.Dd March 11, 2017
|
|
.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
|
|
.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
|
|
.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 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.
|
|
.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 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.
|
|
.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_vfs 3 ,
|
|
.Xr SQLITE_FCNTL_LOCKSTATE 3 ,
|
|
.Xr SQLITE_IOCAP_ATOMIC 3 ,
|
|
.Xr SQLITE_LOCK_NONE 3 ,
|
|
.Xr SQLITE_OK 3
|