Updated: 2025/Nov/16

Please read Privacy Policy. It's for your privacy.

SQLITE3_PROGRESS_HANDLER(3)                           Library Functions Manual

NAME
     sqlite3_progress_handler - query progress callbacks

SYNOPSIS
     #include <sqlite3.h>

     void
     sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);

DESCRIPTION
     The sqlite3_progress_handler(D,N,X,P) interface causes the callback
     function X to be invoked periodically during long running calls to
     sqlite3_step() and sqlite3_prepare() and similar for database connection
     D.  An example use for this interface is to keep a GUI updated during a
     large query.

     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.

     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.

     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.

     The progress handler callback must not do anything that will modify the
     database connection that invoked the progress handler.  Note that
     sqlite3_prepare_v2() and sqlite3_step() both modify their database
     connections for the meaning of "modify" in this paragraph.

     The progress handler callback would originally only be invoked from the
     bytecode engine.  It still might be invoked during 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 sqlite3_prepare() while analyzing and generating code for
     complex queries.

IMPLEMENTATION NOTES
     These declarations were extracted from the interface documentation at
     line 3421.

     SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);

SEE ALSO
     sqlite3(3), sqlite3_prepare(3), sqlite3_step(3)

NetBSD 11.99                   January 24, 2024                   NetBSD 11.99