Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


SQLITE_FCNTL_LOCKSTATE(3)  Library Functions Manual  SQLITE_FCNTL_LOCKSTATE(3)

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, SQLITE_FCNTL_BEGIN_ATOMIC_WRITE,
     SQLITE_FCNTL_COMMIT_ATOMIC_WRITE, SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE,
     SQLITE_FCNTL_LOCK_TIMEOUT, SQLITE_FCNTL_DATA_VERSION,
     SQLITE_FCNTL_SIZE_LIMIT, SQLITE_FCNTL_CKPT_DONE,
     SQLITE_FCNTL_RESERVE_BYTES, SQLITE_FCNTL_CKPT_START,
     SQLITE_FCNTL_EXTERNAL_READER, SQLITE_FCNTL_CKSM_FILE,
     SQLITE_FCNTL_RESET_CACHE - standard file control opcodes

SYNOPSIS
     #include <sqlite3.h>

     #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
     #define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE
     #define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE
     #define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE
     #define SQLITE_FCNTL_LOCK_TIMEOUT
     #define SQLITE_FCNTL_DATA_VERSION
     #define SQLITE_FCNTL_SIZE_LIMIT
     #define SQLITE_FCNTL_CKPT_DONE
     #define SQLITE_FCNTL_RESERVE_BYTES
     #define SQLITE_FCNTL_CKPT_START
     #define SQLITE_FCNTL_EXTERNAL_READER
     #define SQLITE_FCNTL_CKSM_FILE
     #define SQLITE_FCNTL_RESET_CACHE

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 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 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 super-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 (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.

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

        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.

        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.

        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.

        The SQLITE_FCNTL_LOCK_TIMEOUT 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_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.

IMPLEMENTATION NOTES
     These declarations were extracted from the interface documentation at
     line 862.

     #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
     #define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE     31
     #define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE    32
     #define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE  33
     #define SQLITE_FCNTL_LOCK_TIMEOUT           34
     #define SQLITE_FCNTL_DATA_VERSION           35
     #define SQLITE_FCNTL_SIZE_LIMIT             36
     #define SQLITE_FCNTL_CKPT_DONE              37
     #define SQLITE_FCNTL_RESERVE_BYTES          38
     #define SQLITE_FCNTL_CKPT_START             39
     #define SQLITE_FCNTL_EXTERNAL_READER        40
     #define SQLITE_FCNTL_CKSM_FILE              41
     #define SQLITE_FCNTL_RESET_CACHE            42

SEE ALSO
     sqlite3_deserialize(3), sqlite3_file(3), sqlite3_file_control(3),
     sqlite3_io_methods(3), sqlite3_malloc(3), sqlite3_mprintf(3),
     sqlite3_total_changes(3), sqlite3_vfs(3), sqlite_int64(3),
     SQLITE_IOCAP_ATOMIC(3), SQLITE_LOCK_NONE(3), SQLITE_OK(3)

NetBSD 10.99                    August 24, 2023                   NetBSD 10.99