diff options
Diffstat (limited to 'www/c3ref/io_methods.html')
| -rw-r--r-- | www/c3ref/io_methods.html | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/www/c3ref/io_methods.html b/www/c3ref/io_methods.html new file mode 100644 index 0000000..67ddcd0 --- /dev/null +++ b/www/c3ref/io_methods.html @@ -0,0 +1,252 @@ +<!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 File Virtual Methods 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_io_methods --> +<div class=nosearch> +<a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a> +<h2>OS Interface File Virtual Methods Object</h2> +</div> +<blockquote><pre> +typedef struct sqlite3_io_methods sqlite3_io_methods; +struct sqlite3_io_methods { + int iVersion; + int (*xClose)(sqlite3_file*); + int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst); + int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst); + int (*xTruncate)(sqlite3_file*, sqlite3_int64 size); + int (*xSync)(sqlite3_file*, int flags); + int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize); + int (*xLock)(sqlite3_file*, int); + int (*xUnlock)(sqlite3_file*, int); + int (*xCheckReservedLock)(sqlite3_file*, int *pResOut); + int (*xFileControl)(sqlite3_file*, int op, void *pArg); + int (*xSectorSize)(sqlite3_file*); + int (*xDeviceCharacteristics)(sqlite3_file*); + /* Methods above are valid for version 1 */ + int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**); + int (*xShmLock)(sqlite3_file*, int offset, int n, int flags); + void (*xShmBarrier)(sqlite3_file*); + int (*xShmUnmap)(sqlite3_file*, int deleteFlag); + /* Methods above are valid for version 2 */ + int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp); + int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p); + /* Methods above are valid for version 3 */ + /* Additional methods may be added in future releases */ +}; +</pre></blockquote> +<p> +Every file opened by the <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method populates an +<a href="../c3ref/file.html">sqlite3_file</a> object (or, more commonly, a subclass of the +<a href="../c3ref/file.html">sqlite3_file</a> object) with a pointer to an instance of this object. +This object defines the methods used to perform various operations +against the open file represented by the <a href="../c3ref/file.html">sqlite3_file</a> object.</p> + +<p>If the <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method sets the sqlite3_file.pMethods element +to a non-NULL pointer, then the sqlite3_io_methods.xClose method +may be invoked even if the <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> reported that it failed. The +only way to prevent a call to xClose following a failed <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> +is for the <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> to set the sqlite3_file.pMethods element +to NULL.</p> + +<p>The flags argument to xSync may be one of <a href="../c3ref/c_sync_dataonly.html">SQLITE_SYNC_NORMAL</a> or +<a href="../c3ref/c_sync_dataonly.html">SQLITE_SYNC_FULL</a>. The first choice is the normal fsync(). +The second choice is a Mac OS X style fullsync. The <a href="../c3ref/c_sync_dataonly.html">SQLITE_SYNC_DATAONLY</a> +flag may be ORed in to indicate that only the data of the file +and not its inode needs to be synced.</p> + +<p>The integer values to xLock() and xUnlock() are one of +<ul> +<li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_NONE</a>, +<li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a>, +<li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_RESERVED</a>, +<li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_PENDING</a>, or +<li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_EXCLUSIVE</a>. +</ul> +xLock() upgrades the database file lock. In other words, xLock() moves the +database file lock in the direction NONE toward EXCLUSIVE. The argument to +xLock() is always on of SHARED, RESERVED, PENDING, or EXCLUSIVE, never +SQLITE_LOCK_NONE. If the database file lock is already at or above the +requested lock, then the call to xLock() is a no-op. +xUnlock() downgrades the database file lock to either SHARED or NONE. +to xUnlock() is a no-op. +The xCheckReservedLock() method checks whether any database connection, +either in this process or in some other process, is holding a RESERVED, +PENDING, or EXCLUSIVE lock on the file. It returns true +if such a lock exists and false otherwise.</p> + +<p>The xFileControl() method is a generic interface that allows custom +VFS implementations to directly control an open file using the +<a href="../c3ref/file_control.html">sqlite3_file_control()</a> interface. The second "op" argument is an +integer opcode. The third argument is a generic pointer intended to +point to a structure that may contain arguments or space in which to +write return values. Potential uses for xFileControl() might be +functions to enable blocking locks with timeouts, to change the +locking strategy (for example to use dot-file locks), to inquire +about the status of a lock, or to break stale locks. The SQLite +core reserves all opcodes less than 100 for its own use. +A <a href="../c3ref/c_fcntl_begin_atomic_write.html">list of opcodes</a> less than 100 is available. +Applications that define a custom xFileControl method should use opcodes +greater than 100 to avoid conflicts. VFS implementations should +return <a href="../rescode.html#notfound">SQLITE_NOTFOUND</a> for file control opcodes that they do not +recognize.</p> + +<p>The xSectorSize() method returns the sector size of the +device that underlies the file. The sector size is the +minimum write that can be performed without disturbing +other bytes in the file. The xDeviceCharacteristics() +method returns a bit vector describing behaviors of the +underlying device:</p> + +<p><ul> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC</a> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC512</a> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC1K</a> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC2K</a> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC4K</a> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC8K</a> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC16K</a> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC32K</a> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC64K</a> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SAFE_APPEND</a> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SEQUENTIAL</a> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN</a> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_POWERSAFE_OVERWRITE</a> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_IMMUTABLE</a> +<li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_BATCH_ATOMIC</a> +</ul></p> + +<p>The SQLITE_IOCAP_ATOMIC property means that all writes of +any size are atomic. The SQLITE_IOCAP_ATOMICnnn values +mean that writes of blocks that are nnn bytes in size and +are aligned to an address which is an integer multiple of +nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means +that when data is appended to a file, the data is appended +first then the size of the file is extended, never the other +way around. The SQLITE_IOCAP_SEQUENTIAL property means that +information is written to disk in the same order as calls +to xWrite().</p> + +<p>If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill +in the unread portions of the buffer with zeros. A VFS that +fails to zero-fill short reads might seem to work. However, +failure to zero-fill short reads will eventually lead to +database corruption. +</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> + |