1.Dd January 24, 2024 2.Dt SQLITE3_GET_CLIENTDATA 3 3.Os 4.Sh NAME 5.Nm sqlite3_get_clientdata , 6.Nm sqlite3_set_clientdata 7.Nd database connection client data 8.Sh SYNOPSIS 9.In sqlite3.h 10.Ft void * 11.Fo sqlite3_get_clientdata 12.Fa "sqlite3*" 13.Fa "const char*" 14.Fc 15.Ft int 16.Fo sqlite3_set_clientdata 17.Fa "sqlite3*" 18.Fa "const char*" 19.Fa "void*" 20.Fa "void(*)(void*)" 21.Fc 22.Sh DESCRIPTION 23These functions are used to associate one or more named pointers with 24a database connection. 25A call to sqlite3_set_clientdata(D,N,P,X) causes the pointer P to be 26attached to database connection D using name N. 27Subsequent calls to sqlite3_get_clientdata(D,N) will return a copy 28of pointer P or a NULL pointer if there were no prior calls to sqlite3_set_clientdata() 29with the same values of D and N. 30Names are compared using strcmp() and are thus case sensitive. 31.Pp 32If P and X are both non-NULL, then the destructor X is invoked with 33argument P on the first of the following occurrences: 34.Bl -bullet 35.It 36An out-of-memory error occurs during the call to sqlite3_set_clientdata() 37which attempts to register pointer P. 38.It 39A subsequent call to sqlite3_set_clientdata(D,N,P,X) is made with the 40same D and N parameters. 41.It 42The database connection closes. 43SQLite does not make any guarantees about the order in which destructors 44are called, only that all destructors will be called exactly once at 45some point during the database connection closing process. 46.El 47.Pp 48SQLite does not do anything with client data other than invoke destructors 49on the client data at the appropriate time. 50The intended use for client data is to provide a mechanism for wrapper 51libraries to store additional information about an SQLite database 52connection. 53.Pp 54There is no limit (other than available memory) on the number of different 55client data pointers (with different names) that can be attached to 56a single database connection. 57However, the implementation is optimized for the case of having only 58one or two different client data names. 59Applications and wrapper libraries are discouraged from using more 60than one client data name each. 61.Pp 62There is no way to enumerate the client data pointers associated with 63a database connection. 64The N parameter can be thought of as a secret key such that only code 65that knows the secret key is able to access the associated data. 66.Pp 67Security Warning: These interfaces should not be exposed in scripting 68languages or in other circumstances where it might be possible for 69an an attacker to invoke them. 70Any agent that can invoke these interfaces can probably also take control 71of the process. 72.Pp 73Database connection client data is only available for SQLite version 743.44.0 (dateof:3.44.0) and later. 75.Pp 76.Sh IMPLEMENTATION NOTES 77These declarations were extracted from the 78interface documentation at line 5973. 79.Bd -literal 80SQLITE_API void *sqlite3_get_clientdata(sqlite3*,const char*); 81SQLITE_API int sqlite3_set_clientdata(sqlite3*, const char*, void*, void(*)(void*)); 82.Ed 83.Sh SEE ALSO 84.Xr sqlite3 3 , 85.Xr sqlite3_get_auxdata 3 86