1.Dd January 24, 2024 2.Dt SQLITE3_GET_AUXDATA 3 3.Os 4.Sh NAME 5.Nm sqlite3_get_auxdata , 6.Nm sqlite3_set_auxdata 7.Nd function auxiliary data 8.Sh SYNOPSIS 9.In sqlite3.h 10.Ft void * 11.Fo sqlite3_get_auxdata 12.Fa "sqlite3_context*" 13.Fa "int N" 14.Fc 15.Ft void 16.Fo sqlite3_set_auxdata 17.Fa "sqlite3_context*" 18.Fa "int N" 19.Fa "void*" 20.Fa "void (*)(void*)" 21.Fc 22.Sh DESCRIPTION 23These functions may be used by (non-aggregate) SQL functions to associate 24auxiliary data with argument values. 25If the same argument value is passed to multiple invocations of the 26same SQL function during query execution, under some circumstances 27the associated auxiliary data might be preserved. 28An example of where this might be useful is in a regular-expression 29matching function. 30The compiled version of the regular expression can be stored as auxiliary 31data associated with the pattern string. 32Then as long as the pattern string remains the same, the compiled regular 33expression can be reused on multiple invocations of the same function. 34.Pp 35The sqlite3_get_auxdata(C,N) interface returns a pointer to the auxiliary 36data associated by the sqlite3_set_auxdata(C,N,P,X) function with the 37Nth argument value to the application-defined function. 38N is zero for the left-most function argument. 39If there is no auxiliary data associated with the function argument, 40the sqlite3_get_auxdata(C,N) interface returns a NULL pointer. 41.Pp 42The sqlite3_set_auxdata(C,N,P,X) interface saves P as auxiliary data 43for the N-th argument of the application-defined function. 44Subsequent calls to sqlite3_get_auxdata(C,N) return P from the most 45recent sqlite3_set_auxdata(C,N,P,X) call if the auxiliary data is still 46valid or NULL if the auxiliary data has been discarded. 47After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL, 48SQLite will invoke the destructor function X with parameter P exactly 49once, when the auxiliary data is discarded. 50SQLite is free to discard the auxiliary data at any time, including: 51.Bl -bullet 52.It 53when the corresponding function parameter changes, or 54.It 55when 56.Fn sqlite3_reset 57or 58.Fn sqlite3_finalize 59is called for the SQL statement, or 60.It 61when sqlite3_set_auxdata() is invoked again on the same parameter, 62or 63.It 64during the original sqlite3_set_auxdata() call when a memory allocation 65error occurs. 66.It 67during the original sqlite3_set_auxdata() call if the function is evaluated 68during query planning instead of during query execution, as sometimes 69happens with SQLITE_ENABLE_STAT4. 70.El 71.Pp 72Note the last two bullets in particular. 73The destructor X in sqlite3_set_auxdata(C,N,P,X) might be called immediately, 74before the sqlite3_set_auxdata() interface even returns. 75Hence sqlite3_set_auxdata() should be called near the end of the function 76implementation and the function implementation should not make any 77use of P after sqlite3_set_auxdata() has been called. 78Furthermore, a call to sqlite3_get_auxdata() that occurs immediately 79after a corresponding call to sqlite3_set_auxdata() might still return 80NULL if an out-of-memory condition occurred during the sqlite3_set_auxdata() 81call or if the function is being evaluated during query planning rather 82than during query execution. 83.Pp 84In practice, auxiliary data is preserved between function calls for 85function parameters that are compile-time constants, including literal 86values and parameters and expressions composed from the same. 87.Pp 88The value of the N parameter to these interfaces should be non-negative. 89Future enhancements may make use of negative N values to define new 90kinds of function caching behavior. 91.Pp 92These routines must be called from the same thread in which the SQL 93function is running. 94.Pp 95.Sh IMPLEMENTATION NOTES 96These declarations were extracted from the 97interface documentation at line 5903. 98.Bd -literal 99SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N); 100SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*)); 101.Ed 102.Sh SEE ALSO 103.Xr sqlite3_finalize 3 , 104.Xr sqlite3_get_clientdata 3 , 105.Xr sqlite3_reset 3 106