1.Dd January 24, 2024 2.Dt SQLITE3_WAL_HOOK 3 3.Os 4.Sh NAME 5.Nm sqlite3_wal_hook 6.Nd write-Ahead log commit hook 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft void * 10.Fo sqlite3_wal_hook 11.Fa "sqlite3*" 12.Fa "int(*)(void *,sqlite3*,const char*,int)" 13.Fa "void*" 14.Fc 15.Sh DESCRIPTION 16The 17.Fn sqlite3_wal_hook 18function is used to register a callback that is invoked each time data 19is committed to a database in wal mode. 20.Pp 21The callback is invoked by SQLite after the commit has taken place 22and the associated write-lock on the database released, so the implementation 23may read, write or checkpoint the database as required. 24.Pp 25The first parameter passed to the callback function when it is invoked 26is a copy of the third parameter passed to sqlite3_wal_hook() when 27registering the callback. 28The second is a copy of the database handle. 29The third parameter is the name of the database that was written to 30- either "main" or the name of an ATTACH-ed database. 31The fourth parameter is the number of pages currently in the write-ahead 32log file, including those that were just committed. 33.Pp 34The callback function should normally return SQLITE_OK. 35If an error code is returned, that error will propagate back up through 36the SQLite code base to cause the statement that provoked the callback 37to report an error, though the commit will have still occurred. 38If the callback returns SQLITE_ROW or SQLITE_DONE, 39or if it returns a value that does not correspond to any valid SQLite 40error code, the results are undefined. 41.Pp 42A single database handle may have at most a single write-ahead log 43callback registered at one time. 44Calling 45.Fn sqlite3_wal_hook 46replaces any previously registered write-ahead log callback. 47The return value is a copy of the third parameter from the previous 48call, if any, or 0. 49Note that the 50.Fn sqlite3_wal_autocheckpoint 51interface and the wal_autocheckpoint pragma 52both invoke 53.Fn sqlite3_wal_hook 54and will overwrite any prior 55.Fn sqlite3_wal_hook 56settings. 57.Sh IMPLEMENTATION NOTES 58These declarations were extracted from the 59interface documentation at line 9512. 60.Bd -literal 61SQLITE_API void *sqlite3_wal_hook( 62 sqlite3*, 63 int(*)(void *,sqlite3*,const char*,int), 64 void* 65); 66.Ed 67.Sh SEE ALSO 68.Xr sqlite3_wal_autocheckpoint 3 , 69.Xr SQLITE_OK 3 70