NAME
sqlite3_io_methods,
sqlite3_io_methods
—
OS Interface File Virtual Methods Object
SYNOPSIS
typedef struct sqlite3_io_methods sqlite3_io_methods;
struct sqlite3_io_methods;
DESCRIPTION
Every file opened by the sqlite3_vfs.xOpen method populates an sqlite3_file
object (or, more commonly, a subclass of the sqlite3_file object) with a
pointer to an instance of this object. This object defines the methods used to
perform various operations against the open file represented by the
sqlite3_file object.
If the sqlite3_vfs.xOpen method sets the sqlite3_file.pMethods element to a
non-NULL pointer, then the sqlite3_io_methods.xClose method may be invoked
even if the sqlite3_vfs.xOpen reported that it failed. The only way to prevent
a call to xClose following a failed sqlite3_vfs.xOpen is for the
sqlite3_vfs.xOpen to set the sqlite3_file.pMethods element to NULL.
The flags argument to xSync may be one of SQLITE_SYNC_NORMAL or
SQLITE_SYNC_FULL. The first choice is the normal fsync(). The second choice is
a Mac OS X style fullsync. The SQLITE_SYNC_DATAONLY flag may be ORed in to
indicate that only the data of the file and not its inode needs to be synced.
The integer values to xLock() and xUnlock() are one of
- SQLITE_LOCK_NONE,
- SQLITE_LOCK_SHARED,
- SQLITE_LOCK_RESERVED,
- SQLITE_LOCK_PENDING, or
- SQLITE_LOCK_EXCLUSIVE.
xLock() increases the lock. xUnlock() decreases the lock. The
xCheckReservedLock() method checks whether any database connection, either in
this process or in some other process, is holding a RESERVED, PENDING, or
EXCLUSIVE lock on the file. It returns true if such a lock exists and false
otherwise.
The xFileControl() method is a generic interface that allows custom VFS
implementations to directly control an open file using the
sqlite3_file_control() interface. The second "op" argument is an
integer opcode. The third argument is a generic pointer intended to point to a
structure that may contain arguments or space in which to write return values.
Potential uses for xFileControl() might be functions to enable blocking locks
with timeouts, to change the locking strategy (for example to use dot-file
locks), to inquire about the status of a lock, or to break stale locks. The
SQLite core reserves all opcodes less than 100 for its own use. A list of
opcodes less than 100 is available. Applications that define a custom
xFileControl method should use opcodes greater than 100 to avoid conflicts.
VFS implementations should return SQLITE_NOTFOUND for file control opcodes
that they do not recognize.
The xSectorSize() method returns the sector size of the device that underlies
the file. The sector size is the minimum write that can be performed without
disturbing other bytes in the file. The xDeviceCharacteristics() method
returns a bit vector describing behaviors of the underlying device:
- SQLITE_IOCAP_ATOMIC
- SQLITE_IOCAP_ATOMIC512
- SQLITE_IOCAP_ATOMIC1K
- SQLITE_IOCAP_ATOMIC2K
- SQLITE_IOCAP_ATOMIC4K
- SQLITE_IOCAP_ATOMIC8K
- SQLITE_IOCAP_ATOMIC16K
- SQLITE_IOCAP_ATOMIC32K
- SQLITE_IOCAP_ATOMIC64K
- SQLITE_IOCAP_SAFE_APPEND
- SQLITE_IOCAP_SEQUENTIAL
- SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
- SQLITE_IOCAP_POWERSAFE_OVERWRITE
- SQLITE_IOCAP_IMMUTABLE
The SQLITE_IOCAP_ATOMIC property means that all writes of any size are atomic.
The SQLITE_IOCAP_ATOMICnnn values mean that writes of blocks that are nnn
bytes in size and are aligned to an address which is an integer multiple of
nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means that when data is
appended to a file, the data is appended first then the size of the file is
extended, never the other way around. The SQLITE_IOCAP_SEQUENTIAL property
means that information is written to disk in the same order as calls to
xWrite().
If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill in the unread
portions of the buffer with zeros. A VFS that fails to zero-fill short reads
might seem to work. However, failure to zero-fill short reads will eventually
lead to database corruption.
SEE ALSO
SQLITE_FCNTL_LOCKSTATE(3),
sqlite3_file(3),
sqlite3_file_control(3),
SQLITE_IOCAP_ATOMIC(3),
SQLITE_LOCK_NONE(3),
SQLITE_OK(3),
SQLITE_SYNC_NORMAL(3)