1.Dd January 24, 2024 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.In sqlite3.h 10.Vt typedef struct sqlite3_io_methods sqlite3_io_methods; 11.Vt struct sqlite3_io_methods ; 12.Sh DESCRIPTION 13Every file opened by the sqlite3_vfs.xOpen method 14populates an sqlite3_file object (or, more commonly, a 15subclass of the sqlite3_file object) with a pointer to 16an instance of this object. 17This object defines the methods used to perform various operations 18against the open file represented by the sqlite3_file object. 19.Pp 20If the sqlite3_vfs.xOpen method sets the sqlite3_file.pMethods 21element to a non-NULL pointer, then the sqlite3_io_methods.xClose method 22may be invoked even if the sqlite3_vfs.xOpen reported 23that it failed. 24The only way to prevent a call to xClose following a failed sqlite3_vfs.xOpen 25is for the sqlite3_vfs.xOpen to set the sqlite3_file.pMethods 26element to NULL. 27.Pp 28The flags argument to xSync may be one of SQLITE_SYNC_NORMAL 29or SQLITE_SYNC_FULL. 30The first choice is the normal fsync(). 31The second choice is a Mac OS X style fullsync. 32The SQLITE_SYNC_DATAONLY flag may be ORed in to 33indicate that only the data of the file and not its inode needs to 34be synced. 35.Pp 36The integer values to xLock() and xUnlock() are one of 37.Bl -bullet 38.It 39SQLITE_LOCK_NONE, 40.It 41SQLITE_LOCK_SHARED, 42.It 43SQLITE_LOCK_RESERVED, 44.It 45SQLITE_LOCK_PENDING, or 46.It 47SQLITE_LOCK_EXCLUSIVE. 48.El 49.Pp 50xLock() upgrades the database file lock. 51In other words, xLock() moves the database file lock in the direction 52NONE toward EXCLUSIVE. 53The argument to xLock() is always on of SHARED, RESERVED, PENDING, 54or EXCLUSIVE, never SQLITE_LOCK_NONE. 55If the database file lock is already at or above the requested lock, 56then the call to xLock() is a no-op. 57xUnlock() downgrades the database file lock to either SHARED or NONE. 58If the lock is already at or below the requested lock state, then the 59call to xUnlock() is a no-op. 60The xCheckReservedLock() method checks whether any database connection, 61either in this process or in some other process, is holding a RESERVED, 62PENDING, or EXCLUSIVE lock on the file. 63It returns true if such a lock exists and false otherwise. 64.Pp 65The xFileControl() method is a generic interface that allows custom 66VFS implementations to directly control an open file using the 67.Fn sqlite3_file_control 68interface. 69The second "op" argument is an integer opcode. 70The third argument is a generic pointer intended to point to a structure 71that may contain arguments or space in which to write return values. 72Potential uses for xFileControl() might be functions to enable blocking 73locks with timeouts, to change the locking strategy (for example to 74use dot-file locks), to inquire about the status of a lock, or to break 75stale locks. 76The SQLite core reserves all opcodes less than 100 for its own use. 77A list of opcodes less than 100 is available. 78Applications that define a custom xFileControl method should use opcodes 79greater than 100 to avoid conflicts. 80VFS implementations should return SQLITE_NOTFOUND for 81file control opcodes that they do not recognize. 82.Pp 83The xSectorSize() method returns the sector size of the device that 84underlies the file. 85The sector size is the minimum write that can be performed without 86disturbing other bytes in the file. 87The xDeviceCharacteristics() method returns a bit vector describing 88behaviors of the underlying device: 89.Bl -bullet 90.It 91SQLITE_IOCAP_ATOMIC 92.It 93SQLITE_IOCAP_ATOMIC512 94.It 95SQLITE_IOCAP_ATOMIC1K 96.It 97SQLITE_IOCAP_ATOMIC2K 98.It 99SQLITE_IOCAP_ATOMIC4K 100.It 101SQLITE_IOCAP_ATOMIC8K 102.It 103SQLITE_IOCAP_ATOMIC16K 104.It 105SQLITE_IOCAP_ATOMIC32K 106.It 107SQLITE_IOCAP_ATOMIC64K 108.It 109SQLITE_IOCAP_SAFE_APPEND 110.It 111SQLITE_IOCAP_SEQUENTIAL 112.It 113SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 114.It 115SQLITE_IOCAP_POWERSAFE_OVERWRITE 116.It 117SQLITE_IOCAP_IMMUTABLE 118.It 119SQLITE_IOCAP_BATCH_ATOMIC 120.El 121.Pp 122The SQLITE_IOCAP_ATOMIC property means that all writes of any size 123are atomic. 124The SQLITE_IOCAP_ATOMICnnn values mean that writes of blocks that are 125nnn bytes in size and are aligned to an address which is an integer 126multiple of nnn are atomic. 127The SQLITE_IOCAP_SAFE_APPEND value means that when data is appended 128to a file, the data is appended first then the size of the file is 129extended, never the other way around. 130The SQLITE_IOCAP_SEQUENTIAL property means that information is written 131to disk in the same order as calls to xWrite(). 132.Pp 133If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill in the 134unread portions of the buffer with zeros. 135A VFS that fails to zero-fill short reads might seem to work. 136However, failure to zero-fill short reads will eventually lead to database 137corruption. 138.Sh IMPLEMENTATION NOTES 139These declarations were extracted from the 140interface documentation at line 734. 141.Bd -literal 142typedef struct sqlite3_io_methods sqlite3_io_methods; 143struct sqlite3_io_methods { 144 int iVersion; 145 int (*xClose)(sqlite3_file*); 146 int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst); 147 int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst); 148 int (*xTruncate)(sqlite3_file*, sqlite3_int64 size); 149 int (*xSync)(sqlite3_file*, int flags); 150 int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize); 151 int (*xLock)(sqlite3_file*, int); 152 int (*xUnlock)(sqlite3_file*, int); 153 int (*xCheckReservedLock)(sqlite3_file*, int *pResOut); 154 int (*xFileControl)(sqlite3_file*, int op, void *pArg); 155 int (*xSectorSize)(sqlite3_file*); 156 int (*xDeviceCharacteristics)(sqlite3_file*); 157 /* Methods above are valid for version 1 */ 158 int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**); 159 int (*xShmLock)(sqlite3_file*, int offset, int n, int flags); 160 void (*xShmBarrier)(sqlite3_file*); 161 int (*xShmUnmap)(sqlite3_file*, int deleteFlag); 162 /* Methods above are valid for version 2 */ 163 int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp); 164 int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p); 165 /* Methods above are valid for version 3 */ 166 /* Additional methods may be added in future releases */ 167}; 168.Ed 169.Sh SEE ALSO 170.Xr sqlite3_file 3 , 171.Xr sqlite3_file_control 3 , 172.Xr SQLITE_FCNTL_LOCKSTATE 3 , 173.Xr SQLITE_IOCAP_ATOMIC 3 , 174.Xr SQLITE_LOCK_NONE 3 , 175.Xr SQLITE_OK 3 , 176.Xr SQLITE_SYNC_NORMAL 3 177