1.Dd December 19, 2018 2.Dt SQLITE3_IO_METHODS 3 3.Os 4.Sh NAME 5.Nm sqlite3_io_methods , 6.Nm sqlite3_io_methods 7.Nd OS Interface File Virtual Methods Object 8.Sh SYNOPSIS 9.Vt typedef struct sqlite3_io_methods sqlite3_io_methods; 10.Vt struct sqlite3_io_methods ; 11.Sh DESCRIPTION 12Every file opened by the sqlite3_vfs.xOpen method 13populates an sqlite3_file object (or, more commonly, a 14subclass of the sqlite3_file object) with a pointer to 15an instance of this object. 16This object defines the methods used to perform various operations 17against the open file represented by the sqlite3_file object. 18.Pp 19If the sqlite3_vfs.xOpen method sets the sqlite3_file.pMethods 20element to a non-NULL pointer, then the sqlite3_io_methods.xClose method 21may be invoked even if the sqlite3_vfs.xOpen reported 22that it failed. 23The only way to prevent a call to xClose following a failed sqlite3_vfs.xOpen 24is for the sqlite3_vfs.xOpen to set the sqlite3_file.pMethods 25element to NULL. 26.Pp 27The flags argument to xSync may be one of SQLITE_SYNC_NORMAL 28or SQLITE_SYNC_FULL. 29The first choice is the normal fsync(). 30The second choice is a Mac OS X style fullsync. 31The SQLITE_SYNC_DATAONLY flag may be ORed in to 32indicate that only the data of the file and not its inode needs to 33be synced. 34.Pp 35The integer values to xLock() and xUnlock() are one of 36.Bl -bullet 37.It 38SQLITE_LOCK_NONE, 39.It 40SQLITE_LOCK_SHARED, 41.It 42SQLITE_LOCK_RESERVED, 43.It 44SQLITE_LOCK_PENDING, or 45.It 46SQLITE_LOCK_EXCLUSIVE. 47.El 48.Pp 49xLock() increases the lock. 50xUnlock() decreases the lock. 51The xCheckReservedLock() method checks whether any database connection, 52either in this process or in some other process, is holding a RESERVED, 53PENDING, or EXCLUSIVE lock on the file. 54It returns true if such a lock exists and false otherwise. 55.Pp 56The xFileControl() method is a generic interface that allows custom 57VFS implementations to directly control an open file using the sqlite3_file_control() 58interface. 59The second "op" argument is an integer opcode. 60The third argument is a generic pointer intended to point to a structure 61that may contain arguments or space in which to write return values. 62Potential uses for xFileControl() might be functions to enable blocking 63locks with timeouts, to change the locking strategy (for example to 64use dot-file locks), to inquire about the status of a lock, or to break 65stale locks. 66The SQLite core reserves all opcodes less than 100 for its own use. 67A list of opcodes less than 100 is available. 68Applications that define a custom xFileControl method should use opcodes 69greater than 100 to avoid conflicts. 70VFS implementations should return SQLITE_NOTFOUND for 71file control opcodes that they do not recognize. 72.Pp 73The xSectorSize() method returns the sector size of the device that 74underlies the file. 75The sector size is the minimum write that can be performed without 76disturbing other bytes in the file. 77The xDeviceCharacteristics() method returns a bit vector describing 78behaviors of the underlying device: 79.Bl -bullet 80.It 81SQLITE_IOCAP_ATOMIC 82.It 83SQLITE_IOCAP_ATOMIC512 84.It 85SQLITE_IOCAP_ATOMIC1K 86.It 87SQLITE_IOCAP_ATOMIC2K 88.It 89SQLITE_IOCAP_ATOMIC4K 90.It 91SQLITE_IOCAP_ATOMIC8K 92.It 93SQLITE_IOCAP_ATOMIC16K 94.It 95SQLITE_IOCAP_ATOMIC32K 96.It 97SQLITE_IOCAP_ATOMIC64K 98.It 99SQLITE_IOCAP_SAFE_APPEND 100.It 101SQLITE_IOCAP_SEQUENTIAL 102.It 103SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 104.It 105SQLITE_IOCAP_POWERSAFE_OVERWRITE 106.It 107SQLITE_IOCAP_IMMUTABLE 108.It 109SQLITE_IOCAP_BATCH_ATOMIC 110.El 111.Pp 112The SQLITE_IOCAP_ATOMIC property means that all writes of any size 113are atomic. 114The SQLITE_IOCAP_ATOMICnnn values mean that writes of blocks that are 115nnn bytes in size and are aligned to an address which is an integer 116multiple of nnn are atomic. 117The SQLITE_IOCAP_SAFE_APPEND value means that when data is appended 118to a file, the data is appended first then the size of the file is 119extended, never the other way around. 120The SQLITE_IOCAP_SEQUENTIAL property means that information is written 121to disk in the same order as calls to xWrite(). 122.Pp 123If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill in the 124unread portions of the buffer with zeros. 125A VFS that fails to zero-fill short reads might seem to work. 126However, failure to zero-fill short reads will eventually lead to database 127corruption. 128.Sh SEE ALSO 129.Xr SQLITE_FCNTL_LOCKSTATE 3 , 130.Xr sqlite3_file 3 , 131.Xr sqlite3_file_control 3 , 132.Xr SQLITE_IOCAP_ATOMIC 3 , 133.Xr SQLITE_LOCK_NONE 3 , 134.Xr SQLITE_OK 3 , 135.Xr SQLITE_SYNC_NORMAL 3 136