diff options
Diffstat (limited to 'www/c3ref/vfs.html')
| -rw-r--r-- | www/c3ref/vfs.html | 337 |
1 files changed, 337 insertions, 0 deletions
diff --git a/www/c3ref/vfs.html b/www/c3ref/vfs.html new file mode 100644 index 0000000..05155d7 --- /dev/null +++ b/www/c3ref/vfs.html @@ -0,0 +1,337 @@ +<!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; +} +var antiRobot = 0; +function antiRobotGo(){ +if( antiRobot!=3 ) return; +antiRobot = 7; +var j = document.getElementById("mtimelink"); +if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href"); +} +function antiRobotDefense(){ +document.body.onmousedown=function(){ +antiRobot |= 2; +antiRobotGo(); +document.body.onmousedown=null; +} +document.body.onmousemove=function(){ +antiRobot |= 2; +antiRobotGo(); +document.body.onmousemove=null; +} +setTimeout(function(){ +antiRobot |= 1; +antiRobotGo(); +}, 100) +antiRobotGo(); +} +antiRobotDefense(); +</script> +<!-- keywords: sqlite3_vfs --> +<div class=nosearch> +<a href="../c3ref/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*, 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. + */ +}; +</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="../c3ref/objlist.html">Objects</a>, + <a href="../c3ref/constlist.html">Constants</a>, and + <a href="../c3ref/funclist.html">Functions</a>.</p> + |