Small, Fast, Reliable.
Choose any three.

About Sitemap Documentation Download License News Developers Support

## SQLite C Interface

### OS Interface Object

>     typedef struct sqlite3_vfs sqlite3_vfs;
>     struct sqlite3_vfs {
>       int iVersion;            /* Structure version number */
>       int szOsFile;            /* Size of subclassed sqlite3_file */
>       int mxPathname;          /* Maximum file pathname length */
>       sqlite3_vfs *pNext;      /* Next registered VFS */
>       const char *zName;       /* Name of this virtual file system */
>       void *pAppData;          /* Pointer to application-specific data */
>       int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
>                    int flags, int *pOutFlags);
>       int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
>       int (*xAccess)(sqlite3_vfs*, const char *zName, int flags);
>       int (*xGetTempname)(sqlite3_vfs*, int nOut, char *zOut);
>       int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
>       void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
>       void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
>       void *(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol);
>       void (*xDlClose)(sqlite3_vfs*, void*);
>       int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
>       int (*xSleep)(sqlite3_vfs*, int microseconds);
>       int (*xCurrentTime)(sqlite3_vfs*, double*);
>       /* New fields may be appended in figure versions.  The iVersion
>       ** value will increment whenever this happens. */
>     };

An instance of this object defines the interface between the SQLite core and the underlying operating system. The "vfs" in the name of the object stands for "virtual file system".

The iVersion field is initially 1 but may be larger for future versions of SQLite. Additional fields may be appended to this object when the iVersion value is increased.

The szOsFile field is the size of the subclassed sqlite3_file structure used by this VFS. mxPathname is the maximum length of a pathname in this VFS.

Registered vfs modules are kept on a linked list formed by the pNext pointer. The sqlite3_vfs_register() and sqlite3_vfs_unregister() interfaces manage this list in a thread-safe way. The sqlite3_vfs_find() interface searches the list.

The pNext field is the only fields in the sqlite3_vfs structure that SQLite will ever modify. SQLite will only access or modify this field while holding a particular static mutex. The application should never modify anything within the sqlite3_vfs object once the object has been registered.

The zName field holds the name of the VFS module. The name must be unique across all VFS modules.

SQLite will guarantee that the zFilename string passed to xOpen() is a full pathname as generated by xFullPathname() and that the string will be valid and unchanged until xClose() is called. So the sqlite3_file can store a pointer to the filename if it needs to remember the filename for some reason.

The flags argument to xOpen() is a copy of the flags argument to sqlite3_open_v2(). If sqlite3_open() or sqlite3_open16() is used, then flags is SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE. If xOpen() opens a file read-only then it sets *pOutFlags to include SQLITE_OPEN_READONLY. Other bits in *pOutFlags may be set.

SQLite will also add one of the following flags to the xOpen() call, depending on the object being opened:

- SQLITE_OPEN_MAIN_DB
- SQLITE_OPEN_MAIN_JOURNAL
- SQLITE_OPEN_TEMP_DB
- SQLITE_OPEN_TEMP_JOURNAL
- SQLITE_OPEN_TRANSIENT_DB
- SQLITE_OPEN_SUBJOURNAL
- SQLITE_OPEN_MASTER_JOURNAL

The file I/O implementation can use the object type flags to changes the way it deals with files. For example, an application that does not care about crash recovery or rollback, might make the open of a journal file a no-op. Writes to this journal are also a no-op. Any attempt to read the journal return SQLITE_IOERR. Or the implementation might recognize the a database file will be doing page-aligned sector reads and writes in a random order and set up its I/O subsystem accordingly.

SQLite might also add one of the following flags to the xOpen method:

- SQLITE_OPEN_DELETEONCLOSE
- SQLITE_OPEN_EXCLUSIVE

The SQLITE_OPEN_DELETEONCLOSE flag means the file should be deleted when it is closed. This will always be set for TEMP databases and journals and for subjournals. The SQLITE_OPEN_EXCLUSIVE flag means the file should be opened for exclusive access. This flag is set for all files except for the main database file.

Space to hold the sqlite3_file structure passed as the third argument to xOpen is allocated by caller (the SQLite core). szOsFile bytes are allocated for this object. The xOpen method fills in the allocated space.

The flags argument to xAccess() may be SQLITE_ACCESS_EXISTS to test for the existance of a file, or SQLITE_ACCESS_READWRITE to test to see if a file is readable and writable, or SQLITE_ACCESS_READ to test to see if a file is at least readable. The file can be a directory.

SQLite will always allocate at least mxPathname+1 byte for the output buffers for xGetTempname and xFullPathname. The exact size of the output buffer is also passed as a parameter to both methods. If the output buffer is not large enough, SQLITE_CANTOPEN should be returned. As this is handled as a fatal error by SQLite, vfs implementations should endevour to prevent this by setting mxPathname to a sufficiently large value.

The xRandomness(), xSleep(), and xCurrentTime() interfaces are not strictly a part of the filesystem, but they are included in the VFS structure for completeness. The xRandomness() function attempts to return nBytes bytes of good-quality randomness into zOut. The return value is the actual number of bytes of randomness obtained. The xSleep() method cause the calling thread to sleep for at least the number of microseconds given. The xCurrentTime() method returns a Julian Day Number for the current date and time.

See also lists of Objects, Constants, and Functions.

This page last modified 2007/11/22 00:41:31 UTC