diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_get_auxdata.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_get_auxdata.3 | 105 |
1 files changed, 105 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_get_auxdata.3 b/static/netbsd/man3/sqlite3_get_auxdata.3 new file mode 100644 index 00000000..3220c724 --- /dev/null +++ b/static/netbsd/man3/sqlite3_get_auxdata.3 @@ -0,0 +1,105 @@ +.Dd January 24, 2024 +.Dt SQLITE3_GET_AUXDATA 3 +.Os +.Sh NAME +.Nm sqlite3_get_auxdata , +.Nm sqlite3_set_auxdata +.Nd function auxiliary data +.Sh SYNOPSIS +.In sqlite3.h +.Ft void * +.Fo sqlite3_get_auxdata +.Fa "sqlite3_context*" +.Fa "int N" +.Fc +.Ft void +.Fo sqlite3_set_auxdata +.Fa "sqlite3_context*" +.Fa "int N" +.Fa "void*" +.Fa "void (*)(void*)" +.Fc +.Sh DESCRIPTION +These functions may be used by (non-aggregate) SQL functions to associate +auxiliary data with argument values. +If the same argument value is passed to multiple invocations of the +same SQL function during query execution, under some circumstances +the associated auxiliary data might be preserved. +An example of where this might be useful is in a regular-expression +matching function. +The compiled version of the regular expression can be stored as auxiliary +data associated with the pattern string. +Then as long as the pattern string remains the same, the compiled regular +expression can be reused on multiple invocations of the same function. +.Pp +The sqlite3_get_auxdata(C,N) interface returns a pointer to the auxiliary +data associated by the sqlite3_set_auxdata(C,N,P,X) function with the +Nth argument value to the application-defined function. +N is zero for the left-most function argument. +If there is no auxiliary data associated with the function argument, +the sqlite3_get_auxdata(C,N) interface returns a NULL pointer. +.Pp +The sqlite3_set_auxdata(C,N,P,X) interface saves P as auxiliary data +for the N-th argument of the application-defined function. +Subsequent calls to sqlite3_get_auxdata(C,N) return P from the most +recent sqlite3_set_auxdata(C,N,P,X) call if the auxiliary data is still +valid or NULL if the auxiliary data has been discarded. +After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL, +SQLite will invoke the destructor function X with parameter P exactly +once, when the auxiliary data is discarded. +SQLite is free to discard the auxiliary data at any time, including: +.Bl -bullet +.It +when the corresponding function parameter changes, or +.It +when +.Fn sqlite3_reset +or +.Fn sqlite3_finalize +is called for the SQL statement, or +.It +when sqlite3_set_auxdata() is invoked again on the same parameter, +or +.It +during the original sqlite3_set_auxdata() call when a memory allocation +error occurs. +.It +during the original sqlite3_set_auxdata() call if the function is evaluated +during query planning instead of during query execution, as sometimes +happens with SQLITE_ENABLE_STAT4. +.El +.Pp +Note the last two bullets in particular. +The destructor X in sqlite3_set_auxdata(C,N,P,X) might be called immediately, +before the sqlite3_set_auxdata() interface even returns. +Hence sqlite3_set_auxdata() should be called near the end of the function +implementation and the function implementation should not make any +use of P after sqlite3_set_auxdata() has been called. +Furthermore, a call to sqlite3_get_auxdata() that occurs immediately +after a corresponding call to sqlite3_set_auxdata() might still return +NULL if an out-of-memory condition occurred during the sqlite3_set_auxdata() +call or if the function is being evaluated during query planning rather +than during query execution. +.Pp +In practice, auxiliary data is preserved between function calls for +function parameters that are compile-time constants, including literal +values and parameters and expressions composed from the same. +.Pp +The value of the N parameter to these interfaces should be non-negative. +Future enhancements may make use of negative N values to define new +kinds of function caching behavior. +.Pp +These routines must be called from the same thread in which the SQL +function is running. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5903. +.Bd -literal +SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N); +SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*)); +.Ed +.Sh SEE ALSO +.Xr sqlite3_finalize 3 , +.Xr sqlite3_get_clientdata 3 , +.Xr sqlite3_reset 3 |