Debian Codegraph @

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