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
|
<!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>Checkpoint a database</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: sqlite3_wal_checkpoint_v2 -->
<div class=nosearch>
<a href="intro.html"><h2>SQLite C Interface</h2></a>
<h2>Checkpoint a database</h2>
</div>
<blockquote><pre>
int sqlite3_wal_checkpoint_v2(
sqlite3 *db, /* Database handle */
const char *zDb, /* Name of attached database (or NULL) */
int eMode, /* SQLITE_CHECKPOINT_* value */
int *pnLog, /* OUT: Size of WAL log in frames */
int *pnCkpt /* OUT: Total number of frames checkpointed */
);
</pre></blockquote>
<p>
The sqlite3_wal_checkpoint_v2(D,X,M,L,C) interface runs a checkpoint
operation on database X of <a href="../c3ref/sqlite3.html">database connection</a> D in mode M. Status
information is written back into integers pointed to by L and C.
The M parameter must be a valid <a href="../c3ref/c_checkpoint_full.html">checkpoint mode</a>:</p>
<p><dl>
<dt>SQLITE_CHECKPOINT_PASSIVE<dd>
Checkpoint as many frames as possible without waiting for any database
readers or writers to finish, then sync the database file if all frames
in the log were checkpointed. The <a href="../c3ref/busy_handler.html">busy-handler callback</a>
is never invoked in the SQLITE_CHECKPOINT_PASSIVE mode.
On the other hand, passive mode might leave the checkpoint unfinished
if there are concurrent readers or writers.</p>
<p><dt>SQLITE_CHECKPOINT_FULL<dd>
This mode blocks (it invokes the
<a href="../c3ref/busy_handler.html">busy-handler callback</a>) until there is no
database writer and all readers are reading from the most recent database
snapshot. It then checkpoints all frames in the log file and syncs the
database file. This mode blocks new database writers while it is pending,
but new database readers are allowed to continue unimpeded.</p>
<p><dt>SQLITE_CHECKPOINT_RESTART<dd>
This mode works the same way as SQLITE_CHECKPOINT_FULL with the addition
that after checkpointing the log file it blocks (calls the
<a href="../c3ref/busy_handler.html">busy-handler callback</a>)
until all readers are reading from the database file only. This ensures
that the next writer will restart the log file from the beginning.
Like SQLITE_CHECKPOINT_FULL, this mode blocks new
database writer attempts while it is pending, but does not impede readers.</p>
<p><dt>SQLITE_CHECKPOINT_TRUNCATE<dd>
This mode works the same way as SQLITE_CHECKPOINT_RESTART with the
addition that it also truncates the log file to zero bytes just prior
to a successful return.
</dl></p>
<p>If pnLog is not NULL, then *pnLog is set to the total number of frames in
the log file or to -1 if the checkpoint could not run because
of an error or because the database is not in <a href="../wal.html">WAL mode</a>. If pnCkpt is not
NULL,then *pnCkpt is set to the total number of checkpointed frames in the
log file (including any that were already checkpointed before the function
was called) or to -1 if the checkpoint could not run due to an error or
because the database is not in WAL mode. Note that upon successful
completion of an SQLITE_CHECKPOINT_TRUNCATE, the log file will have been
truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.</p>
<p>All calls obtain an exclusive "checkpoint" lock on the database file. If
any other process is running a checkpoint operation at the same time, the
lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a
busy-handler configured, it will not be invoked in this case.</p>
<p>The SQLITE_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the
exclusive "writer" lock on the database file. If the writer lock cannot be
obtained immediately, and a busy-handler is configured, it is invoked and
the writer lock retried until either the busy-handler returns 0 or the lock
is successfully obtained. The busy-handler is also invoked while waiting for
database readers as described above. If the busy-handler returns 0 before
the writer lock is obtained or while waiting for database readers, the
checkpoint operation proceeds from that point in the same way as
SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
without blocking any further. SQLITE_BUSY is returned in this case.</p>
<p>If parameter zDb is NULL or points to a zero length string, then the
specified operation is attempted on all WAL databases <a href="../lang_attach.html">attached</a> to
<a href="../c3ref/sqlite3.html">database connection</a> db. In this case the
values written to output parameters *pnLog and *pnCkpt are undefined. If
an SQLITE_BUSY error is encountered when processing one or more of the
attached WAL databases, the operation is still attempted on any remaining
attached databases and SQLITE_BUSY is returned at the end. If any other
error occurs while processing an attached database, processing is abandoned
and the error code is returned to the caller immediately. If no error
(SQLITE_BUSY or otherwise) is encountered while processing the attached
databases, SQLITE_OK is returned.</p>
<p>If database zDb is the name of an attached database that is not in WAL
mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If
zDb is not NULL (or a zero length string) and is not the name of any
attached database, SQLITE_ERROR is returned to the caller.</p>
<p>Unless it returns SQLITE_MISUSE,
the sqlite3_wal_checkpoint_v2() interface
sets the error information that is queried by
<a href="../c3ref/errcode.html">sqlite3_errcode()</a> and <a href="../c3ref/errcode.html">sqlite3_errmsg()</a>.</p>
<p>The <a href="../pragma.html#pragma_wal_checkpoint">PRAGMA wal_checkpoint</a> command can be used to invoke this interface
from SQL.
</p><p>See also lists of
<a href="objlist.html">Objects</a>,
<a href="constlist.html">Constants</a>, and
<a href="funclist.html">Functions</a>.</p>
|
