Debian Codegraph @

www/c3ref/io_methods.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="../sqlite.css" rel="stylesheet">
6 <title>OS Interface File Virtual Methods Object</title>
7 <!-- path=../ -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="../index.html">
12 <img class="logo" src="../images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="../index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='../about.html'>About</a>
23 <li class='desktoponly'><a href="../docs.html">Documentation</a>
24 <li class='desktoponly'><a href="../download.html">Download</a>
25 <li class='wideonly'><a href='../copyright.html'>License</a>
26 <li class='desktoponly'><a href="../support.html">Support</a>
27 <li class='desktoponly'><a href="../prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='../about.html'>About</a>
35 <li><a href='../docs.html'>Documentation</a>
36 <li><a href='../download.html'>Download</a>
37 <li><a href='../support.html'>Support</a>
38 <li><a href='../prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="../search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <!-- keywords: sqlite3_io_methods -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>OS Interface File Virtual Methods Object</h2>
122 </div>
123 <blockquote><pre>
124 typedef struct sqlite3_io_methods sqlite3_io_methods;
125 struct sqlite3_io_methods {
126 int iVersion;
127 int (*xClose)(sqlite3_file*);
128 int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
129 int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
130 int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
131 int (*xSync)(sqlite3_file*, int flags);
132 int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
133 int (*xLock)(sqlite3_file*, int);
134 int (*xUnlock)(sqlite3_file*, int);
135 int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
136 int (*xFileControl)(sqlite3_file*, int op, void *pArg);
137 int (*xSectorSize)(sqlite3_file*);
138 int (*xDeviceCharacteristics)(sqlite3_file*);
139 /* Methods above are valid for version 1 */
140 int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
141 int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
142 void (*xShmBarrier)(sqlite3_file*);
143 int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
144 /* Methods above are valid for version 2 */
145 int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
146 int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
147 /* Methods above are valid for version 3 */
148 /* Additional methods may be added in future releases */
149 };
150 </pre></blockquote>
151 <p>
152 Every file opened by the <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method populates an
153 <a href="../c3ref/file.html">sqlite3_file</a> object (or, more commonly, a subclass of the
154 <a href="../c3ref/file.html">sqlite3_file</a> object) with a pointer to an instance of this object.
155 This object defines the methods used to perform various operations
156 against the open file represented by the <a href="../c3ref/file.html">sqlite3_file</a> object.</p>
157
158 <p>If the <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> method sets the sqlite3_file.pMethods element
159 to a non-NULL pointer, then the sqlite3_io_methods.xClose method
160 may be invoked even if the <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> reported that it failed. The
161 only way to prevent a call to xClose following a failed <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a>
162 is for the <a href="../c3ref/vfs.html#sqlite3vfsxopen">sqlite3_vfs.xOpen</a> to set the sqlite3_file.pMethods element
163 to NULL.</p>
164
165 <p>The flags argument to xSync may be one of <a href="../c3ref/c_sync_dataonly.html">SQLITE_SYNC_NORMAL</a> or
166 <a href="../c3ref/c_sync_dataonly.html">SQLITE_SYNC_FULL</a>. The first choice is the normal fsync().
167 The second choice is a Mac OS X style fullsync. The <a href="../c3ref/c_sync_dataonly.html">SQLITE_SYNC_DATAONLY</a>
168 flag may be ORed in to indicate that only the data of the file
169 and not its inode needs to be synced.</p>
170
171 <p>The integer values to xLock() and xUnlock() are one of
172 <ul>
173 <li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_NONE</a>,
174 <li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a>,
175 <li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_RESERVED</a>,
176 <li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_PENDING</a>, or
177 <li> <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_EXCLUSIVE</a>.
178 </ul>
179 xLock() upgrades the database file lock. In other words, xLock() moves the
180 database file lock in the direction NONE toward EXCLUSIVE. The argument to
181 xLock() is always one of SHARED, RESERVED, PENDING, or EXCLUSIVE, never
182 SQLITE_LOCK_NONE. If the database file lock is already at or above the
183 requested lock, then the call to xLock() is a no-op.
184 xUnlock() downgrades the database file lock to either SHARED or NONE.
185 If the lock is already at or below the requested lock state, then the call
186 to xUnlock() is a no-op.
187 The xCheckReservedLock() method checks whether any database connection,
188 either in this process or in some other process, is holding a RESERVED,
189 PENDING, or EXCLUSIVE lock on the file. It returns, via its output
190 pointer parameter, true if such a lock exists and false otherwise.</p>
191
192 <p>The xFileControl() method is a generic interface that allows custom
193 VFS implementations to directly control an open file using the
194 <a href="../c3ref/file_control.html">sqlite3_file_control()</a> interface. The second "op" argument is an
195 integer opcode. The third argument is a generic pointer intended to
196 point to a structure that may contain arguments or space in which to
197 write return values. Potential uses for xFileControl() might be
198 functions to enable blocking locks with timeouts, to change the
199 locking strategy (for example to use dot-file locks), to inquire
200 about the status of a lock, or to break stale locks. The SQLite
201 core reserves all opcodes less than 100 for its own use.
202 A <a href="../c3ref/c_fcntl_begin_atomic_write.html">list of opcodes</a> less than 100 is available.
203 Applications that define a custom xFileControl method should use opcodes
204 greater than 100 to avoid conflicts. VFS implementations should
205 return <a href="../rescode.html#notfound">SQLITE_NOTFOUND</a> for file control opcodes that they do not
206 recognize.</p>
207
208 <p>The xSectorSize() method returns the sector size of the
209 device that underlies the file. The sector size is the
210 minimum write that can be performed without disturbing
211 other bytes in the file. The xDeviceCharacteristics()
212 method returns a bit vector describing behaviors of the
213 underlying device:</p>
214
215 <p><ul>
216 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC</a>
217 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC512</a>
218 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC1K</a>
219 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC2K</a>
220 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC4K</a>
221 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC8K</a>
222 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC16K</a>
223 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC32K</a>
224 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_ATOMIC64K</a>
225 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SAFE_APPEND</a>
226 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SEQUENTIAL</a>
227 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN</a>
228 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_POWERSAFE_OVERWRITE</a>
229 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_IMMUTABLE</a>
230 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_BATCH_ATOMIC</a>
231 <li> <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_SUBPAGE_READ</a>
232 </ul></p>
233
234 <p>The SQLITE_IOCAP_ATOMIC property means that all writes of
235 any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
236 mean that writes of blocks that are nnn bytes in size and
237 are aligned to an address which is an integer multiple of
238 nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
239 that when data is appended to a file, the data is appended
240 first then the size of the file is extended, never the other
241 way around. The SQLITE_IOCAP_SEQUENTIAL property means that
242 information is written to disk in the same order as calls
243 to xWrite().</p>
244
245 <p>If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
246 in the unread portions of the buffer with zeros. A VFS that
247 fails to zero-fill short reads might seem to work. However,
248 failure to zero-fill short reads will eventually lead to
249 database corruption.
250 </p><p>See also lists of
251 <a href="../c3ref/objlist.html">Objects</a>,
252 <a href="../c3ref/constlist.html">Constants</a>, and
253 <a href="../c3ref/funclist.html">Functions</a>.</p>
254