1.Dd $Mdocdate$ 2.Dt SQLITE_FCNTL_LOCKSTATE 3 3.Os 4.Sh NAME 5.Nm SQLITE_FCNTL_LOCKSTATE , 6.Nm SQLITE_GET_LOCKPROXYFILE , 7.Nm SQLITE_SET_LOCKPROXYFILE , 8.Nm SQLITE_LAST_ERRNO , 9.Nm SQLITE_FCNTL_SIZE_HINT , 10.Nm SQLITE_FCNTL_CHUNK_SIZE , 11.Nm SQLITE_FCNTL_FILE_POINTER , 12.Nm SQLITE_FCNTL_SYNC_OMITTED , 13.Nm SQLITE_FCNTL_WIN32_AV_RETRY , 14.Nm SQLITE_FCNTL_PERSIST_WAL , 15.Nm SQLITE_FCNTL_OVERWRITE , 16.Nm SQLITE_FCNTL_VFSNAME , 17.Nm SQLITE_FCNTL_POWERSAFE_OVERWRITE , 18.Nm SQLITE_FCNTL_PRAGMA , 19.Nm SQLITE_FCNTL_BUSYHANDLER , 20.Nm SQLITE_FCNTL_TEMPFILENAME , 21.Nm SQLITE_FCNTL_MMAP_SIZE , 22.Nm SQLITE_FCNTL_TRACE , 23.Nm SQLITE_FCNTL_HAS_MOVED , 24.Nm SQLITE_FCNTL_SYNC , 25.Nm SQLITE_FCNTL_COMMIT_PHASETWO 26.Nd Standard File Control Opcodes 27.Sh SYNOPSIS 28.Fd #define SQLITE_FCNTL_LOCKSTATE 29.Fd #define SQLITE_GET_LOCKPROXYFILE 30.Fd #define SQLITE_SET_LOCKPROXYFILE 31.Fd #define SQLITE_LAST_ERRNO 32.Fd #define SQLITE_FCNTL_SIZE_HINT 33.Fd #define SQLITE_FCNTL_CHUNK_SIZE 34.Fd #define SQLITE_FCNTL_FILE_POINTER 35.Fd #define SQLITE_FCNTL_SYNC_OMITTED 36.Fd #define SQLITE_FCNTL_WIN32_AV_RETRY 37.Fd #define SQLITE_FCNTL_PERSIST_WAL 38.Fd #define SQLITE_FCNTL_OVERWRITE 39.Fd #define SQLITE_FCNTL_VFSNAME 40.Fd #define SQLITE_FCNTL_POWERSAFE_OVERWRITE 41.Fd #define SQLITE_FCNTL_PRAGMA 42.Fd #define SQLITE_FCNTL_BUSYHANDLER 43.Fd #define SQLITE_FCNTL_TEMPFILENAME 44.Fd #define SQLITE_FCNTL_MMAP_SIZE 45.Fd #define SQLITE_FCNTL_TRACE 46.Fd #define SQLITE_FCNTL_HAS_MOVED 47.Fd #define SQLITE_FCNTL_SYNC 48.Fd #define SQLITE_FCNTL_COMMIT_PHASETWO 49.Sh DESCRIPTION 50These integer constants are opcodes for the xFileControl method of 51the sqlite3_io_methods object and for the sqlite3_file_control() 52interface. 53.Pp 54The SQLITE_FCNTL_LOCKSTATE opcode is used for 55debugging. 56This opcode causes the xFileControl method to write the current state 57of the lock (one of SQLITE_LOCK_NONE, SQLITE_LOCK_SHARED, 58SQLITE_LOCK_RESERVED, SQLITE_LOCK_PENDING, 59or SQLITE_LOCK_EXCLUSIVE) into an integer that 60the pArg argument points to. 61This capability is used during testing and only needs to be supported 62when SQLITE_TEST is defined. 63.Bl -bullet 64.It 65The SQLITE_FCNTL_SIZE_HINT opcode is used by 66SQLite to give the VFS layer a hint of how large the database file 67will grow to be during the current transaction. 68This hint is not guaranteed to be accurate but it is often close. 69The underlying VFS might choose to preallocate database file space 70based on this hint in order to help writes to the database file run 71faster. 72.It 73The SQLITE_FCNTL_CHUNK_SIZE opcode is used to 74request that the VFS extends and truncates the database file in chunks 75of a size specified by the user. 76The fourth argument to sqlite3_file_control() 77should point to an integer (type int) containing the new chunk-size 78to use for the nominated database. 79Allocating database file space in large chunks (say 1MB at a time), 80may reduce file-system fragmentation and improve performance on some 81systems. 82.It 83The SQLITE_FCNTL_FILE_POINTER opcode is used 84to obtain a pointer to the sqlite3_file object associated 85with a particular database connection. 86See the sqlite3_file_control() documentation 87for additional information. 88.It 89No longer in use. 90.It 91The SQLITE_FCNTL_SYNC opcode is generated internally 92by SQLite and sent to the VFS immediately before the xSync method is 93invoked on a database file descriptor. 94Or, if the xSync method is not invoked because the user has configured 95SQLite with PRAGMA synchronous=OFF it is invoked 96in place of the xSync method. 97In most cases, the pointer argument passed with this file-control is 98NULL. 99However, if the database file is being synced as part of a multi-database 100commit, the argument points to a nul-terminated string containing the 101transactions master-journal file name. 102VFSes that do not need this signal should silently ignore this opcode. 103Applications should not call sqlite3_file_control() 104with this opcode as doing so may disrupt the operation of the specialized 105VFSes that do require it. 106.It 107The SQLITE_FCNTL_COMMIT_PHASETWO opcode 108is generated internally by SQLite and sent to the VFS after a transaction 109has been committed immediately but before the database is unlocked. 110VFSes that do not need this signal should silently ignore this opcode. 111Applications should not call sqlite3_file_control() 112with this opcode as doing so may disrupt the operation of the specialized 113VFSes that do require it. 114.It 115The SQLITE_FCNTL_WIN32_AV_RETRY opcode is 116used to configure automatic retry counts and intervals for certain 117disk I/O operations for the windows VFS in order to provide robustness 118in the presence of anti-virus programs. 119By default, the windows VFS will retry file read, file write, and file 120delete operations up to 10 times, with a delay of 25 milliseconds before 121the first retry and with the delay increasing by an additional 25 milliseconds 122with each subsequent retry. 123This opcode allows these two values (10 retries and 25 milliseconds 124of delay) to be adjusted. 125The values are changed for all database connections within the same 126process. 127The argument is a pointer to an array of two integers where the first 128integer i the new retry count and the second integer is the delay. 129If either integer is negative, then the setting is not changed but 130instead the prior value of that setting is written into the array entry, 131allowing the current retry settings to be interrogated. 132The zDbName parameter is ignored. 133.It 134The SQLITE_FCNTL_PERSIST_WAL opcode is used 135to set or query the persistent Write Ahead Log setting. 136By default, the auxiliary write ahead log and shared memory files used 137for transaction control are automatically deleted when the latest connection 138to the database closes. 139Setting persistent WAL mode causes those files to persist after close. 140Persisting the files is useful when other processes that do not have 141write permission on the directory containing the database file want 142to read the database file, as the WAL and shared memory files must 143exist in order for the database to be readable. 144The fourth parameter to sqlite3_file_control() 145for this opcode should be a pointer to an integer. 146That integer is 0 to disable persistent WAL mode or 1 to enable persistent 147WAL mode. 148If the integer is -1, then it is overwritten with the current WAL persistence 149setting. 150.It 151The SQLITE_FCNTL_POWERSAFE_OVERWRITE 152opcode is used to set or query the persistent "powersafe-overwrite" 153or "PSOW" setting. 154The PSOW setting determines the SQLITE_IOCAP_POWERSAFE_OVERWRITE 155bit of the xDeviceCharacteristics methods. 156The fourth parameter to sqlite3_file_control() 157for this opcode should be a pointer to an integer. 158That integer is 0 to disable zero-damage mode or 1 to enable zero-damage 159mode. 160If the integer is -1, then it is overwritten with the current zero-damage 161mode setting. 162.It 163The SQLITE_FCNTL_OVERWRITE opcode is invoked 164by SQLite after opening a write transaction to indicate that, unless 165it is rolled back for some reason, the entire database file will be 166overwritten by the current transaction. 167This is used by VACUUM operations. 168.It 169The SQLITE_FCNTL_VFSNAME opcode can be used to 170obtain the names of all VFSes in the VFS stack. 171The names are of all VFS shims and the final bottom-level VFS are written 172into memory obtained from sqlite3_malloc() and the 173result is stored in the char* variable that the fourth parameter of 174sqlite3_file_control() points to. 175The caller is responsible for freeing the memory when done. 176As with all file-control actions, there is no guarantee that this will 177actually do anything. 178Callers should initialize the char* variable to a NULL pointer in case 179this file-control is not implemented. 180This file-control is intended for diagnostic use only. 181.It 182Whenever a PRAGMA statement is parsed, an SQLITE_FCNTL_PRAGMA 183file control is sent to the open sqlite3_file object corresponding 184to the database file to which the pragma statement refers. 185The argument to the SQLITE_FCNTL_PRAGMA file control 186is an array of pointers to strings (char**) in which the second element 187of the array is the name of the pragma and the third element is the 188argument to the pragma or NULL if the pragma has no argument. 189The handler for an SQLITE_FCNTL_PRAGMA file control 190can optionally make the first element of the char** argument point 191to a string obtained from sqlite3_mprintf() or the 192equivalent and that string will become the result of the pragma or 193the error message if the pragma fails. 194If the SQLITE_FCNTL_PRAGMA file control returns 195SQLITE_NOTFOUND, then normal PRAGMA processing 196continues. 197If the SQLITE_FCNTL_PRAGMA file control returns 198SQLITE_OK, then the parser assumes that the VFS has handled 199the PRAGMA itself and the parser generates a no-op prepared statement. 200If the SQLITE_FCNTL_PRAGMA file control returns 201any result code other than SQLITE_OK or SQLITE_NOTFOUND, 202that means that the VFS encountered an error while handling the PRAGMA 203and the compilation of the PRAGMA fails with an error. 204The SQLITE_FCNTL_PRAGMA file control occurs at the 205beginning of pragma statement analysis and so it is able to override 206built-in PRAGMA statements. 207.It 208The SQLITE_FCNTL_BUSYHANDLER file-control may 209be invoked by SQLite on the database file handle shortly after it is 210opened in order to provide a custom VFS with access to the connections 211busy-handler callback. 212The argument is of type (void **) - an array of two (void *) values. 213The first (void *) actually points to a function of type (int (*)(void 214*)). 215In order to invoke the connections busy-handler, this function should 216be invoked with the second (void *) in the array as the only argument. 217If it returns non-zero, then the operation should be retried. 218If it returns zero, the custom VFS should abandon the current operation. 219.It 220Application can invoke the SQLITE_FCNTL_TEMPFILENAME 221file-control to have SQLite generate a temporary filename using the 222same algorithm that is followed to generate temporary filenames for 223TEMP tables and other internal uses. 224The argument should be a char** which will be filled with the filename 225written into memory obtained from sqlite3_malloc(). 226The caller should invoke sqlite3_free() on the result 227to avoid a memory leak. 228.It 229The SQLITE_FCNTL_MMAP_SIZE file control is used 230to query or set the maximum number of bytes that will be used for memory-mapped 231I/O. 232The argument is a pointer to a value of type sqlite3_int64 that is 233an advisory maximum number of bytes in the file to memory map. 234The pointer is overwritten with the old value. 235The limit is not changed if the value originally pointed to is negative, 236and so the current limit can be queried by passing in a pointer to 237a negative number. 238This file-control is used internally to implement PRAGMA mmap_size. 239.It 240The SQLITE_FCNTL_TRACE file control provides advisory 241information to the VFS about what the higher layers of the SQLite stack 242are doing. 243This file control is used by some VFS activity tracing shims. 244The argument is a zero-terminated string. 245Higher layers in the SQLite stack may generate instances of this file 246control if the SQLITE_USE_FCNTL_TRACE compile-time 247option is enabled. 248.It 249The SQLITE_FCNTL_HAS_MOVED file control interprets 250its argument as a pointer to an integer and it writes a boolean into 251that integer depending on whether or not the file has been renamed, 252moved, or deleted since it was first opened. 253.El 254.Pp 255.Sh SEE ALSO 256.Xr sqlite3_file 3 , 257.Xr sqlite3_file_control 3 , 258.Xr sqlite3_malloc 3 , 259.Xr sqlite3_io_methods 3 , 260.Xr sqlite3_malloc 3 , 261.Xr sqlite3_mprintf 3 , 262.Xr SQLITE_FCNTL_LOCKSTATE 3 , 263.Xr SQLITE_IOCAP_ATOMIC 3 , 264.Xr SQLITE_LOCK_NONE 3 , 265.Xr SQLITE_OK 3 266