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
|
.Dd January 24, 2024
.Dt SQLITE3_WAL_HOOK 3
.Os
.Sh NAME
.Nm sqlite3_wal_hook
.Nd write-Ahead log commit hook
.Sh SYNOPSIS
.In sqlite3.h
.Ft void *
.Fo sqlite3_wal_hook
.Fa "sqlite3*"
.Fa "int(*)(void *,sqlite3*,const char*,int)"
.Fa "void*"
.Fc
.Sh DESCRIPTION
The
.Fn sqlite3_wal_hook
function is used to register a callback that is invoked each time data
is committed to a database in wal mode.
.Pp
The callback is invoked by SQLite after the commit has taken place
and the associated write-lock on the database released, so the implementation
may read, write or checkpoint the database as required.
.Pp
The first parameter passed to the callback function when it is invoked
is a copy of the third parameter passed to sqlite3_wal_hook() when
registering the callback.
The second is a copy of the database handle.
The third parameter is the name of the database that was written to
- either "main" or the name of an ATTACH-ed database.
The fourth parameter is the number of pages currently in the write-ahead
log file, including those that were just committed.
.Pp
The callback function should normally return SQLITE_OK.
If an error code is returned, that error will propagate back up through
the SQLite code base to cause the statement that provoked the callback
to report an error, though the commit will have still occurred.
If the callback returns SQLITE_ROW or SQLITE_DONE,
or if it returns a value that does not correspond to any valid SQLite
error code, the results are undefined.
.Pp
A single database handle may have at most a single write-ahead log
callback registered at one time.
Calling
.Fn sqlite3_wal_hook
replaces any previously registered write-ahead log callback.
The return value is a copy of the third parameter from the previous
call, if any, or 0.
Note that the
.Fn sqlite3_wal_autocheckpoint
interface and the wal_autocheckpoint pragma
both invoke
.Fn sqlite3_wal_hook
and will overwrite any prior
.Fn sqlite3_wal_hook
settings.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 9512.
.Bd -literal
SQLITE_API void *sqlite3_wal_hook(
sqlite3*,
int(*)(void *,sqlite3*,const char*,int),
void*
);
.Ed
.Sh SEE ALSO
.Xr sqlite3_wal_autocheckpoint 3 ,
.Xr SQLITE_OK 3
|
