1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
3
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
4
<title>Checkpoint a database</title>
5
<style type="text/css">
8
font-family: Verdana, sans-serif;
13
a:visited { color: #734559 }
15
.logo { position:absolute; margin:3px; }
31
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
32
.toolbar a:visited { color: white; }
33
.toolbar a:hover { color: #044a64; background: white; }
35
.content { margin: 5%; }
36
.content dt { font-weight:bold; }
37
.content dd { margin-bottom: 25px; margin-left:20%; }
38
.content ul { padding:0px; padding-left: 15px; margin:0px; }
41
.se { background: url(../images/se.gif) 100% 100% no-repeat #044a64}
42
.sw { background: url(../images/sw.gif) 0% 100% no-repeat }
43
.ne { background: url(../images/ne.gif) 100% 0% no-repeat }
44
.nw { background: url(../images/nw.gif) 0% 0% no-repeat }
46
/* Things for "fancyformat" documents start here. */
47
.fancy img+p {font-style:italic}
48
.fancy .codeblock i { color: darkblue; }
49
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
50
.fancy h2 { margin-left: 10px }
51
.fancy h3 { margin-left: 20px }
52
.fancy h4 { margin-left: 30px }
53
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
54
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
55
.fancy #toc a { color: darkblue ; text-decoration: none }
56
.fancy .todo { color: #AA3333 ; font-style : italic }
57
.fancy .todo:before { content: 'TODO:' }
58
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
59
.fancy img { display:block; }
60
.fancy :link:hover, .fancy :visited:hover { background: wheat }
61
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
62
.fancy li p { margin: 1em 0 }
63
/* End of "fancyformat" specific rules. */
69
<div><!-- container div to satisfy validator -->
71
<a href="../index.html">
72
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
74
<div><!-- IE hack to prevent disappearing logo--></div>
75
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
77
<table width=100% style="clear:both"><tr><td>
78
<div class="se"><div class="sw"><div class="ne"><div class="nw">
79
<table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
82
<a href="../about.html">About</a>
83
<a href="../sitemap.html">Sitemap</a>
84
<a href="../docs.html">Documentation</a>
85
<a href="../download.html">Download</a>
86
<a href="../copyright.html">License</a>
87
<a href="../news.html">News</a>
88
<a href="../support.html">Support</a>
91
gMsg = "Search SQLite Docs..."
92
function entersearch() {
93
var q = document.getElementById("q");
94
if( q.value == gMsg ) { q.value = "" }
95
q.style.color = "black"
96
q.style.fontStyle = "normal"
98
function leavesearch() {
99
var q = document.getElementById("q");
100
if( q.value == "" ) {
102
q.style.color = "#044a64"
103
q.style.fontStyle = "italic"
108
<div style="padding:0 1em 0px 0;white-space:nowrap">
109
<form name=f method="GET" action="http://www.sqlite.org/search">
110
<input id=q name=q type=text
111
onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
112
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
116
</div></div></div></div>
118
<div class=startsearch></div>
120
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Checkpoint a database</h2><blockquote><pre>int sqlite3_wal_checkpoint_v2(
121
sqlite3 *db, /* Database handle */
122
const char *zDb, /* Name of attached database (or NULL) */
123
int eMode, /* SQLITE_CHECKPOINT_* value */
124
int *pnLog, /* OUT: Size of WAL log in frames */
125
int *pnCkpt /* OUT: Total number of frames checkpointed */
127
</pre></blockquote><p>
128
Run a checkpoint operation on WAL database zDb attached to database
129
handle db. The specific operation is determined by the value of the
133
<dt>SQLITE_CHECKPOINT_PASSIVE<dd>
134
Checkpoint as many frames as possible without waiting for any database
135
readers or writers to finish. Sync the db file if all frames in the log
136
are checkpointed. This mode is the same as calling
137
sqlite3_wal_checkpoint(). The busy-handler callback is never invoked.</p>
139
<p><dt>SQLITE_CHECKPOINT_FULL<dd>
140
This mode blocks (calls the busy-handler callback) until there is no
141
database writer and all readers are reading from the most recent database
142
snapshot. It then checkpoints all frames in the log file and syncs the
143
database file. This call blocks database writers while it is running,
144
but not database readers.</p>
146
<p><dt>SQLITE_CHECKPOINT_RESTART<dd>
147
This mode works the same way as SQLITE_CHECKPOINT_FULL, except after
148
checkpointing the log file it blocks (calls the busy-handler callback)
149
until all readers are reading from the database file only. This ensures
150
that the next client to write to the database file restarts the log file
151
from the beginning. This call blocks database writers while it is running,
152
but not database readers.
155
<p>If pnLog is not NULL, then *pnLog is set to the total number of frames in
156
the log file before returning. If pnCkpt is not NULL, then *pnCkpt is set to
157
the total number of checkpointed frames (including any that were already
158
checkpointed when this function is called). *pnLog and *pnCkpt may be
159
populated even if sqlite3_wal_checkpoint_v2() returns other than SQLITE_OK.
160
If no values are available because of an error, they are both set to -1
161
before returning to communicate this to the caller.</p>
163
<p>All calls obtain an exclusive "checkpoint" lock on the database file. If
164
any other process is running a checkpoint operation at the same time, the
165
lock cannot be obtained and SQLITE_BUSY is returned. Even if there is a
166
busy-handler configured, it will not be invoked in this case.</p>
168
<p>The SQLITE_CHECKPOINT_FULL and RESTART modes also obtain the exclusive
169
"writer" lock on the database file. If the writer lock cannot be obtained
170
immediately, and a busy-handler is configured, it is invoked and the writer
171
lock retried until either the busy-handler returns 0 or the lock is
172
successfully obtained. The busy-handler is also invoked while waiting for
173
database readers as described above. If the busy-handler returns 0 before
174
the writer lock is obtained or while waiting for database readers, the
175
checkpoint operation proceeds from that point in the same way as
176
SQLITE_CHECKPOINT_PASSIVE - checkpointing as many frames as possible
177
without blocking any further. SQLITE_BUSY is returned in this case.</p>
179
<p>If parameter zDb is NULL or points to a zero length string, then the
180
specified operation is attempted on all WAL databases. In this case the
181
values written to output parameters *pnLog and *pnCkpt are undefined. If
182
an SQLITE_BUSY error is encountered when processing one or more of the
183
attached WAL databases, the operation is still attempted on any remaining
184
attached databases and SQLITE_BUSY is returned to the caller. If any other
185
error occurs while processing an attached database, processing is abandoned
186
and the error code returned to the caller immediately. If no error
187
(SQLITE_BUSY or otherwise) is encountered while processing the attached
188
databases, SQLITE_OK is returned.</p>
190
<p>If database zDb is the name of an attached database that is not in WAL
191
mode, SQLITE_OK is returned and both *pnLog and *pnCkpt set to -1. If
192
zDb is not NULL (or a zero length string) and is not the name of any
193
attached database, SQLITE_ERROR is returned to the caller.
194
</p><p>See also lists of
195
<a href="objlist.html">Objects</a>,
196
<a href="constlist.html">Constants</a>, and
197
<a href="funclist.html">Functions</a>.</p>
added
removed
c3ref/wal_checkpoint_v2.html
