1.Dd March 11, 2017 2.Dt SQLITE3_VFS 3 3.Os 4.Sh NAME 5.Nm sqlite3_vfs , 6.Nm sqlite3_syscall_ptr , 7.Nm sqlite3_vfs 8.Nd OS Interface Object 9.Sh SYNOPSIS 10.Vt typedef struct sqlite3_vfs sqlite3_vfs; 11.Vt typedef void (*sqlite3_syscall_ptr)(void); 12.Vt struct sqlite3_vfs ; 13.Sh DESCRIPTION 14An instance of the sqlite3_vfs object defines the interface between 15the SQLite core and the underlying operating system. 16The "vfs" in the name of the object stands for "virtual file system". 17See the VFS documentation for further information. 18.Pp 19The value of the iVersion field is initially 1 but may be larger in 20future versions of SQLite. 21Additional fields may be appended to this object when the iVersion 22value is increased. 23Note that the structure of the sqlite3_vfs object changes in the transaction 24between SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was 25not modified. 26.Pp 27The szOsFile field is the size of the subclassed sqlite3_file 28structure used by this VFS. 29mxPathname is the maximum length of a pathname in this VFS. 30.Pp 31Registered sqlite3_vfs objects are kept on a linked list formed by 32the pNext pointer. 33The sqlite3_vfs_register() and sqlite3_vfs_unregister() 34interfaces manage this list in a thread-safe way. 35The sqlite3_vfs_find() interface searches the list. 36Neither the application code nor the VFS implementation should use 37the pNext pointer. 38.Pp 39The pNext field is the only field in the sqlite3_vfs structure that 40SQLite will ever modify. 41SQLite will only access or modify this field while holding a particular 42static mutex. 43The application should never modify anything within the sqlite3_vfs 44object once the object has been registered. 45.Pp 46The zName field holds the name of the VFS module. 47The name must be unique across all VFS modules. 48.Pp 49SQLite guarantees that the zFilename parameter to xOpen is either a 50NULL pointer or string obtained from xFullPathname() with an optional 51suffix added. 52If a suffix is added to the zFilename parameter, it will consist of 53a single "-" character followed by no more than 11 alphanumeric and/or 54"-" characters. 55SQLite further guarantees that the string will be valid and unchanged 56until xClose() is called. 57Because of the previous sentence, the sqlite3_file can 58safely store a pointer to the filename if it needs to remember the 59filename for some reason. 60If the zFilename parameter to xOpen is a NULL pointer then xOpen must 61invent its own temporary name for the file. 62Whenever the xFilename parameter is NULL it will also be the case that 63the flags parameter will include SQLITE_OPEN_DELETEONCLOSE. 64.Pp 65The flags argument to xOpen() includes all bits set in the flags argument 66to sqlite3_open_v2(). 67Or if sqlite3_open() or sqlite3_open16() 68is used, then flags includes at least SQLITE_OPEN_READWRITE 69| SQLITE_OPEN_CREATE. 70If xOpen() opens a file read-only then it sets *pOutFlags to include 71SQLITE_OPEN_READONLY. 72Other bits in *pOutFlags may be set. 73.Pp 74SQLite will also add one of the following flags to the xOpen() call, 75depending on the object being opened: 76.Bl -bullet 77.It 78SQLITE_OPEN_MAIN_DB 79.It 80SQLITE_OPEN_MAIN_JOURNAL 81.It 82SQLITE_OPEN_TEMP_DB 83.It 84SQLITE_OPEN_TEMP_JOURNAL 85.It 86SQLITE_OPEN_TRANSIENT_DB 87.It 88SQLITE_OPEN_SUBJOURNAL 89.It 90SQLITE_OPEN_MASTER_JOURNAL 91.It 92SQLITE_OPEN_WAL 93.El 94.Pp 95The file I/O implementation can use the object type flags to change 96the way it deals with files. 97For example, an application that does not care about crash recovery 98or rollback might make the open of a journal file a no-op. 99Writes to this journal would also be no-ops, and any attempt to read 100the journal would return SQLITE_IOERR. 101Or the implementation might recognize that a database file will be 102doing page-aligned sector reads and writes in a random order and set 103up its I/O subsystem accordingly. 104.Pp 105SQLite might also add one of the following flags to the xOpen method: 106.Bl -bullet 107.It 108SQLITE_OPEN_DELETEONCLOSE 109.It 110SQLITE_OPEN_EXCLUSIVE 111.El 112.Pp 113The SQLITE_OPEN_DELETEONCLOSE flag means the 114file should be deleted when it is closed. 115The SQLITE_OPEN_DELETEONCLOSE will be set 116for TEMP databases and their journals, transient databases, and subjournals. 117.Pp 118The SQLITE_OPEN_EXCLUSIVE flag is always used 119in conjunction with the SQLITE_OPEN_CREATE flag, 120which are both directly analogous to the O_EXCL and O_CREAT flags of 121the POSIX open() API. 122The SQLITE_OPEN_EXCLUSIVE flag, when paired with the SQLITE_OPEN_CREATE, 123is used to indicate that file should always be created, and that it 124is an error if it already exists. 125It is <i>not</i> used to indicate the file should be opened for exclusive 126access. 127.Pp 128At least szOsFile bytes of memory are allocated by SQLite to hold the 129sqlite3_file structure passed as the third argument to 130xOpen. 131The xOpen method does not have to allocate the structure; it should 132just fill it in. 133Note that the xOpen method must set the sqlite3_file.pMethods to either 134a valid sqlite3_io_methods object or to NULL. 135xOpen must do this even if the open fails. 136SQLite expects that the sqlite3_file.pMethods element will be valid 137after xOpen returns regardless of the success or failure of the xOpen 138call. 139.Pp 140The flags argument to xAccess() may be SQLITE_ACCESS_EXISTS 141to test for the existence of a file, or SQLITE_ACCESS_READWRITE 142to test whether a file is readable and writable, or SQLITE_ACCESS_READ 143to test whether a file is at least readable. 144The file can be a directory. 145.Pp 146SQLite will always allocate at least mxPathname+1 bytes for the output 147buffer xFullPathname. 148The exact size of the output buffer is also passed as a parameter to 149both methods. 150If the output buffer is not large enough, SQLITE_CANTOPEN 151should be returned. 152Since this is handled as a fatal error by SQLite, vfs implementations 153should endeavor to prevent this by setting mxPathname to a sufficiently 154large value. 155.Pp 156The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64() 157interfaces are not strictly a part of the filesystem, but they are 158included in the VFS structure for completeness. 159The xRandomness() function attempts to return nBytes bytes of good-quality 160randomness into zOut. 161The return value is the actual number of bytes of randomness obtained. 162The xSleep() method causes the calling thread to sleep for at least 163the number of microseconds given. 164The xCurrentTime() method returns a Julian Day Number for the current 165date and time as a floating point value. 166The xCurrentTimeInt64() method returns, as an integer, the Julian Day 167Number multiplied by 86400000 (the number of milliseconds in a 24-hour 168day). 169SQLite will use the xCurrentTimeInt64() method to get the current date 170and time if that method is available (if iVersion is 2 or greater and 171the function pointer is not NULL) and will fall back to xCurrentTime() 172if xCurrentTimeInt64() is unavailable. 173.Pp 174The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces 175are not used by the SQLite core. 176These optional interfaces are provided by some VFSes to facilitate 177testing of the VFS code. 178By overriding system calls with functions under its control, a test 179program can simulate faults and error conditions that would otherwise 180be difficult or impossible to induce. 181The set of system calls that can be overridden varies from one VFS 182to another, and from one version of the same VFS to the next. 183Applications that use these interfaces must be prepared for any or 184all of these interfaces to be NULL or for their behavior to change 185from one release to the next. 186Applications must not attempt to access any of these methods if the 187iVersion of the VFS is less than 3. 188.Sh SEE ALSO 189.Xr sqlite3_file 3 , 190.Xr sqlite3_io_methods 3 , 191.Xr sqlite3_open 3 , 192.Xr sqlite3_vfs_find 3 , 193.Xr SQLITE_ACCESS_EXISTS 3 , 194.Xr SQLITE_OK 3 , 195.Xr SQLITE_OPEN_READONLY 3 196