Updated: 2025/Nov/16

Please read Privacy Policy. It's for your privacy.

SQLITE3_GET_AUXDATA(3)     Library Functions Manual     SQLITE3_GET_AUXDATA(3)

NAME
     sqlite3_get_auxdata, sqlite3_set_auxdata - function auxiliary data

SYNOPSIS
     #include <sqlite3.h>

     void *
     sqlite3_get_auxdata(sqlite3_context*, int N);

     void
     sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));

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.

     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.

     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:

     ⊕   when the corresponding function parameter changes, or

     ⊕   when sqlite3_reset() or sqlite3_finalize() is called for the SQL
         statement, or

     ⊕   when sqlite3_set_auxdata() is invoked again on the same parameter, or

     ⊕   during the original sqlite3_set_auxdata() call when a memory
         allocation error occurs.

     ⊕   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.

     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.

     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.

     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.

     These routines must be called from the same thread in which the SQL
     function is running.

IMPLEMENTATION NOTES
     These declarations were extracted from the interface documentation at
     line 5903.

     SQLITE_API void *sqlite3_get_auxdata(sqlite3_context*, int N);
     SQLITE_API void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));

SEE ALSO
     sqlite3_finalize(3), sqlite3_get_clientdata(3), sqlite3_reset(3)

NetBSD 11.99                   January 24, 2024                   NetBSD 11.99