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