Debian Codegraph @

www/c3ref/wal_checkpoint_v2.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>Checkpoint a database</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: sqlite3_wal_checkpoint_v2 -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Checkpoint a database</h2>
122 </div>
123 <blockquote><pre>
124 int sqlite3_wal_checkpoint_v2(
125 sqlite3 *db, /* Database handle */
126 const char *zDb, /* Name of attached database (or NULL) */
127 int eMode, /* SQLITE_CHECKPOINT_* value */
128 int *pnLog, /* OUT: Size of WAL log in frames */
129 int *pnCkpt /* OUT: Total number of frames checkpointed */
130 );
131 </pre></blockquote>
132 <p>
133 The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint
134 operation on database X of <a href="../c3ref/sqlite3.html">database connection</a> D in mode M. Status
135 information is written back into integers pointed to by L and C.
136 The M parameter must be a valid <a href="../c3ref/c_checkpoint_full.html">checkpoint mode</a>:</p>
137
138 <p><dl>
139 <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
140 Checkpoint as many frames as possible without waiting for any database
141 readers or writers to finish, then sync the database file if all frames
142 in the log were checkpointed. The <a href="../c3ref/busy_handler.html">busy-handler callback</a>
143 is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.
144 On the other hand, passive mode might leave the checkpoint unfinished
145 if there are concurrent readers or writers.</p>
146
147 <p><dt>SQLITE_CHECKPOINT_FULL<dd>
148 This mode blocks (it invokes the
149 <a href="../c3ref/busy_handler.html">busy-handler callback</a>) until there is no
150 database writer and all readers are reading from the most recent database
151 snapshot. It then checkpoints all frames in the log file and syncs the
152 database file. This mode blocks new database writers while it is pending,
153 but new database readers are allowed to continue unimpeded.</p>
154
155 <p><dt>SQLITE_CHECKPOINT_RESTART<dd>
156 This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition
157 that after checkpointing the log file it blocks (calls the
158 <a href="../c3ref/busy_handler.html">busy-handler callback</a>)
159 until all readers are reading from the database file only. This ensures
160 that the next writer will restart the log file from the beginning.
161 Like SQLITE_CHECKPOINT_FULL, this mode blocks new
162 database writer attempts while it is pending, but does not impede readers.</p>
163
164 <p><dt>SQLITE_CHECKPOINT_TRUNCATE<dd>
165 This mode works the same way as SQLITE_CHECKPOINT_RESTART with the
166 addition that it also truncates the log file to zero bytes just prior
167 to a successful return.</p>
168
169 <p><dt>SQLITE_CHECKPOINT_NOOP<dd>
170 This mode always checkpoints zero frames. The only reason to invoke
171 a NOOP checkpoint is to access the values returned by
172 sqlite3_wal_checkpoint_v2() via output parameters *pnLog and *pnCkpt.
173 </dl></p>
174
175 <p>If pnLog is not NULL, then *pnLog is set to the total number of frames in
176 the log file or to -1 if the checkpoint could not run because
177 of an error or because the database is not in <a href="../wal.html">WAL mode</a>. If pnCkpt is not
178 NULL,then *pnCkpt is set to the total number of checkpointed frames in the
179 log file (including any that were already checkpointed before the function
180 was called) or to -1 if the checkpoint could not run due to an error or
181 because the database is not in WAL mode. Note that upon successful
182 completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been
183 truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.</p>
184
185 <p>All calls obtain an exclusive "checkpoint" lock on the database file. If
186 any other process is running a checkpoint operation at the same time, the
187 lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a
188 busy-handler configured, it will not be invoked in this case.</p>
189
190 <p>The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the
191 exclusive "writer" lock on the database file. If the writer lock cannot be
192 obtained immediately, and a busy-handler is configured, it is invoked and
193 the writer lock retried until either the busy-handler returns 0 or the lock
194 is successfully obtained. The busy-handler is also invoked while waiting for
195 database readers as described above. If the busy-handler returns 0 before
196 the writer lock is obtained or while waiting for database readers, the
197 checkpoint operation proceeds from that point in the same way as
198 SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
199 without blocking any further. SQLITE_BUSY is returned in this case.</p>
200
201 <p>If parameter zDb is NULL or points to a zero length string, then the
202 specified operation is attempted on all WAL databases <a href="../lang_attach.html">attached</a> to
203 <a href="../c3ref/sqlite3.html">database connection</a> db. In this case the
204 values written to output parameters *pnLog and *pnCkpt are undefined. If
205 an SQLITE_BUSY error is encountered when processing one or more of the
206 attached WAL databases, the operation is still attempted on any remaining
207 attached databases and SQLITE_BUSY is returned at the end. If any other
208 error occurs while processing an attached database, processing is abandoned
209 and the error code is returned to the caller immediately. If no error
210 (SQLITE_BUSY or otherwise) is encountered while processing the attached
211 databases, SQLITE_OK is returned.</p>
212
213 <p>If database zDb is the name of an attached database that is not in WAL
214 mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If
215 zDb is not NULL (or a zero length string) and is not the name of any
216 attached database, SQLITE_ERROR is returned to the caller.</p>
217
218 <p>Unless it returns SQLITE_MISUSE,
219 the sqlite3_wal_checkpoint_v2() interface
220 sets the error information that is queried by
221 <a href="../c3ref/errcode.html">sqlite3_errcode()</a> and <a href="../c3ref/errcode.html">sqlite3_errmsg()</a>.</p>
222
223 <p>The <a href="../pragma.html#pragma_wal_checkpoint">PRAGMA wal_checkpoint</a> command can be used to invoke this interface
224 from SQL.
225 </p><p>See also lists of
226 <a href="../c3ref/objlist.html">Objects</a>,
227 <a href="../c3ref/constlist.html">Constants</a>, and
228 <a href="../c3ref/funclist.html">Functions</a>.</p>
229