Name

sqlite3_busy_handler() — Register a busy handler

Definition

int sqlite3_busy_handler( sqlite3* db, busy_handler, void* udp );

int busy_handler( void* udp, int count );

db

A database connection.

busy_handler

A function pointer to an application busy handler function.

udp

An application-defined user-data pointer. This value is made available to the busy handler.

count

The number of times the handler has been called for this lock.

Returns (sqlite3_busy_handler())

An SQLite result code.

Returns (busy_handler())

A nonzero return code indicates that the connection should continue to wait for the desired lock. A return code of zero indicates that the database connection should give up and return SQLITE_BUSY or SQLITE_IOERR_BLOCKED to the application.

Description

This function registers a busy handler with a specific database connection. The busy handler is called any time the database connection encounters a locked database file. In most cases, the application can simply wait for the lock to be released before proceeding. In these situations, the SQLite library will keep calling the busy handler, which can decide to keep waiting, or to give up and return an error to the application.

For a full discussion of locking states and busy handlers, see the section Database Locking.

Each database connection has only one busy handler. Registering a new busy handler will replace the old one. To remove a busy handler, pass in a NULL function pointer. Setting a busy timeout with sqlite3_busy_timeout() will also reset the busy handler.

See Also

sqlite3_busy_timeout()