diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_preupdate_hook.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_preupdate_hook.3 | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_preupdate_hook.3 b/static/netbsd/man3/sqlite3_preupdate_hook.3 new file mode 100644 index 00000000..9283e8b9 --- /dev/null +++ b/static/netbsd/man3/sqlite3_preupdate_hook.3 @@ -0,0 +1,188 @@ +.Dd January 24, 2024 +.Dt SQLITE3_PREUPDATE_HOOK 3 +.Os +.Sh NAME +.Nm sqlite3_preupdate_hook , +.Nm sqlite3_preupdate_old , +.Nm sqlite3_preupdate_count , +.Nm sqlite3_preupdate_depth , +.Nm sqlite3_preupdate_new , +.Nm sqlite3_preupdate_blobwrite +.Nd the pre-update hook +.Sh SYNOPSIS +.In sqlite3.h +.Ft void * +.Fo sqlite3_preupdate_hook +.Fa "sqlite3 *db" +.Fa "void(*xPreUpdate)( void *pCtx,sqlite3 *db,int op,char const *zDb,char const *zName,sqlite3_int64 iKey1,sqlite3_int64 iKey2)" +.Fa "void*" +.Fc +.Ft int +.Fo sqlite3_preupdate_old +.Fa "sqlite3 *" +.Fa "int" +.Fa "sqlite3_value **" +.Fc +.Ft int +.Fo sqlite3_preupdate_count +.Fa "sqlite3 *" +.Fc +.Ft int +.Fo sqlite3_preupdate_depth +.Fa "sqlite3 *" +.Fc +.Ft int +.Fo sqlite3_preupdate_new +.Fa "sqlite3 *" +.Fa "int" +.Fa "sqlite3_value **" +.Fc +.Ft int +.Fo sqlite3_preupdate_blobwrite +.Fa "sqlite3 *" +.Fc +.Sh DESCRIPTION +These interfaces are only available if SQLite is compiled using the +SQLITE_ENABLE_PREUPDATE_HOOK compile-time +option. +.Pp +The +.Fn sqlite3_preupdate_hook +interface registers a callback function that is invoked prior to each +INSERT, UPDATE, and DELETE operation on a database +table. +At most one preupdate hook may be registered at a time on a single +database connection; each call to +.Fn sqlite3_preupdate_hook +overrides the previous setting. +The preupdate hook is disabled by invoking +.Fn sqlite3_preupdate_hook +with a NULL pointer as the second parameter. +The third parameter to +.Fn sqlite3_preupdate_hook +is passed through as the first parameter to callbacks. +.Pp +The preupdate hook only fires for changes to real database tables; +the preupdate hook is not invoked for changes to virtual tables +or to system tables like sqlite_sequence or sqlite_stat1. +.Pp +The second parameter to the preupdate callback is a pointer to the +database connection that registered the preupdate +hook. +The third parameter to the preupdate callback is one of the constants +SQLITE_INSERT, SQLITE_DELETE, or SQLITE_UPDATE +to identify the kind of update operation that is about to occur. +The fourth parameter to the preupdate callback is the name of the database +within the database connection that is being modified. +This will be "main" for the main database or "temp" for TEMP tables +or the name given after the AS keyword in the ATTACH statement +for attached databases. +The fifth parameter to the preupdate callback is the name of the table +that is being modified. +.Pp +For an UPDATE or DELETE operation on a rowid table, the +sixth parameter passed to the preupdate callback is the initial rowid +of the row being modified or deleted. +For an INSERT operation on a rowid table, or any operation on a WITHOUT +ROWID table, the value of the sixth parameter is undefined. +For an INSERT or UPDATE on a rowid table the seventh parameter is the +final rowid value of the row being inserted or updated. +The value of the seventh parameter passed to the callback function +is not defined for operations on WITHOUT ROWID tables, or for DELETE +operations on rowid tables. +.Pp +The sqlite3_preupdate_hook(D,C,P) function returns the P argument from +the previous call on the same database connection +D, or NULL for the first call on D. +.Pp +The +.Fn sqlite3_preupdate_old , +.Fn sqlite3_preupdate_new , +.Fn sqlite3_preupdate_count , +and +.Fn sqlite3_preupdate_depth +interfaces provide additional information about a preupdate event. +These routines may only be called from within a preupdate callback. +Invoking any of these routines from outside of a preupdate callback +or with a database connection pointer that is different +from the one supplied to the preupdate callback results in undefined +and probably undesirable behavior. +.Pp +The sqlite3_preupdate_count(D) interface +returns the number of columns in the row that is being inserted, updated, +or deleted. +.Pp +The sqlite3_preupdate_old(D,N,P) interface +writes into P a pointer to a protected sqlite3_value +that contains the value of the Nth column of the table row before it +is updated. +The N parameter must be between 0 and one less than the number of columns +or the behavior will be undefined. +This must only be used within SQLITE_UPDATE and SQLITE_DELETE preupdate +callbacks; if it is used by an SQLITE_INSERT callback then the behavior +is undefined. +The sqlite3_value that P points to will be destroyed when +the preupdate callback returns. +.Pp +The sqlite3_preupdate_new(D,N,P) interface +writes into P a pointer to a protected sqlite3_value +that contains the value of the Nth column of the table row after it +is updated. +The N parameter must be between 0 and one less than the number of columns +or the behavior will be undefined. +This must only be used within SQLITE_INSERT and SQLITE_UPDATE preupdate +callbacks; if it is used by an SQLITE_DELETE callback then the behavior +is undefined. +The sqlite3_value that P points to will be destroyed when +the preupdate callback returns. +.Pp +The sqlite3_preupdate_depth(D) interface +returns 0 if the preupdate callback was invoked as a result of a direct +insert, update, or delete operation; or 1 for inserts, updates, or +deletes invoked by top-level triggers; or 2 for changes resulting from +triggers called by top-level triggers; and so forth. +.Pp +When the +.Fn sqlite3_blob_write +API is used to update a blob column, the pre-update hook is invoked +with SQLITE_DELETE. +This is because the in this case the new values are not available. +In this case, when a callback made with op==SQLITE_DELETE is actually +a write using the sqlite3_blob_write() API, the +.Fn sqlite3_preupdate_blobwrite +returns the index of the column being written. +In other cases, where the pre-update hook is being invoked for some +other reason, including a regular DELETE, sqlite3_preupdate_blobwrite() +returns -1. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 10316. +.Bd -literal +#if defined(SQLITE_ENABLE_PREUPDATE_HOOK) +SQLITE_API void *sqlite3_preupdate_hook( + sqlite3 *db, + void(*xPreUpdate)( + void *pCtx, /* Copy of third arg to preupdate_hook() */ + sqlite3 *db, /* Database handle */ + int op, /* SQLITE_UPDATE, DELETE or INSERT */ + char const *zDb, /* Database name */ + char const *zName, /* Table name */ + sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */ + sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */ + ), + void* +); +SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **); +SQLITE_API int sqlite3_preupdate_count(sqlite3 *); +SQLITE_API int sqlite3_preupdate_depth(sqlite3 *); +SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **); +SQLITE_API int sqlite3_preupdate_blobwrite(sqlite3 *); +#endif +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_blob_write 3 , +.Xr sqlite3_update_hook 3 , +.Xr sqlite3_value 3 , +.Xr SQLITE_CREATE_INDEX 3 |