1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>OS Interface File Virtual Methods Object</title>
<style type="text/css">
body {
margin: auto;
font-family: Verdana, sans-serif;
padding: 8px 1%;
}
a { color: #044a64 }
a:visited { color: #734559 }
.logo { position:absolute; margin:3px; }
.tagline {
float:right;
text-align:right;
font-style:italic;
width:300px;
margin:12px;
margin-top:58px;
}
.menubar {
clear: both;
border-radius: 8px;
background: #044a64;
padding: 0px;
margin: 0px;
cell-spacing: 0px;
}
.toolbar {
text-align: center;
line-height: 1.6em;
margin: 0;
padding: 0px 8px;
}
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
.toolbar a:visited { color: white; }
.toolbar a:hover { color: #044a64; background: white; }
.content { margin: 5%; }
.content dt { font-weight:bold; }
.content dd { margin-bottom: 25px; margin-left:20%; }
.content ul { padding:0px; padding-left: 15px; margin:0px; }
/* Things for "fancyformat" documents start here. */
.fancy img+p {font-style:italic}
.fancy .codeblock i { color: darkblue; }
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
.fancy h2 { margin-left: 10px }
.fancy h3 { margin-left: 20px }
.fancy h4 { margin-left: 30px }
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
.fancy #toc a { color: darkblue ; text-decoration: none }
.fancy .todo { color: #AA3333 ; font-style : italic }
.fancy .todo:before { content: 'TODO:' }
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
.fancy img { display:block; }
.fancy :link:hover, .fancy :visited:hover { background: wheat }
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
.fancy li p { margin: 1em 0 }
/* End of "fancyformat" specific rules. */
</style>
</head>
<body>
<div><!-- container div to satisfy validator -->
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
border="0"></a>
<div><!-- IE hack to prevent disappearing logo--></div>
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
<table width=100% class="menubar"><tr>
<td width=100%>
<div class="toolbar">
<a href="../about.html">About</a>
<a href="../sitemap.html">Sitemap</a>
<a href="../docs.html">Documentation</a>
<a href="../download.html">Download</a>
<a href="../copyright.html">License</a>
<a href="../news.html">News</a>
<a href="../support.html">Support</a>
</div>
<script>
gMsg = "Search SQLite Docs..."
function entersearch() {
var q = document.getElementById("q");
if( q.value == gMsg ) { q.value = "" }
q.style.color = "black"
q.style.fontStyle = "normal"
}
function leavesearch() {
var q = document.getElementById("q");
if( q.value == "" ) {
q.value = gMsg
q.style.color = "#044a64"
q.style.fontStyle = "italic"
}
}
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>
<td>
<div style="padding:0 1em 0px 0;white-space:nowrap">
<form name=f method="GET" action="http://www.sqlite.org/search">
<input id=q name=q type=text
onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
</form>
</div>
</table>
<div class=startsearch></div>
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>OS Interface File Virtual Methods Object</h2><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() increases the lock. xUnlock() decreases the lock.
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_busyhandler.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>
</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="objlist.html">Objects</a>,
<a href="constlist.html">Constants</a>, and
<a href="funclist.html">Functions</a>.</p>
|
