313 lines
15 KiB
HTML
313 lines
15 KiB
HTML
<!DOCTYPE html>
|
|
<html><head>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
|
<link href="../sqlite.css" rel="stylesheet">
|
|
<title>OS Interface Object</title>
|
|
<!-- path=../ -->
|
|
</head>
|
|
<body>
|
|
<div class=nosearch>
|
|
<a href="../index.html">
|
|
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0">
|
|
</a>
|
|
<div><!-- IE hack to prevent disappearing logo --></div>
|
|
<div class="tagline desktoponly">
|
|
Small. Fast. Reliable.<br>Choose any three.
|
|
</div>
|
|
<div class="menu mainmenu">
|
|
<ul>
|
|
<li><a href="../index.html">Home</a>
|
|
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
|
|
<li class='wideonly'><a href='../about.html'>About</a>
|
|
<li class='desktoponly'><a href="../docs.html">Documentation</a>
|
|
<li class='desktoponly'><a href="../download.html">Download</a>
|
|
<li class='wideonly'><a href='../copyright.html'>License</a>
|
|
<li class='desktoponly'><a href="../support.html">Support</a>
|
|
<li class='desktoponly'><a href="../prosupport.html">Purchase</a>
|
|
<li class='search' id='search_menubutton'>
|
|
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
|
|
</ul>
|
|
</div>
|
|
<div class="menu submenu" id="submenu">
|
|
<ul>
|
|
<li><a href='../about.html'>About</a>
|
|
<li><a href='../docs.html'>Documentation</a>
|
|
<li><a href='../download.html'>Download</a>
|
|
<li><a href='../support.html'>Support</a>
|
|
<li><a href='../prosupport.html'>Purchase</a>
|
|
</ul>
|
|
</div>
|
|
<div class="searchmenu" id="searchmenu">
|
|
<form method="GET" action="../search">
|
|
<select name="s" id="searchtype">
|
|
<option value="d">Search Documentation</option>
|
|
<option value="c">Search Changelog</option>
|
|
</select>
|
|
<input type="text" name="q" id="searchbox" value="">
|
|
<input type="submit" value="Go">
|
|
</form>
|
|
</div>
|
|
</div>
|
|
<script>
|
|
function toggle_div(nm) {
|
|
var w = document.getElementById(nm);
|
|
if( w.style.display=="block" ){
|
|
w.style.display = "none";
|
|
}else{
|
|
w.style.display = "block";
|
|
}
|
|
}
|
|
function toggle_search() {
|
|
var w = document.getElementById("searchmenu");
|
|
if( w.style.display=="block" ){
|
|
w.style.display = "none";
|
|
} else {
|
|
w.style.display = "block";
|
|
setTimeout(function(){
|
|
document.getElementById("searchbox").focus()
|
|
}, 30);
|
|
}
|
|
}
|
|
function div_off(nm){document.getElementById(nm).style.display="none";}
|
|
window.onbeforeunload = function(e){div_off("submenu");}
|
|
/* Disable the Search feature if we are not operating from CGI, since */
|
|
/* Search is accomplished using CGI and will not work without it. */
|
|
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
|
|
document.getElementById("search_menubutton").style.display = "none";
|
|
}
|
|
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
|
|
function hideorshow(btn,obj){
|
|
var x = document.getElementById(obj);
|
|
var b = document.getElementById(btn);
|
|
if( x.style.display!='none' ){
|
|
x.style.display = 'none';
|
|
b.innerHTML='show';
|
|
}else{
|
|
x.style.display = '';
|
|
b.innerHTML='hide';
|
|
}
|
|
return false;
|
|
}
|
|
</script>
|
|
</div>
|
|
<!-- keywords: sqlite3_vfs -->
|
|
<div class=nosearch>
|
|
<a href="intro.html"><h2>SQLite C Interface</h2></a>
|
|
<h2>OS Interface Object</h2>
|
|
</div>
|
|
<blockquote><pre>
|
|
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*, 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 *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.
|
|
*/
|
|
};
|
|
</pre></blockquote>
|
|
<p>
|
|
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 <a href="../vfs.html">VFS documentation</a> for further information.</p>
|
|
|
|
<p>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 <a href="../releaselog/3_5_0.html">version 3.5.0</a> on 2007-09-04, then increased to 2
|
|
with SQLite <a href="../releaselog/3_7_0.html">version 3.7.0</a> on 2010-07-21, and then increased
|
|
to 3 with SQLite <a href="../releaselog/3_7_6.html">version 3.7.6</a> on 2011-04-12. 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 <a href="../releaselog/3_5_9.html">version 3.5.9</a> to <a href="../releaselog/3_6_0.html">version 3.6.0</a> on 2008-07-16
|
|
and yet the iVersion field was not increased.</p>
|
|
|
|
<p>The szOsFile field is the size of the subclassed <a href="../c3ref/file.html">sqlite3_file</a>
|
|
structure used by this VFS. mxPathname is the maximum length of
|
|
a pathname in this VFS.</p>
|
|
|
|
<p>Registered sqlite3_vfs objects are kept on a linked list formed by
|
|
the pNext pointer. The <a href="../c3ref/vfs_find.html">sqlite3_vfs_register()</a>
|
|
and <a href="../c3ref/vfs_find.html">sqlite3_vfs_unregister()</a> interfaces manage this list
|
|
in a thread-safe way. The <a href="../c3ref/vfs_find.html">sqlite3_vfs_find()</a> interface
|
|
searches the list. Neither the application code nor the VFS
|
|
implementation should use the pNext pointer.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>The zName field holds the name of the VFS module. The name must
|
|
be unique across all VFS modules.</p>
|
|
|
|
<p><a name="sqlite3vfsxopen"></a>
|
|
|
|
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 <a href="../c3ref/file.html">sqlite3_file</a> 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 <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a>.</p>
|
|
|
|
<p>The flags argument to xOpen() includes all bits set in
|
|
the flags argument to <a href="../c3ref/open.html">sqlite3_open_v2()</a>. Or if <a href="../c3ref/open.html">sqlite3_open()</a>
|
|
or <a href="../c3ref/open.html">sqlite3_open16()</a> is used, then flags includes at least
|
|
<a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READWRITE</a> | <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_CREATE</a>.
|
|
If xOpen() opens a file read-only then it sets *pOutFlags to
|
|
include <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_READONLY</a>. Other bits in *pOutFlags may be set.</p>
|
|
|
|
<p>SQLite will also add one of the following flags to the xOpen()
|
|
call, depending on the object being opened:</p>
|
|
|
|
<p><ul>
|
|
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_MAIN_DB</a>
|
|
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_MAIN_JOURNAL</a>
|
|
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_TEMP_DB</a>
|
|
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_TEMP_JOURNAL</a>
|
|
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_TRANSIENT_DB</a>
|
|
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_SUBJOURNAL</a>
|
|
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_SUPER_JOURNAL</a>
|
|
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_WAL</a>
|
|
</ul></p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>SQLite might also add one of the following flags to the xOpen method:</p>
|
|
|
|
<p><ul>
|
|
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a>
|
|
<li> <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_EXCLUSIVE</a>
|
|
</ul></p>
|
|
|
|
<p>The <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a> flag means the file should be
|
|
deleted when it is closed. The <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_DELETEONCLOSE</a>
|
|
will be set for TEMP databases and their journals, transient
|
|
databases, and subjournals.</p>
|
|
|
|
<p>The <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_EXCLUSIVE</a> flag is always used in conjunction
|
|
with the <a href="../c3ref/c_open_autoproxy.html">SQLITE_OPEN_CREATE</a> 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 <i>not</i> used to indicate the file should be opened
|
|
for exclusive access.</p>
|
|
|
|
<p>At least szOsFile bytes of memory are allocated by SQLite
|
|
to hold the <a href="../c3ref/file.html">sqlite3_file</a> 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 <a href="../c3ref/io_methods.html">sqlite3_io_methods</a> 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.</p>
|
|
|
|
<p><a name="sqlite3vfsxaccess"></a>
|
|
|
|
The flags argument to xAccess() may be <a href="../c3ref/c_access_exists.html">SQLITE_ACCESS_EXISTS</a>
|
|
to test for the existence of a file, or <a href="../c3ref/c_access_exists.html">SQLITE_ACCESS_READWRITE</a> to
|
|
test whether a file is readable and writable, or <a href="../c3ref/c_access_exists.html">SQLITE_ACCESS_READ</a>
|
|
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 <a href="../rescode.html#ok">SQLITE_OK</a> 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.</p>
|
|
|
|
<p>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, <a href="../rescode.html#cantopen">SQLITE_CANTOPEN</a> 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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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.
|
|
</p><p>See also lists of
|
|
<a href="objlist.html">Objects</a>,
|
|
<a href="constlist.html">Constants</a>, and
|
|
<a href="funclist.html">Functions</a>.</p>
|