Updated: 2025/Nov/16

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

SQLITE3_GET_CLIENTDATA(3)  Library Functions Manual  SQLITE3_GET_CLIENTDATA(3)

NAME
     sqlite3_get_clientdata, sqlite3_set_clientdata - database connection
     client data

SYNOPSIS
     #include <sqlite3.h>

     void *
     sqlite3_get_clientdata(sqlite3*, const char*);

     int
     sqlite3_set_clientdata(sqlite3*, const char*, void*, void(*)(void*));

DESCRIPTION
     These functions are used to associate one or more named pointers with a
     database connection.  A call to sqlite3_set_clientdata(D,N,P,X) causes
     the pointer P to be attached to database connection D using name N.
     Subsequent calls to sqlite3_get_clientdata(D,N) will return a copy of
     pointer P or a NULL pointer if there were no prior calls to
     sqlite3_set_clientdata() with the same values of D and N.  Names are
     compared using strcmp() and are thus case sensitive.

     If P and X are both non-NULL, then the destructor X is invoked with
     argument P on the first of the following occurrences:

     ⊕   An out-of-memory error occurs during the call to
         sqlite3_set_clientdata() which attempts to register pointer P.

     ⊕   A subsequent call to sqlite3_set_clientdata(D,N,P,X) is made with the
         same D and N parameters.

     ⊕   The database connection closes.  SQLite does not make any guarantees
         about the order in which destructors are called, only that all
         destructors will be called exactly once at some point during the
         database connection closing process.

     SQLite does not do anything with client data other than invoke
     destructors on the client data at the appropriate time.  The intended use
     for client data is to provide a mechanism for wrapper libraries to store
     additional information about an SQLite database connection.

     There is no limit (other than available memory) on the number of
     different client data pointers (with different names) that can be
     attached to a single database connection.  However, the implementation is
     optimized for the case of having only one or two different client data
     names.  Applications and wrapper libraries are discouraged from using
     more than one client data name each.

     There is no way to enumerate the client data pointers associated with a
     database connection.  The N parameter can be thought of as a secret key
     such that only code that knows the secret key is able to access the
     associated data.

     Security Warning:  These interfaces should not be exposed in scripting
     languages or in other circumstances where it might be possible for an an
     attacker to invoke them.  Any agent that can invoke these interfaces can
     probably also take control of the process.

     Database connection client data is only available for SQLite version
     3.44.0 (dateof:3.44.0) and later.

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

     SQLITE_API void *sqlite3_get_clientdata(sqlite3*,const char*);
     SQLITE_API int sqlite3_set_clientdata(sqlite3*, const char*, void*, void(*)(void*));

SEE ALSO
     sqlite3(3), sqlite3_get_auxdata(3)

NetBSD 11.99                   January 24, 2024                   NetBSD 11.99