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
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
|
<!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>Standard File Control Opcodes</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: SQLITE_FCNTL_BEGIN_ATOMIC_WRITE SQLITE_FCNTL_BUSYHANDLER SQLITE_FCNTL_CHUNK_SIZE SQLITE_FCNTL_CKPT_DONE SQLITE_FCNTL_CKPT_START SQLITE_FCNTL_CKSM_FILE SQLITE_FCNTL_COMMIT_ATOMIC_WRITE SQLITE_FCNTL_COMMIT_PHASETWO SQLITE_FCNTL_DATA_VERSION SQLITE_FCNTL_EXTERNAL_READER SQLITE_FCNTL_FILE_POINTER SQLITE_FCNTL_GET_LOCKPROXYFILE SQLITE_FCNTL_HAS_MOVED SQLITE_FCNTL_JOURNAL_POINTER SQLITE_FCNTL_LAST_ERRNO SQLITE_FCNTL_LOCKSTATE SQLITE_FCNTL_LOCK_TIMEOUT SQLITE_FCNTL_MMAP_SIZE SQLITE_FCNTL_OVERWRITE SQLITE_FCNTL_PDB SQLITE_FCNTL_PERSIST_WAL SQLITE_FCNTL_POWERSAFE_OVERWRITE SQLITE_FCNTL_PRAGMA SQLITE_FCNTL_RBU SQLITE_FCNTL_RESERVE_BYTES SQLITE_FCNTL_RESET_CACHE SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE SQLITE_FCNTL_SET_LOCKPROXYFILE SQLITE_FCNTL_SIZE_HINT SQLITE_FCNTL_SIZE_LIMIT SQLITE_FCNTL_SYNC SQLITE_FCNTL_SYNC_OMITTED SQLITE_FCNTL_TEMPFILENAME SQLITE_FCNTL_TRACE SQLITE_FCNTL_VFSNAME SQLITE_FCNTL_VFS_POINTER SQLITE_FCNTL_WAL_BLOCK SQLITE_FCNTL_WIN32_AV_RETRY SQLITE_FCNTL_WIN32_GET_HANDLE SQLITE_FCNTL_WIN32_SET_HANDLE SQLITE_FCNTL_ZIPVFS {file control opcode} {file control opcodes} -->
<div class=nosearch>
<a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
<h2>Standard File Control Opcodes</h2>
</div>
<blockquote><pre>
#define SQLITE_FCNTL_LOCKSTATE 1
#define SQLITE_FCNTL_GET_LOCKPROXYFILE 2
#define SQLITE_FCNTL_SET_LOCKPROXYFILE 3
#define SQLITE_FCNTL_LAST_ERRNO 4
#define SQLITE_FCNTL_SIZE_HINT 5
#define SQLITE_FCNTL_CHUNK_SIZE 6
#define SQLITE_FCNTL_FILE_POINTER 7
#define SQLITE_FCNTL_SYNC_OMITTED 8
#define SQLITE_FCNTL_WIN32_AV_RETRY 9
#define SQLITE_FCNTL_PERSIST_WAL 10
#define SQLITE_FCNTL_OVERWRITE 11
#define SQLITE_FCNTL_VFSNAME 12
#define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13
#define SQLITE_FCNTL_PRAGMA 14
#define SQLITE_FCNTL_BUSYHANDLER 15
#define SQLITE_FCNTL_TEMPFILENAME 16
#define SQLITE_FCNTL_MMAP_SIZE 18
#define SQLITE_FCNTL_TRACE 19
#define SQLITE_FCNTL_HAS_MOVED 20
#define SQLITE_FCNTL_SYNC 21
#define SQLITE_FCNTL_COMMIT_PHASETWO 22
#define SQLITE_FCNTL_WIN32_SET_HANDLE 23
#define SQLITE_FCNTL_WAL_BLOCK 24
#define SQLITE_FCNTL_ZIPVFS 25
#define SQLITE_FCNTL_RBU 26
#define SQLITE_FCNTL_VFS_POINTER 27
#define SQLITE_FCNTL_JOURNAL_POINTER 28
#define SQLITE_FCNTL_WIN32_GET_HANDLE 29
#define SQLITE_FCNTL_PDB 30
#define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31
#define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32
#define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33
#define SQLITE_FCNTL_LOCK_TIMEOUT 34
#define SQLITE_FCNTL_DATA_VERSION 35
#define SQLITE_FCNTL_SIZE_LIMIT 36
#define SQLITE_FCNTL_CKPT_DONE 37
#define SQLITE_FCNTL_RESERVE_BYTES 38
#define SQLITE_FCNTL_CKPT_START 39
#define SQLITE_FCNTL_EXTERNAL_READER 40
#define SQLITE_FCNTL_CKSM_FILE 41
#define SQLITE_FCNTL_RESET_CACHE 42
</pre></blockquote>
<p>
These integer constants are opcodes for the xFileControl method
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>
interface.</p>
<p><ul>
<li><a name="sqlitefcntllockstate"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntllockstate">SQLITE_FCNTL_LOCKSTATE</a> opcode is used for debugging. This
opcode causes the xFileControl method to write the current state of
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>,
<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>)
into an integer that the pArg argument points to.
This capability is only available if SQLite is compiled with <a href="../compile.html#debug">SQLITE_DEBUG</a>.</p>
<p><li><a name="sqlitefcntlsizehint"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlsizehint">SQLITE_FCNTL_SIZE_HINT</a> opcode is used by SQLite to give the VFS
layer a hint of how large the database file will grow to be during the
current transaction. This hint is not guaranteed to be accurate but it
is often close. The underlying VFS might choose to preallocate database
file space based on this hint in order to help writes to the database
file run faster.</p>
<p><li><a name="sqlitefcntlsizelimit"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlsizelimit">SQLITE_FCNTL_SIZE_LIMIT</a> opcode is used by in-memory VFS that
implements <a href="../c3ref/deserialize.html">sqlite3_deserialize()</a> to set an upper bound on the size
of the in-memory database. The argument is a pointer to a <a href="../c3ref/int64.html">sqlite3_int64</a>.
If the integer pointed to is negative, then it is filled in with the
current limit. Otherwise the limit is set to the larger of the value
of the integer pointed to and the current database size. The integer
pointed to is set to the new limit.</p>
<p><li><a name="sqlitefcntlchunksize"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlchunksize">SQLITE_FCNTL_CHUNK_SIZE</a> opcode is used to request that the VFS
extends and truncates the database file in chunks of a size specified
by the user. The fourth argument to <a href="../c3ref/file_control.html">sqlite3_file_control()</a> should
point to an integer (type int) containing the new chunk-size to use
for the nominated database. Allocating database file space in large
chunks (say 1MB at a time), may reduce file-system fragmentation and
improve performance on some systems.</p>
<p><li><a name="sqlitefcntlfilepointer"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlfilepointer">SQLITE_FCNTL_FILE_POINTER</a> opcode is used to obtain a pointer
to the <a href="../c3ref/file.html">sqlite3_file</a> object associated with a particular database
connection. See also <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntljournalpointer">SQLITE_FCNTL_JOURNAL_POINTER</a>.</p>
<p><li><a name="sqlitefcntljournalpointer"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntljournalpointer">SQLITE_FCNTL_JOURNAL_POINTER</a> opcode is used to obtain a pointer
to the <a href="../c3ref/file.html">sqlite3_file</a> object associated with the journal file (either
the <a href="../lockingv3.html#rollback">rollback journal</a> or the <a href="../wal.html">write-ahead log</a>) for a particular database
connection. See also <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlfilepointer">SQLITE_FCNTL_FILE_POINTER</a>.</p>
<p><li><a name="sqlitefcntlsyncomitted"></a>
No longer in use.</p>
<p><li><a name="sqlitefcntlsync"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlsync">SQLITE_FCNTL_SYNC</a> opcode is generated internally by SQLite and
sent to the VFS immediately before the xSync method is invoked on a
database file descriptor. Or, if the xSync method is not invoked
because the user has configured SQLite with
<a href="../pragma.html#pragma_synchronous">PRAGMA synchronous=OFF</a> it is invoked in place
of the xSync method. In most cases, the pointer argument passed with
this file-control is NULL. However, if the database file is being synced
as part of a multi-database commit, the argument points to a nul-terminated
string containing the transactions super-journal file name. VFSes that
do not need this signal should silently ignore this opcode. Applications
should not call <a href="../c3ref/file_control.html">sqlite3_file_control()</a> with this opcode as doing so may
disrupt the operation of the specialized VFSes that do require it.</p>
<p><li><a name="sqlitefcntlcommitphasetwo"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlcommitphasetwo">SQLITE_FCNTL_COMMIT_PHASETWO</a> opcode is generated internally by SQLite
and sent to the VFS after a transaction has been committed immediately
but before the database is unlocked. VFSes that do not need this signal
should silently ignore this opcode. Applications should not call
<a href="../c3ref/file_control.html">sqlite3_file_control()</a> with this opcode as doing so may disrupt the
operation of the specialized VFSes that do require it.</p>
<p><li><a name="sqlitefcntlwin32avretry"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlwin32avretry">SQLITE_FCNTL_WIN32_AV_RETRY</a> opcode is used to configure automatic
retry counts and intervals for certain disk I/O operations for the
windows <a href="../vfs.html">VFS</a> in order to provide robustness in the presence of
anti-virus programs. By default, the windows VFS will retry file read,
file write, and file delete operations up to 10 times, with a delay
of 25 milliseconds before the first retry and with the delay increasing
by an additional 25 milliseconds with each subsequent retry. This
opcode allows these two values (10 retries and 25 milliseconds of delay)
to be adjusted. The values are changed for all database connections
within the same process. The argument is a pointer to an array of two
integers where the first integer is the new retry count and the second
integer is the delay. If either integer is negative, then the setting
is not changed but instead the prior value of that setting is written
into the array entry, allowing the current retry settings to be
interrogated. The zDbName parameter is ignored.</p>
<p><li><a name="sqlitefcntlpersistwal"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlpersistwal">SQLITE_FCNTL_PERSIST_WAL</a> opcode is used to set or query the
persistent <a href="../wal.html">Write Ahead Log</a> setting. By default, the auxiliary
write ahead log (<a href="../wal.html#walfile">WAL file</a>) and shared memory
files used for transaction control
are automatically deleted when the latest connection to the database
closes. Setting persistent WAL mode causes those files to persist after
close. Persisting the files is useful when other processes that do not
have write permission on the directory containing the database file want
to read the database file, as the WAL and shared memory files must exist
in order for the database to be readable. The fourth parameter to
<a href="../c3ref/file_control.html">sqlite3_file_control()</a> for this opcode should be a pointer to an integer.
That integer is 0 to disable persistent WAL mode or 1 to enable persistent
WAL mode. If the integer is -1, then it is overwritten with the current
WAL persistence setting.</p>
<p><li><a name="sqlitefcntlpowersafeoverwrite"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlpowersafeoverwrite">SQLITE_FCNTL_POWERSAFE_OVERWRITE</a> opcode is used to set or query the
persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting
determines the <a href="../c3ref/c_iocap_atomic.html">SQLITE_IOCAP_POWERSAFE_OVERWRITE</a> bit of the
xDeviceCharacteristics methods. The fourth parameter to
<a href="../c3ref/file_control.html">sqlite3_file_control()</a> for this opcode should be a pointer to an integer.
That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
mode. If the integer is -1, then it is overwritten with the current
zero-damage mode setting.</p>
<p><li><a name="sqlitefcntloverwrite"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntloverwrite">SQLITE_FCNTL_OVERWRITE</a> opcode is invoked by SQLite after opening
a write transaction to indicate that, unless it is rolled back for some
reason, the entire database file will be overwritten by the current
transaction. This is used by VACUUM operations.</p>
<p><li><a name="sqlitefcntlvfsname"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlvfsname">SQLITE_FCNTL_VFSNAME</a> opcode can be used to obtain the names of
all <a href="../vfs.html">VFSes</a> in the VFS stack. The names are of all VFS shims and the
final bottom-level VFS are written into memory obtained from
<a href="../c3ref/free.html">sqlite3_malloc()</a> and the result is stored in the char* variable
that the fourth parameter of <a href="../c3ref/file_control.html">sqlite3_file_control()</a> points to.
The caller is responsible for freeing the memory when done. As with
all file-control actions, there is no guarantee that this will actually
do anything. Callers should initialize the char* variable to a NULL
pointer in case this file-control is not implemented. This file-control
is intended for diagnostic use only.</p>
<p><li><a name="sqlitefcntlvfspointer"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlvfspointer">SQLITE_FCNTL_VFS_POINTER</a> opcode finds a pointer to the top-level
<a href="../vfs.html">VFSes</a> currently in use. The argument X in
sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
of type "<a href="../c3ref/vfs.html">sqlite3_vfs</a> **". This opcodes will set *X
to a pointer to the top-level VFS.
When there are multiple VFS shims in the stack, this opcode finds the
upper-most shim only.</p>
<p><li><a name="sqlitefcntlpragma"></a>
Whenever a <a href="../pragma.html#syntax">PRAGMA</a> statement is parsed, an <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>
file control is sent to the open <a href="../c3ref/file.html">sqlite3_file</a> object corresponding
to the database file to which the pragma statement refers. The argument
to the <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control is an array of
pointers to strings (char**) in which the second element of the array
is the name of the pragma and the third element is the argument to the
pragma or NULL if the pragma has no argument. The handler for an
<a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control can optionally make the first element
of the char** argument point to a string obtained from <a href="../c3ref/mprintf.html">sqlite3_mprintf()</a>
or the equivalent and that string will become the result of the pragma or
the error message if the pragma fails. If the
<a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control returns <a href="../rescode.html#notfound">SQLITE_NOTFOUND</a>, then normal
<a href="../pragma.html#syntax">PRAGMA</a> processing continues. If the <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>
file control returns <a href="../rescode.html#ok">SQLITE_OK</a>, then the parser assumes that the
VFS has handled the PRAGMA itself and the parser generates a no-op
prepared statement if result string is NULL, or that returns a copy
of the result string if the string is non-NULL.
If the <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a> file control returns
any result code other than <a href="../rescode.html#ok">SQLITE_OK</a> or <a href="../rescode.html#notfound">SQLITE_NOTFOUND</a>, that means
that the VFS encountered an error while handling the <a href="../pragma.html#syntax">PRAGMA</a> and the
compilation of the PRAGMA fails with an error. The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlpragma">SQLITE_FCNTL_PRAGMA</a>
file control occurs at the beginning of pragma statement analysis and so
it is able to override built-in <a href="../pragma.html#syntax">PRAGMA</a> statements.</p>
<p><li><a name="sqlitefcntlbusyhandler"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlbusyhandler">SQLITE_FCNTL_BUSYHANDLER</a>
file-control may be invoked by SQLite on the database file handle
shortly after it is opened in order to provide a custom VFS with access
to the connection's busy-handler callback. The argument is of type (void**)
- an array of two (void *) values. The first (void *) actually points
to a function of type (int (*)(void *)). In order to invoke the connection's
busy-handler, this function should be invoked with the second (void *) in
the array as the only argument. If it returns non-zero, then the operation
should be retried. If it returns zero, the custom VFS should abandon the
current operation.</p>
<p><li><a name="sqlitefcntltempfilename"></a>
Applications can invoke the <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntltempfilename">SQLITE_FCNTL_TEMPFILENAME</a> file-control
to have SQLite generate a
temporary filename using the same algorithm that is followed to generate
temporary filenames for TEMP tables and other internal uses. The
argument should be a char** which will be filled with the filename
written into memory obtained from <a href="../c3ref/free.html">sqlite3_malloc()</a>. The caller should
invoke <a href="../c3ref/free.html">sqlite3_free()</a> on the result to avoid a memory leak.</p>
<p><li><a name="sqlitefcntlmmapsize"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlmmapsize">SQLITE_FCNTL_MMAP_SIZE</a> file control is used to query or set the
maximum number of bytes that will be used for memory-mapped I/O.
The argument is a pointer to a value of type sqlite3_int64 that
is an advisory maximum number of bytes in the file to memory map. The
pointer is overwritten with the old value. The limit is not changed if
the value originally pointed to is negative, and so the current limit
can be queried by passing in a pointer to a negative number. This
file-control is used internally to implement <a href="../pragma.html#pragma_mmap_size">PRAGMA mmap_size</a>.</p>
<p><li><a name="sqlitefcntltrace"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntltrace">SQLITE_FCNTL_TRACE</a> file control provides advisory information
to the VFS about what the higher layers of the SQLite stack are doing.
This file control is used by some VFS activity tracing <a href="../vfs.html#shim">shims</a>.
The argument is a zero-terminated string. Higher layers in the
SQLite stack may generate instances of this file control if
the <a href="../compile.html#use_fcntl_trace">SQLITE_USE_FCNTL_TRACE</a> compile-time option is enabled.</p>
<p><li><a name="sqlitefcntlhasmoved"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlhasmoved">SQLITE_FCNTL_HAS_MOVED</a> file control interprets its argument as a
pointer to an integer and it writes a boolean into that integer depending
on whether or not the file has been renamed, moved, or deleted since it
was first opened.</p>
<p><li><a name="sqlitefcntlwin32gethandle"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlwin32gethandle">SQLITE_FCNTL_WIN32_GET_HANDLE</a> opcode can be used to obtain the
underlying native file handle associated with a file handle. This file
control interprets its argument as a pointer to a native file handle and
writes the resulting value there.</p>
<p><li><a name="sqlitefcntlwin32sethandle"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlwin32sethandle">SQLITE_FCNTL_WIN32_SET_HANDLE</a> opcode is used for debugging. This
opcode causes the xFileControl method to swap the file handle with the one
pointed to by the pArg argument. This capability is used during testing
and only needs to be supported when SQLITE_TEST is defined.</p>
<p><li><a name="sqlitefcntlwalblock"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlwalblock">SQLITE_FCNTL_WAL_BLOCK</a> is a signal to the VFS layer that it might
be advantageous to block on the next WAL lock if the lock is not immediately
available. The WAL subsystem issues this signal during rare
circumstances in order to fix a problem with priority inversion.
Applications should <em>not</em> use this file-control.</p>
<p><li><a name="sqlitefcntlzipvfs"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlzipvfs">SQLITE_FCNTL_ZIPVFS</a> opcode is implemented by zipvfs only. All other
VFS should return SQLITE_NOTFOUND for this opcode.</p>
<p><li><a name="sqlitefcntlrbu"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlrbu">SQLITE_FCNTL_RBU</a> opcode is implemented by the special VFS used by
the RBU extension only. All other VFS should return SQLITE_NOTFOUND for
this opcode.</p>
<p><li><a name="sqlitefcntlbeginatomicwrite"></a>
If the <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a> opcode returns SQLITE_OK, then
the file descriptor is placed in "batch write mode", which
means all subsequent write operations will be deferred and done
atomically at the next <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlcommitatomicwrite">SQLITE_FCNTL_COMMIT_ATOMIC_WRITE</a>. Systems
that do not support batch atomic writes will return SQLITE_NOTFOUND.
Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
the closing <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlcommitatomicwrite">SQLITE_FCNTL_COMMIT_ATOMIC_WRITE</a> or
<a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlrollbackatomicwrite">SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE</a>, SQLite will make
no VFS interface calls on the same <a href="../c3ref/file.html">sqlite3_file</a> file descriptor
except for calls to the xWrite method and the xFileControl method
with <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlsizehint">SQLITE_FCNTL_SIZE_HINT</a>.</p>
<p><li><a name="sqlitefcntlcommitatomicwrite"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlcommitatomicwrite">SQLITE_FCNTL_COMMIT_ATOMIC_WRITE</a> opcode causes all write
operations since the previous successful call to
<a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a> to be performed atomically.
This file control returns <a href="../rescode.html#ok">SQLITE_OK</a> if and only if the writes were
all performed successfully and have been committed to persistent storage.
Regardless of whether or not it is successful, this file control takes
the file descriptor out of batch write mode so that all subsequent
write operations are independent.
SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without
a prior successful call to <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a>.</p>
<p><li><a name="sqlitefcntlrollbackatomicwrite"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlrollbackatomicwrite">SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE</a> opcode causes all write
operations since the previous successful call to
<a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a> to be rolled back.
This file control takes the file descriptor out of batch write mode
so that all subsequent write operations are independent.
SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
a prior successful call to <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlbeginatomicwrite">SQLITE_FCNTL_BEGIN_ATOMIC_WRITE</a>.</p>
<p><li><a name="sqlitefcntllocktimeout"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntllocktimeout">SQLITE_FCNTL_LOCK_TIMEOUT</a> opcode is used to configure a VFS
to block for up to M milliseconds before failing when attempting to
obtain a file lock using the xLock or xShmLock methods of the VFS.
The parameter is a pointer to a 32-bit signed integer that contains
the value that M is to be set to. Before returning, the 32-bit signed
integer is overwritten with the previous value of M.</p>
<p><li><a name="sqlitefcntldataversion"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntldataversion">SQLITE_FCNTL_DATA_VERSION</a> opcode is used to detect changes to
a database file. The argument is a pointer to a 32-bit unsigned integer.
The "data version" for the pager is written into the pointer. The
"data version" changes whenever any change occurs to the corresponding
database file, either through SQL statements on the same database
connection or through transactions committed by separate database
connections possibly in other processes. The <a href="../c3ref/total_changes.html">sqlite3_total_changes()</a>
interface can be used to find if any database on the connection has changed,
but that interface responds to changes on TEMP as well as MAIN and does
not provide a mechanism to detect changes to MAIN only. Also, the
<a href="../c3ref/total_changes.html">sqlite3_total_changes()</a> interface responds to internal changes only and
omits changes made by other database connections. The
<a href="../pragma.html#pragma_data_version">PRAGMA data_version</a> command provides a mechanism to detect changes to
a single attached database that occur due to other database connections,
but omits changes implemented by the database connection on which it is
called. This file control is the only mechanism to detect changes that
happen either internally or externally and that are associated with
a particular attached database.</p>
<p><li><a name="sqlitefcntlckptstart"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlckptstart">SQLITE_FCNTL_CKPT_START</a> opcode is invoked from within a checkpoint
in wal mode before the client starts to copy pages from the wal
file to the database file.</p>
<p><li><a name="sqlitefcntlckptdone"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlckptdone">SQLITE_FCNTL_CKPT_DONE</a> opcode is invoked from within a checkpoint
in wal mode after the client has finished copying pages from the wal
file to the database file, but before the *-shm file is updated to
record the fact that the pages have been checkpointed.</p>
<p><li><a name="sqlitefcntlexternalreader"></a>
The EXPERIMENTAL <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlexternalreader">SQLITE_FCNTL_EXTERNAL_READER</a> opcode is used to detect
whether or not there is a database client in another process with a wal-mode
transaction open on the database or not. It is only available on unix.The
(void*) argument passed with this file-control should be a pointer to a
value of type (int). The integer value is set to 1 if the database is a wal
mode database and there exists at least one client in another process that
currently has an SQL transaction open on the database. It is set to 0 if
the database is not a wal-mode db, or if there is no such connection in any
other process. This opcode cannot be used to detect transactions opened
by clients within the current process, only within other processes.</p>
<p><li><a name="sqlitefcntlcksmfile"></a>
The <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlcksmfile">SQLITE_FCNTL_CKSM_FILE</a> opcode is for use internally by the
<a href="../cksumvfs.html">checksum VFS shim</a> only.</p>
<p><li><a name="sqlitefcntlresetcache"></a>
If there is currently no transaction open on the database, and the
database is not a temp db, then the <a href="../c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlresetcache">SQLITE_FCNTL_RESET_CACHE</a> file-control
purges the contents of the in-memory page cache. If there is an open
transaction, or if the db is a temp-db, this opcode is a no-op, not an error.
</ul>
</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>
|
