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