1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
3
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
4
<title>Standard File Control Opcodes</title>
5
<style type="text/css">
8
font-family: Verdana, sans-serif;
13
a:visited { color: #734559 }
15
.logo { position:absolute; margin:3px; }
31
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
32
.toolbar a:visited { color: white; }
33
.toolbar a:hover { color: #044a64; background: white; }
35
.content { margin: 5%; }
36
.content dt { font-weight:bold; }
37
.content dd { margin-bottom: 25px; margin-left:20%; }
38
.content ul { padding:0px; padding-left: 15px; margin:0px; }
41
.se { background: url(../images/se.gif) 100% 100% no-repeat #044a64}
42
.sw { background: url(../images/sw.gif) 0% 100% no-repeat }
43
.ne { background: url(../images/ne.gif) 100% 0% no-repeat }
44
.nw { background: url(../images/nw.gif) 0% 0% no-repeat }
46
/* Things for "fancyformat" documents start here. */
47
.fancy img+p {font-style:italic}
48
.fancy .codeblock i { color: darkblue; }
49
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
50
.fancy h2 { margin-left: 10px }
51
.fancy h3 { margin-left: 20px }
52
.fancy h4 { margin-left: 30px }
53
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
54
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
55
.fancy #toc a { color: darkblue ; text-decoration: none }
56
.fancy .todo { color: #AA3333 ; font-style : italic }
57
.fancy .todo:before { content: 'TODO:' }
58
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
59
.fancy img { display:block; }
60
.fancy :link:hover, .fancy :visited:hover { background: wheat }
61
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
62
.fancy li p { margin: 1em 0 }
63
/* End of "fancyformat" specific rules. */
69
<div><!-- container div to satisfy validator -->
71
<a href="../index.html">
72
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
74
<div><!-- IE hack to prevent disappearing logo--></div>
75
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
77
<table width=100% style="clear:both"><tr><td>
78
<div class="se"><div class="sw"><div class="ne"><div class="nw">
79
<table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
82
<a href="../about.html">About</a>
83
<a href="../sitemap.html">Sitemap</a>
84
<a href="../docs.html">Documentation</a>
85
<a href="../download.html">Download</a>
86
<a href="../copyright.html">License</a>
87
<a href="../news.html">News</a>
88
<a href="../support.html">Support</a>
91
gMsg = "Search SQLite Docs..."
92
function entersearch() {
93
var q = document.getElementById("q");
94
if( q.value == gMsg ) { q.value = "" }
95
q.style.color = "black"
96
q.style.fontStyle = "normal"
98
function leavesearch() {
99
var q = document.getElementById("q");
100
if( q.value == "" ) {
102
q.style.color = "#044a64"
103
q.style.fontStyle = "italic"
108
<div style="padding:0 1em 0px 0;white-space:nowrap">
109
<form name=f method="GET" action="http://www.sqlite.org/search">
110
<input id=q name=q type=text
111
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...">
112
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
116
</div></div></div></div>
118
<div class=startsearch></div>
120
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Standard File Control Opcodes</h2><blockquote><pre>#define SQLITE_FCNTL_LOCKSTATE 1
121
#define SQLITE_GET_LOCKPROXYFILE 2
122
#define SQLITE_SET_LOCKPROXYFILE 3
123
#define SQLITE_LAST_ERRNO 4
124
#define SQLITE_FCNTL_SIZE_HINT 5
125
#define SQLITE_FCNTL_CHUNK_SIZE 6
126
#define SQLITE_FCNTL_FILE_POINTER 7
127
#define SQLITE_FCNTL_SYNC_OMITTED 8
128
#define SQLITE_FCNTL_WIN32_AV_RETRY 9
129
#define SQLITE_FCNTL_PERSIST_WAL 10
130
#define SQLITE_FCNTL_OVERWRITE 11
131
#define SQLITE_FCNTL_VFSNAME 12
132
#define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13
133
#define SQLITE_FCNTL_PRAGMA 14
134
</pre></blockquote><p>
135
These integer constants are opcodes for the xFileControl method
136
of the <a href="../c3ref/io_methods.html">sqlite3_io_methods</a> object and for the <a href="../c3ref/file_control.html">sqlite3_file_control()</a>
139
<p>The <a href="../c3ref/c_fcntl_chunk_size.html">SQLITE_FCNTL_LOCKSTATE</a> opcode is used for debugging. This
140
opcode causes the xFileControl method to write the current state of
141
the lock (one of <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_NONE</a>, <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_SHARED</a>,
142
<a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_RESERVED</a>, <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_PENDING</a>, or <a href="../c3ref/c_lock_exclusive.html">SQLITE_LOCK_EXCLUSIVE</a>)
143
into an integer that the pArg argument points to. This capability
144
is used during testing and only needs to be supported when SQLITE_TEST
147
<li><a name="sqlitefcntlsizehint"></a>
149
The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlsizehint">SQLITE_FCNTL_SIZE_HINT</a> opcode is used by SQLite to give the VFS
150
layer a hint of how large the database file will grow to be during the
151
current transaction. This hint is not guaranteed to be accurate but it
152
is often close. The underlying VFS might choose to preallocate database
153
file space based on this hint in order to help writes to the database
156
<p><li><a name="sqlitefcntlchunksize"></a>
158
The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlchunksize">SQLITE_FCNTL_CHUNK_SIZE</a> opcode is used to request that the VFS
159
extends and truncates the database file in chunks of a size specified
160
by the user. The fourth argument to <a href="../c3ref/file_control.html">sqlite3_file_control()</a> should
161
point to an integer (type int) containing the new chunk-size to use
162
for the nominated database. Allocating database file space in large
163
chunks (say 1MB at a time), may reduce file-system fragmentation and
164
improve performance on some systems.</p>
166
<p><li><a name="sqlitefcntlfilepointer"></a>
168
The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlfilepointer">SQLITE_FCNTL_FILE_POINTER</a> opcode is used to obtain a pointer
169
to the <a href="../c3ref/file.html">sqlite3_file</a> object associated with a particular database
170
connection. See the <a href="../c3ref/file_control.html">sqlite3_file_control()</a> documentation for
171
additional information.</p>
173
<p><li><a name="sqlitefcntlsyncomitted"></a>
175
The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlsyncomitted">SQLITE_FCNTL_SYNC_OMITTED</a> opcode is generated internally by
176
SQLite and sent to all VFSes in place of a call to the xSync method
177
when the database connection has <a href="../pragma.html#pragma_synchronous">PRAGMA synchronous</a> set to OFF.
178
Some specialized VFSes need this signal in order to operate correctly
179
when <a href="../pragma.html#pragma_synchronous">PRAGMA synchronous=OFF</a> is set, but most
180
VFSes do not need this signal and should silently ignore this opcode.
181
Applications should not call <a href="../c3ref/file_control.html">sqlite3_file_control()</a> with this
182
opcode as doing so may disrupt the operation of the specialized VFSes
183
that do require it.</p>
185
<p><li><a name="sqlitefcntlwin32avretry"></a>
187
The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlwin32avretry">SQLITE_FCNTL_WIN32_AV_RETRY</a> opcode is used to configure automatic
188
retry counts and intervals for certain disk I/O operations for the
189
windows <a href="../vfs.html">VFS</a> in order to provide robustness in the presence of
190
anti-virus programs. By default, the windows VFS will retry file read,
191
file write, and file delete operations up to 10 times, with a delay
192
of 25 milliseconds before the first retry and with the delay increasing
193
by an additional 25 milliseconds with each subsequent retry. This
194
opcode allows these two values (10 retries and 25 milliseconds of delay)
195
to be adjusted. The values are changed for all database connections
196
within the same process. The argument is a pointer to an array of two
197
integers where the first integer i the new retry count and the second
198
integer is the delay. If either integer is negative, then the setting
199
is not changed but instead the prior value of that setting is written
200
into the array entry, allowing the current retry settings to be
201
interrogated. The zDbName parameter is ignored.</p>
203
<p><li><a name="sqlitefcntlpersistwal"></a>
205
The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpersistwal">SQLITE_FCNTL_PERSIST_WAL</a> opcode is used to set or query the
206
persistent <a href="../wal.html">Write Ahead Log</a> setting. By default, the auxiliary
207
write ahead log and shared memory files used for transaction control
208
are automatically deleted when the latest connection to the database
209
closes. Setting persistent WAL mode causes those files to persist after
210
close. Persisting the files is useful when other processes that do not
211
have write permission on the directory containing the database file want
212
to read the database file, as the WAL and shared memory files must exist
213
in order for the database to be readable. The fourth parameter to
214
<a href="../c3ref/file_control.html">sqlite3_file_control()</a> for this opcode should be a pointer to an integer.
215
That integer is 0 to disable persistent WAL mode or 1 to enable persistent
216
WAL mode. If the integer is -1, then it is overwritten with the current
217
WAL persistence setting.</p>
219
<p><li><a name="sqlitefcntlpowersafeoverwrite"></a>
221
The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpowersafeoverwrite">SQLITE_FCNTL_POWERSAFE_OVERWRITE</a> opcode is used to set or query the
222
persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting
223
determines the <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_POWERSAFE_OVERWRITE</a> bit of the
224
xDeviceCharacteristics methods. The fourth parameter to
225
<a href="../c3ref/file_control.html">sqlite3_file_control()</a> for this opcode should be a pointer to an integer.
226
That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
227
mode. If the integer is -1, then it is overwritten with the current
228
zero-damage mode setting.</p>
230
<p><li><a name="sqlitefcntloverwrite"></a>
232
The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntloverwrite">SQLITE_FCNTL_OVERWRITE</a> opcode is invoked by SQLite after opening
233
a write transaction to indicate that, unless it is rolled back for some
234
reason, the entire database file will be overwritten by the current
235
transaction. This is used by VACUUM operations.</p>
237
<p><li><a name="sqlitefcntlvfsname"></a>
239
The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlvfsname">SQLITE_FCNTL_VFSNAME</a> opcode can be used to obtain the names of
240
all <a href="../vfs.html">VFSes</a> in the VFS stack. The names are of all VFS shims and the
241
final bottom-level VFS are written into memory obtained from
242
<a href="../c3ref/free.html">sqlite3_malloc()</a> and the result is stored in the char* variable
243
that the fourth parameter of <a href="../c3ref/file_control.html">sqlite3_file_control()</a> points to.
244
The caller is responsible for freeing the memory when done. As with
245
all file-control actions, there is no guarantee that this will actually
246
do anything. Callers should initialize the char* variable to a NULL
247
pointer in case this file-control is not implemented. This file-control
248
is intended for diagnostic use only.</p>
250
<p><li><a name="sqlitefcntlpragma"></a>
252
Whenever a <a href="../pragma.html#syntax">PRAGMA</a> statement is parsed, an <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>
253
file control is sent to the open <a href="../c3ref/file.html">sqlite3_file</a> object corresponding
254
to the database file to which the pragma statement refers. The argument
255
to the <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control is an array of
256
pointers to strings (char**) in which the second element of the array
257
is the name of the pragma and the third element is the argument to the
258
pragma or NULL if the pragma has no argument. The handler for an
259
<a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control can optionally make the first element
260
of the char** argument point to a string obtained from <a href="../c3ref/mprintf.html">sqlite3_mprintf()</a>
261
or the equivalent and that string will become the result of the pragma or
262
the error message if the pragma fails. If the
263
<a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control returns <a href="../c3ref/c_abort.html">SQLITE_NOTFOUND</a>, then normal
264
<a href="../pragma.html#syntax">PRAGMA</a> processing continues. If the <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>
265
file control returns <a href="../c3ref/c_abort.html">SQLITE_OK</a>, then the parser assumes that the
266
VFS has handled the PRAGMA itself and the parser generates a no-op
267
prepared statement. If the <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control returns
268
any result code other than <a href="../c3ref/c_abort.html">SQLITE_OK</a> or <a href="../c3ref/c_abort.html">SQLITE_NOTFOUND</a>, that means
269
that the VFS encountered an error while handling the <a href="../pragma.html#syntax">PRAGMA</a> and the
270
compilation of the PRAGMA fails with an error. The <a href="../c3ref/c_fcntl_chunk_size.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>
271
file control occurs at the beginning of pragma statement analysis and so
272
it is able to override built-in <a href="../pragma.html#syntax">PRAGMA</a> statements.
274
</p><p>See also lists of
275
<a href="objlist.html">Objects</a>,
276
<a href="constlist.html">Constants</a>, and
277
<a href="funclist.html">Functions</a>.</p>
added
removed
c3ref/c_fcntl_chunk_size.html
