Adding upstream version 3.45.1.upstream/3.45.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
author: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-04-13 14:07:11 +0000
committer: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-04-13 14:07:11 +0000
commit: 63847496f14c813a5d80efd5b7de0f1294ffe1e3 (patch)
tree: 01c7571c7c762ceee70638549a99834fdd7c411b /www/c3ref/c_fcntl_begin_atomic_write.html
parent: Initial commit. (diff)
download: sqlite3-63847496f14c813a5d80efd5b7de0f1294ffe1e3.tar.xz
sqlite3-63847496f14c813a5d80efd5b7de0f1294ffe1e3.zip
1 files changed, 545 insertions, 0 deletions
diff --git a/www/c3ref/c_fcntl_begin_atomic_write.html b/www/c3ref/c_fcntl_begin_atomic_write.html
new file mode 100644
index 0000000..76d6e5a
--- /dev/null
+++ b/www/c3ref/c_fcntl_begin_atomic_write.html
@@ -0,0 +1,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>
+
author	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-04-13 14:07:11 +0000
committer	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-04-13 14:07:11 +0000
commit	63847496f14c813a5d80efd5b7de0f1294ffe1e3 (patch)
tree	01c7571c7c762ceee70638549a99834fdd7c411b /www/c3ref/c_fcntl_begin_atomic_write.html
parent	Initial commit. (diff)
download	sqlite3-63847496f14c813a5d80efd5b7de0f1294ffe1e3.tar.xz sqlite3-63847496f14c813a5d80efd5b7de0f1294ffe1e3.zip