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