Small. Fast. Reliable.
Choose any three.

About Sitemap Documentation Download License News Developers Support

## SQLite C Interface

### OS Interface File Virtual Methods Object

>     typedef struct sqlite3_io_methods sqlite3_io_methods;
>     struct sqlite3_io_methods {
>       int iVersion;
>       int (*xClose)(sqlite3_file*);
>       int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
>       int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
>       int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
>       int (*xSync)(sqlite3_file*, int flags);
>       int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
>       int (*xLock)(sqlite3_file*, int);
>       int (*xUnlock)(sqlite3_file*, int);
>       int (*xCheckReservedLock)(sqlite3_file*);
>       int (*xFileControl)(sqlite3_file*, int op, void *pArg);
>       int (*xSectorSize)(sqlite3_file*);
>       int (*xDeviceCharacteristics)(sqlite3_file*);
>       /* Additional methods may be added in future releases */
>     };

Every file opened by the sqlite3_vfs xOpen method contains a pointer to an instance of the this object. This object defines the methods used to perform various operations against the open file.

The flags argument to xSync may be one of SQLITE_SYNC_NORMAL or SQLITE_SYNC_FULL. The first choice is the normal fsync(). OS-X style fullsync. The SQLITE_SYNC_DATA 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 looks to see if any database connection, either in this process or in some other process, is holding an RESERVED, PENDING, or EXCLUSIVE lock on the file. It returns true if such a lock exists and false if not.

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 which is intended to be a pointer 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 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.

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

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().

See also lists of Objects, Constants, and Functions.

This page last modified 2007/12/14 14:37:57 UTC