sqlite/man/sqlite3_vfs.3

.Dd January 24, 2024
.Dt SQLITE3_VFS 3
.Os
.Sh NAME
.Nm sqlite3_vfs ,
.Nm sqlite3_syscall_ptr ,
.Nm sqlite3_vfs
.Nd OS interface object
.Sh SYNOPSIS
.In sqlite3.h
.Vt typedef struct sqlite3_vfs sqlite3_vfs;
.Vt typedef void (*sqlite3_syscall_ptr)(void);
.Vt struct sqlite3_vfs ;
.Sh DESCRIPTION
An instance of the sqlite3_vfs 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".
See the VFS documentation for further information.
.Pp
The VFS interface is sometimes extended by adding new methods onto
the end.
Each time such an extension occurs, the iVersion field is incremented.
The iVersion value started out as 1 in SQLite version 3.5.0
on dateof:3.5.0, then increased to 2 with SQLite version 3.7.0
on dateof:3.7.0, and then increased to 3 with SQLite version 3.7.6
on dateof:3.7.6.
Additional fields may be appended to the sqlite3_vfs object and the
iVersion value may increase again in future versions of SQLite.
Note that due to an oversight, the structure of the sqlite3_vfs object
changed in the transition from SQLite version 3.5.9 to
version 3.6.0 on dateof:3.6.0 and yet the
iVersion field was not increased.
.Pp
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.
.Pp
Registered sqlite3_vfs objects are kept on a linked list formed by
the pNext pointer.
The
.Fn sqlite3_vfs_register
and
.Fn sqlite3_vfs_unregister
interfaces manage this list in a thread-safe way.
The
.Fn sqlite3_vfs_find
interface searches the list.
Neither the application code nor the VFS implementation should use
the pNext pointer.
.Pp
The pNext field is the only field 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.
.Pp
The zName field holds the name of the VFS module.
The name must be unique across all VFS modules.
.Pp
SQLite guarantees that the zFilename parameter to xOpen is either a
NULL pointer or string obtained from xFullPathname() with an optional
suffix added.
If a suffix is added to the zFilename parameter, it will consist of
a single "-" character followed by no more than 11 alphanumeric and/or
"-" characters.
SQLite further guarantees that the string will be valid and unchanged
until xClose() is called.
Because of the previous sentence, the sqlite3_file can
safely store a pointer to the filename if it needs to remember the
filename for some reason.
If the zFilename parameter to xOpen is a NULL pointer then xOpen must
invent its own temporary name for the file.
Whenever the xFilename parameter is NULL it will also be the case that
the flags parameter will include SQLITE_OPEN_DELETEONCLOSE.
.Pp
The flags argument to xOpen() includes all bits set in the flags argument
to
.Fn sqlite3_open_v2 .
Or if
.Fn sqlite3_open
or
.Fn sqlite3_open16
is used, then flags includes at least 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.
.Pp
SQLite will also add one of the following flags to the xOpen() call,
depending on the object being opened:
.Bl -bullet
.It
SQLITE_OPEN_MAIN_DB
.It
SQLITE_OPEN_MAIN_JOURNAL
.It
SQLITE_OPEN_TEMP_DB
.It
SQLITE_OPEN_TEMP_JOURNAL
.It
SQLITE_OPEN_TRANSIENT_DB
.It
SQLITE_OPEN_SUBJOURNAL
.It
SQLITE_OPEN_SUPER_JOURNAL
.It
SQLITE_OPEN_WAL
.El
.Pp
The file I/O implementation can use the object type flags to change
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 would also be no-ops, and any attempt to read
the journal would return SQLITE_IOERR.
Or the implementation might recognize that a database file will be
doing page-aligned sector reads and writes in a random order and set
up its I/O subsystem accordingly.
.Pp
SQLite might also add one of the following flags to the xOpen method:
.Bl -bullet
.It
SQLITE_OPEN_DELETEONCLOSE
.It
SQLITE_OPEN_EXCLUSIVE
.El
.Pp
The SQLITE_OPEN_DELETEONCLOSE flag means the
file should be deleted when it is closed.
The SQLITE_OPEN_DELETEONCLOSE will be set
for TEMP databases and their journals, transient databases, and subjournals.
.Pp
The SQLITE_OPEN_EXCLUSIVE flag is always used
in conjunction with the SQLITE_OPEN_CREATE flag,
which are both directly analogous to the O_EXCL and O_CREAT flags of
the POSIX open() API.
The SQLITE_OPEN_EXCLUSIVE flag, when paired with the SQLITE_OPEN_CREATE,
is used to indicate that file should always be created, and that it
is an error if it already exists.
It is \fInot\fP used to indicate the file should be opened for exclusive
access.
.Pp
At least szOsFile bytes of memory are allocated by SQLite to hold the
sqlite3_file structure passed as the third argument to
xOpen.
The xOpen method does not have to allocate the structure; it should
just fill it in.
Note that the xOpen method must set the sqlite3_file.pMethods to either
a valid sqlite3_io_methods object or to NULL.
xOpen must do this even if the open fails.
SQLite expects that the sqlite3_file.pMethods element will be valid
after xOpen returns regardless of the success or failure of the xOpen
call.
.Pp
The flags argument to xAccess() may be SQLITE_ACCESS_EXISTS
to test for the existence of a file, or SQLITE_ACCESS_READWRITE
to test whether a file is readable and writable, or SQLITE_ACCESS_READ
to test whether a file is at least readable.
The SQLITE_ACCESS_READ flag is never actually used and is not implemented
in the built-in VFSes of SQLite.
The file is named by the second argument and can be a directory.
The xAccess method returns SQLITE_OK on success or some non-zero
error code if there is an I/O error or if the name of the file given
in the second argument is illegal.
If SQLITE_OK is returned, then non-zero or zero is written into *pResOut
to indicate whether or not the file is accessible.
.Pp
SQLite will always allocate at least mxPathname+1 bytes for the output
buffer 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.
Since this is handled as a fatal error by SQLite, vfs implementations
should endeavor to prevent this by setting mxPathname to a sufficiently
large value.
.Pp
The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
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 causes 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 as a floating point value.
The xCurrentTimeInt64() method returns, as an integer, the Julian Day
Number multiplied by 86400000 (the number of milliseconds in a 24-hour
day).
SQLite will use the xCurrentTimeInt64() method to get the current date
and time if that method is available (if iVersion is 2 or greater and
the function pointer is not NULL) and will fall back to xCurrentTime()
if xCurrentTimeInt64() is unavailable.
.Pp
The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
are not used by the SQLite core.
These optional interfaces are provided by some VFSes to facilitate
testing of the VFS code.
By overriding system calls with functions under its control, a test
program can simulate faults and error conditions that would otherwise
be difficult or impossible to induce.
The set of system calls that can be overridden varies from one VFS
to another, and from one version of the same VFS to the next.
Applications that use these interfaces must be prepared for any or
all of these interfaces to be NULL or for their behavior to change
from one release to the next.
Applications must not attempt to access any of these methods if the
iVersion of the VFS is less than 3.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 1295.
.Bd -literal
typedef struct sqlite3_vfs sqlite3_vfs;
typedef void (*sqlite3_syscall_ptr)(void);
struct sqlite3_vfs {
  int iVersion;            /* Structure version number (currently 3) */
  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*, sqlite3_filename 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 *pResOut);
  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);
  void (*xDlClose)(sqlite3_vfs*, void*);
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  int (*xSleep)(sqlite3_vfs*, int microseconds);
  int (*xCurrentTime)(sqlite3_vfs*, double*);
  int (*xGetLastError)(sqlite3_vfs*, int, char *);
  /*
  ** The methods above are in version 1 of the sqlite_vfs object
  ** definition.  Those that follow are added in version 2 or later
  */
  int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
  /*
  ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
  ** Those below are for version 3 and greater.
  */
  int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
  sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
  const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
  /*
  ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
  ** New fields may be appended in future versions.  The iVersion
  ** value will increment whenever this happens.
  */
};
.Ed
.Sh SEE ALSO
.Xr sqlite3_file 3 ,
.Xr sqlite3_io_methods 3 ,
.Xr sqlite3_open 3 ,
.Xr sqlite3_vfs_find 3 ,
.Xr SQLITE_ACCESS_EXISTS 3 ,
.Xr SQLITE_OK 3 ,
.Xr SQLITE_OPEN_READONLY 3