1.Dd March 11, 2017 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() interface returns a pointer to the metadata 35associated by the sqlite3_set_auxdata() function with the Nth argument 36value to the application-defined function. 37If there is no metadata associated with the function argument, this 38sqlite3_get_auxdata() interface returns a NULL pointer. 39.Pp 40The sqlite3_set_auxdata(C,N,P,X) interface saves P as metadata for 41the N-th argument of the application-defined function. 42Subsequent calls to sqlite3_get_auxdata(C,N) return P from the most 43recent sqlite3_set_auxdata(C,N,P,X) call if the metadata is still valid 44or NULL if the metadata has been discarded. 45After each call to sqlite3_set_auxdata(C,N,P,X) where X is not NULL, 46SQLite will invoke the destructor function X with parameter P exactly 47once, when the metadata is discarded. 48SQLite is free to discard the metadata at any time, including: 49.Bl -bullet 50.It 51when the corresponding function parameter changes , or 52.It 53when sqlite3_reset() or sqlite3_finalize() 54is called for the SQL statement , or 55.It 56when sqlite3_set_auxdata() is invoked again on the same parameter 57, or 58.It 59during the original sqlite3_set_auxdata() call when a memory allocation 60error occurs. 61.El 62.Pp 63Note the last bullet in particular. 64The destructor X in sqlite3_set_auxdata(C,N,P,X) might be called immediately, 65before the sqlite3_set_auxdata() interface even returns. 66Hence sqlite3_set_auxdata() should be called near the end of the function 67implementation and the function implementation should not make any 68use of P after sqlite3_set_auxdata() has been called. 69.Pp 70In practice, metadata is preserved between function calls for function 71parameters that are compile-time constants, including literal values 72and parameters and expressions composed from the same. 73.Pp 74These routines must be called from the same thread in which the SQL 75function is running. 76.Sh SEE ALSO 77.Xr sqlite3_finalize 3 , 78.Xr sqlite3_reset 3 79