52 lines
1.9 KiB
Groff
52 lines
1.9 KiB
Groff
.Dd March 11, 2017
|
|
.Dt SQLITE3_WAL_HOOK 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sqlite3_wal_hook
|
|
.Nd Write-Ahead Log Commit Hook
|
|
.Sh SYNOPSIS
|
|
.Ft void *
|
|
.Fo sqlite3_wal_hook
|
|
.Fa "sqlite3*"
|
|
.Fa "int(*)(void *,sqlite3*,const char*,int)"
|
|
.Fa "void* "
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
The 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 sqlite3_wal_hook() replaces any previously
|
|
registered write-ahead log callback.
|
|
Note that the sqlite3_wal_autocheckpoint()
|
|
interface and the wal_autocheckpoint pragma
|
|
both invoke sqlite3_wal_hook() and will overwrite
|
|
any prior sqlite3_wal_hook() settings.
|
|
.Sh SEE ALSO
|
|
.Xr sqlite3_wal_autocheckpoint 3 ,
|
|
.Xr sqlite3_wal_hook 3 ,
|
|
.Xr SQLITE_OK 3
|