diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_progress_handler.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_progress_handler.3 | 70 |
1 files changed, 70 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_progress_handler.3 b/static/netbsd/man3/sqlite3_progress_handler.3 new file mode 100644 index 00000000..20af7b30 --- /dev/null +++ b/static/netbsd/man3/sqlite3_progress_handler.3 @@ -0,0 +1,70 @@ +.Dd January 24, 2024 +.Dt SQLITE3_PROGRESS_HANDLER 3 +.Os +.Sh NAME +.Nm sqlite3_progress_handler +.Nd query progress callbacks +.Sh SYNOPSIS +.In sqlite3.h +.Ft void +.Fo sqlite3_progress_handler +.Fa "sqlite3*" +.Fa "int" +.Fa "int(*)(void*)" +.Fa "void*" +.Fc +.Sh DESCRIPTION +The sqlite3_progress_handler(D,N,X,P) interface causes the callback +function X to be invoked periodically during long running calls to +.Fn sqlite3_step +and +.Fn sqlite3_prepare +and similar for database connection D. +An example use for this interface is to keep a GUI updated during a +large query. +.Pp +The parameter P is passed through as the only parameter to the callback +function X. +The parameter N is the approximate number of virtual machine instructions +that are evaluated between successive invocations of the callback X. +If N is less than one then the progress handler is disabled. +.Pp +Only a single progress handler may be defined at one time per database connection; +setting a new progress handler cancels the old one. +Setting parameter X to NULL disables the progress handler. +The progress handler is also disabled by setting N to a value less +than 1. +.Pp +If the progress callback returns non-zero, the operation is interrupted. +This feature can be used to implement a "Cancel" button on a GUI progress +dialog box. +.Pp +The progress handler callback must not do anything that will modify +the database connection that invoked the progress handler. +Note that +.Fn sqlite3_prepare_v2 +and +.Fn sqlite3_step +both modify their database connections for the meaning of "modify" +in this paragraph. +.Pp +The progress handler callback would originally only be invoked from +the bytecode engine. +It still might be invoked during +.Fn sqlite3_prepare +and similar because those routines might force a reparse of the schema +which involves running the bytecode engine. +However, beginning with SQLite version 3.41.0, the progress handler +callback might also be invoked directly from +.Fn sqlite3_prepare +while analyzing and generating code for complex queries. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 3421. +.Bd -literal +SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_step 3 |