Debian Codegraph @

www/c3ref/wal_hook.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>Write-Ahead Log Commit Hook</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_hook -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Write-Ahead Log Commit Hook</h2>
122 </div>
123 <blockquote><pre>
124 void *sqlite3_wal_hook(
125 sqlite3*,
126 int(*)(void *,sqlite3*,const char*,int),
127 void*
128 );
129 </pre></blockquote>
130 <p>
131 The <a href="../c3ref/wal_hook.html">sqlite3_wal_hook()</a> function is used to register a callback that
132 is invoked each time data is committed to a database in wal mode.</p>
133
134 <p>The callback is invoked by SQLite after the commit has taken place and
135 the associated write-lock on the database released, so the implementation
136 may read, write or <a href="../wal.html#ckpt">checkpoint</a> the database as required.</p>
137
138 <p>The first parameter passed to the callback function when it is invoked
139 is a copy of the third parameter passed to sqlite3_wal_hook() when
140 registering the callback. The second is a copy of the database handle.
141 The third parameter is the name of the database that was written to -
142 either "main" or the name of an <a href="../lang_attach.html">ATTACH</a>-ed database. The fourth parameter
143 is the number of pages currently in the write-ahead log file,
144 including those that were just committed.</p>
145
146 <p>The callback function should normally return <a href="../rescode.html#ok">SQLITE_OK</a>. If an error
147 code is returned, that error will propagate back up through the
148 SQLite code base to cause the statement that provoked the callback
149 to report an error, though the commit will have still occurred. If the
150 callback returns <a href="../rescode.html#row">SQLITE_ROW</a> or <a href="../rescode.html#done">SQLITE_DONE</a>, or if it returns a value
151 that does not correspond to any valid SQLite error code, the results
152 are undefined.</p>
153
154 <p>A single database handle may have at most a single write-ahead log
155 callback registered at one time. Calling <a href="../c3ref/wal_hook.html">sqlite3_wal_hook()</a>
156 replaces the default behavior or previously registered write-ahead
157 log callback.</p>
158
159 <p>The return value is a copy of the third parameter from the
160 previous call, if any, or 0.</p>
161
162 <p>The <a href="../c3ref/wal_autocheckpoint.html">sqlite3_wal_autocheckpoint()</a> interface and the
163 <a href="../pragma.html#pragma_wal_autocheckpoint">wal_autocheckpoint pragma</a> both invoke <a href="../c3ref/wal_hook.html">sqlite3_wal_hook()</a> and
164 will overwrite any prior <a href="../c3ref/wal_hook.html">sqlite3_wal_hook()</a> settings.</p>
165
166 <p>If a write-ahead log callback is set using this function then
167 <a href="../c3ref/wal_checkpoint_v2.html">sqlite3_wal_checkpoint_v2()</a> or <a href="../pragma.html#pragma_wal_checkpoint">PRAGMA wal_checkpoint</a>
168 should be invoked periodically to keep the write-ahead log file
169 from growing without bound.</p>
170
171 <p>Passing a NULL pointer for the callback disables automatic
172 checkpointing entirely. To re-enable the default behavior, call
173 sqlite3_wal_autocheckpoint(db,1000) or use <a href="../pragma.html#pragma_wal_checkpoint">PRAGMA wal_checkpoint</a>.
174 </p><p>See also lists of
175 <a href="../c3ref/objlist.html">Objects</a>,
176 <a href="../c3ref/constlist.html">Constants</a>, and
177 <a href="../c3ref/funclist.html">Functions</a>.</p>
178