1.Dd December 19, 2018 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.Ft void * 10.Fo sqlite3_get_auxdata 11.Fa "sqlite3_context*" 12.Fa "int N" 13.Fc 14.Ft void 15.Fo sqlite3_set_auxdata 16.Fa "sqlite3_context*" 17.Fa "int N" 18.Fa "void*" 19.Fa "void (*)(void*)" 20.Fc 21.Sh DESCRIPTION 22These functions may be used by (non-aggregate) SQL functions to associate 23metadata with argument values. 24If the same value is passed to multiple invocations of the same SQL 25function during query execution, under some circumstances the associated 26metadata may be preserved. 27An example of where this might be useful is in a regular-expression 28matching function. 29The compiled version of the regular expression can be stored as metadata 30associated with the pattern string. 31Then as long as the pattern string remains the same, the compiled regular 32expression can be reused on multiple invocations of the same function. 33.Pp 34The sqlite3_get_auxdata(C,N) interface returns a pointer to the metadata 35associated by the sqlite3_set_auxdata(C,N,P,X) function with the Nth 36argument value to the application-defined function. 37N is zero for the left-most function argument. 38If there is no metadata associated with the function argument, the 39sqlite3_get_auxdata(C,N) interface returns a NULL pointer. 40.Pp 41The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for 42the N-th argument of the application-defined function. 43Subsequent calls to sqlite3_get_auxdata(C,N) return P from the most 44recent sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid 45or NULL if the metadata has been discarded. 46After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL, 47SQLite will invoke the destructor function X with parameter P exactly 48once, when the metadata is discarded. 49SQLite is free to discard the metadata at any time, including: 50.Bl -bullet 51.It 52when the corresponding function parameter changes , or 53.It 54when sqlite3_reset() or sqlite3_finalize() 55is called for the SQL statement , or 56.It 57when sqlite3_set_auxdata() is invoked again on the same parameter 58, or 59.It 60during the original sqlite3_set_auxdata() call when a memory allocation 61error occurs. 62.El 63.Pp 64Note the last bullet in particular. 65The destructor X in sqlite3_set_auxdata(C,N,P,X) might be called immediately, 66before the sqlite3_set_auxdata() interface even returns. 67Hence sqlite3_set_auxdata() should be called near the end of the function 68implementation and the function implementation should not make any 69use of P after sqlite3_set_auxdata() has been called. 70.Pp 71In practice, metadata is preserved between function calls for function 72parameters that are compile-time constants, including literal values 73and parameters and expressions composed from the same. 74.Pp 75The value of the N parameter to these interfaces should be non-negative. 76Future enhancements may make use of negative N values to define new 77kinds of function caching behavior. 78.Pp 79These routines must be called from the same thread in which the SQL 80function is running. 81.Sh SEE ALSO 82.Xr sqlite3_finalize 3 , 83.Xr sqlite3_reset 3 84