1.Dd January 24, 2024 2.Dt SQLITE3_PROGRESS_HANDLER 3 3.Os 4.Sh NAME 5.Nm sqlite3_progress_handler 6.Nd query progress callbacks 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft void 10.Fo sqlite3_progress_handler 11.Fa "sqlite3*" 12.Fa "int" 13.Fa "int(*)(void*)" 14.Fa "void*" 15.Fc 16.Sh DESCRIPTION 17The sqlite3_progress_handler(D,N,X,P) interface causes the callback 18function X to be invoked periodically during long running calls to 19.Fn sqlite3_step 20and 21.Fn sqlite3_prepare 22and similar for database connection D. 23An example use for this interface is to keep a GUI updated during a 24large query. 25.Pp 26The parameter P is passed through as the only parameter to the callback 27function X. 28The parameter N is the approximate number of virtual machine instructions 29that are evaluated between successive invocations of the callback X. 30If N is less than one then the progress handler is disabled. 31.Pp 32Only a single progress handler may be defined at one time per database connection; 33setting a new progress handler cancels the old one. 34Setting parameter X to NULL disables the progress handler. 35The progress handler is also disabled by setting N to a value less 36than 1. 37.Pp 38If the progress callback returns non-zero, the operation is interrupted. 39This feature can be used to implement a "Cancel" button on a GUI progress 40dialog box. 41.Pp 42The progress handler callback must not do anything that will modify 43the database connection that invoked the progress handler. 44Note that 45.Fn sqlite3_prepare_v2 46and 47.Fn sqlite3_step 48both modify their database connections for the meaning of "modify" 49in this paragraph. 50.Pp 51The progress handler callback would originally only be invoked from 52the bytecode engine. 53It still might be invoked during 54.Fn sqlite3_prepare 55and similar because those routines might force a reparse of the schema 56which involves running the bytecode engine. 57However, beginning with SQLite version 3.41.0, the progress handler 58callback might also be invoked directly from 59.Fn sqlite3_prepare 60while analyzing and generating code for complex queries. 61.Sh IMPLEMENTATION NOTES 62These declarations were extracted from the 63interface documentation at line 3421. 64.Bd -literal 65SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); 66.Ed 67.Sh SEE ALSO 68.Xr sqlite3 3 , 69.Xr sqlite3_prepare 3 , 70.Xr sqlite3_step 3 71