1 .Dd April 29, 2026 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 23 These functions are used to associate one or more named pointers with 24 a database connection. 25 A call to sqlite3_set_clientdata(D,N,P,X) causes the pointer P to be 26 attached to database connection D using name N. 27 Subsequent calls to sqlite3_get_clientdata(D,N) will return a copy 28 of pointer P or a NULL pointer if there were no prior calls to sqlite3_set_clientdata() 29 with the same values of D and N. 30 Names are compared using strcmp() and are thus case sensitive. 31 It returns 0 on success and SQLITE_NOMEM on allocation failure. 32 .Pp 33 If P and X are both non-NULL, then the destructor X is invoked with 34 argument P on the first of the following occurrences: 35 .Bl -bullet 36 .It 37 An out-of-memory error occurs during the call to sqlite3_set_clientdata() 38 which attempts to register pointer P. 39 .It 40 A subsequent call to sqlite3_set_clientdata(D,N,P,X) is made with the 41 same D and N parameters. 42 .It 43 The database connection closes. 44 SQLite does not make any guarantees about the order in which destructors 45 are called, only that all destructors will be called exactly once at 46 some point during the database connection closing process. 47 .El 48 .Pp 49 SQLite does not do anything with client data other than invoke destructors 50 on the client data at the appropriate time. 51 The intended use for client data is to provide a mechanism for wrapper 52 libraries to store additional information about an SQLite database 53 connection. 54 .Pp 55 There is no limit (other than available memory) on the number of different 56 client data pointers (with different names) that can be attached to 57 a single database connection. 58 However, the current implementation stores the content on a linked 59 list. 60 Insert and retrieval performance will be proportional to the number 61 of entries. 62 The design use case, and the use case for which the implementation 63 is optimized, is that an application will store only small number of 64 client data names, typically just one or two. 65 This interface is not intended to be a generalized key/value store 66 for thousands or millions of keys. 67 It will work for that, but performance might be disappointing. 68 .Pp 69 There is no way to enumerate the client data pointers associated with 70 a database connection. 71 The N parameter can be thought of as a secret key such that only code 72 that knows the secret key is able to access the associated data. 73 .Pp 74 Security Warning: These interfaces should not be exposed in scripting 75 languages or in other circumstances where it might be possible for 76 an attacker to invoke them. 77 Any agent that can invoke these interfaces can probably also take control 78 of the process. 79 .Pp 80 Database connection client data is only available for SQLite version 81 3.44.0 (dateof:3.44.0) and later. 82 .Pp 83 .Sh IMPLEMENTATION NOTES 84 These declarations were extracted from the 85 interface documentation at line 6352. 86 .Bd -literal 87 SQLITE_API void *sqlite3_get_clientdata(sqlite3*,const char*); 88 SQLITE_API int sqlite3_set_clientdata(sqlite3*, const char*, void*, void(*)(void*)); 89 .Ed 90 .Sh SEE ALSO 91 .Xr sqlite3 3 , 92 .Xr sqlite3_get_auxdata 3 93
Indexes created Mon Sep 28 00:25:45 UTC 2026