Adding upstream version 3.40.1.upstream/3.40.1 upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
author: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-05-05 17:28:19 +0000
committer: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-05-05 17:28:19 +0000
commit: 18657a960e125336f704ea058e25c27bd3900dcb (patch)
tree: 17b438b680ed45a996d7b59951e6aa34023783f2 /www/c3ref/vfs.html
parent: Initial commit. (diff)
download: sqlite3-18657a960e125336f704ea058e25c27bd3900dcb.tar.xz
sqlite3-18657a960e125336f704ea058e25c27bd3900dcb.zip
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..df931fb
--- /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="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="objlist.html">Objects</a>,
+  <a href="constlist.html">Constants</a>, and
+  <a href="funclist.html">Functions</a>.</p>
+
author	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-05-05 17:28:19 +0000
committer	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-05-05 17:28:19 +0000
commit	18657a960e125336f704ea058e25c27bd3900dcb (patch)
tree	17b438b680ed45a996d7b59951e6aa34023783f2 /www/c3ref/vfs.html
parent	Initial commit. (diff)
download	sqlite3-18657a960e125336f704ea058e25c27bd3900dcb.tar.xz sqlite3-18657a960e125336f704ea058e25c27bd3900dcb.zip