1.Dd January 24, 2024 2.Dt SQLITE3_BIND_BLOB 3 3.Os 4.Sh NAME 5.Nm sqlite3_bind_blob , 6.Nm sqlite3_bind_blob64 , 7.Nm sqlite3_bind_double , 8.Nm sqlite3_bind_int , 9.Nm sqlite3_bind_int64 , 10.Nm sqlite3_bind_null , 11.Nm sqlite3_bind_text , 12.Nm sqlite3_bind_text16 , 13.Nm sqlite3_bind_text64 , 14.Nm sqlite3_bind_value , 15.Nm sqlite3_bind_pointer , 16.Nm sqlite3_bind_zeroblob , 17.Nm sqlite3_bind_zeroblob64 18.Nd binding values to prepared statements 19.Sh SYNOPSIS 20.In sqlite3.h 21.Ft int 22.Fo sqlite3_bind_blob 23.Fa "sqlite3_stmt*" 24.Fa "int" 25.Fa "const void*" 26.Fa "int n" 27.Fa "void(*)(void*)" 28.Fc 29.Ft int 30.Fo sqlite3_bind_blob64 31.Fa "sqlite3_stmt*" 32.Fa "int" 33.Fa "const void*" 34.Fa "sqlite3_uint64" 35.Fa "void(*)(void*)" 36.Fc 37.Ft int 38.Fo sqlite3_bind_double 39.Fa "sqlite3_stmt*" 40.Fa "int" 41.Fa "double" 42.Fc 43.Ft int 44.Fo sqlite3_bind_int 45.Fa "sqlite3_stmt*" 46.Fa "int" 47.Fa "int" 48.Fc 49.Ft int 50.Fo sqlite3_bind_int64 51.Fa "sqlite3_stmt*" 52.Fa "int" 53.Fa "sqlite3_int64" 54.Fc 55.Ft int 56.Fo sqlite3_bind_null 57.Fa "sqlite3_stmt*" 58.Fa "int" 59.Fc 60.Ft int 61.Fo sqlite3_bind_text 62.Fa "sqlite3_stmt*" 63.Fa "int" 64.Fa "const char*" 65.Fa "int" 66.Fa "void(*)(void*)" 67.Fc 68.Ft int 69.Fo sqlite3_bind_text16 70.Fa "sqlite3_stmt*" 71.Fa "int" 72.Fa "const void*" 73.Fa "int" 74.Fa "void(*)(void*)" 75.Fc 76.Ft int 77.Fo sqlite3_bind_text64 78.Fa "sqlite3_stmt*" 79.Fa "int" 80.Fa "const char*" 81.Fa "sqlite3_uint64" 82.Fa "void(*)(void*)" 83.Fa "unsigned char encoding" 84.Fc 85.Ft int 86.Fo sqlite3_bind_value 87.Fa "sqlite3_stmt*" 88.Fa "int" 89.Fa "const sqlite3_value*" 90.Fc 91.Ft int 92.Fo sqlite3_bind_pointer 93.Fa "sqlite3_stmt*" 94.Fa "int" 95.Fa "void*" 96.Fa "const char*" 97.Fa "void(*)(void*)" 98.Fc 99.Ft int 100.Fo sqlite3_bind_zeroblob 101.Fa "sqlite3_stmt*" 102.Fa "int" 103.Fa "int n" 104.Fc 105.Ft int 106.Fo sqlite3_bind_zeroblob64 107.Fa "sqlite3_stmt*" 108.Fa "int" 109.Fa "sqlite3_uint64" 110.Fc 111.Sh DESCRIPTION 112In the SQL statement text input to 113.Fn sqlite3_prepare_v2 114and its variants, literals may be replaced by a parameter 115that matches one of following templates: 116.Bl -bullet 117.It 118? 119.It 120?NNN 121.It 122:VVV 123.It 124@VVV 125.It 126$VVV 127.El 128.Pp 129In the templates above, NNN represents an integer literal, and VVV 130represents an alphanumeric identifier. 131The values of these parameters (also called "host parameter names" 132or "SQL parameters") can be set using the sqlite3_bind_*() routines 133defined here. 134.Pp 135The first argument to the sqlite3_bind_*() routines is always a pointer 136to the sqlite3_stmt object returned from 137.Fn sqlite3_prepare_v2 138or its variants. 139.Pp 140The second argument is the index of the SQL parameter to be set. 141The leftmost SQL parameter has an index of 1. 142When the same named SQL parameter is used more than once, second and 143subsequent occurrences have the same index as the first occurrence. 144The index for named parameters can be looked up using the 145.Fn sqlite3_bind_parameter_index 146API if desired. 147The index for "?NNN" parameters is the value of NNN. 148The NNN value must be between 1 and the 149.Fn sqlite3_limit 150parameter SQLITE_LIMIT_VARIABLE_NUMBER 151(default value: 32766). 152.Pp 153The third argument is the value to bind to the parameter. 154If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16() 155or sqlite3_bind_blob() is a NULL pointer then the fourth parameter 156is ignored and the end result is the same as sqlite3_bind_null(). 157If the third parameter to sqlite3_bind_text() is not NULL, then it 158should be a pointer to well-formed UTF8 text. 159If the third parameter to sqlite3_bind_text16() is not NULL, then it 160should be a pointer to well-formed UTF16 text. 161If the third parameter to sqlite3_bind_text64() is not NULL, then it 162should be a pointer to a well-formed unicode string that is either 163UTF8 if the sixth parameter is SQLITE_UTF8, or UTF16 otherwise. 164.Pp 165The byte-order of UTF16 input text is determined by the byte-order 166mark (BOM, U+FEFF) found in first character, which is removed, or in 167the absence of a BOM the byte order is the native byte order of the 168host machine for sqlite3_bind_text16() or the byte order specified 169in the 6th parameter for sqlite3_bind_text64(). 170If UTF16 input text contains invalid unicode characters, then SQLite 171might change those invalid characters into the unicode replacement 172character: U+FFFD. 173.Pp 174In those routines that have a fourth argument, its value is the number 175of bytes in the parameter. 176To be clear: the value is the number of \fIbytes\fP in the value, not the 177number of characters. 178If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16() 179is negative, then the length of the string is the number of bytes up 180to the first zero terminator. 181If the fourth parameter to sqlite3_bind_blob() is negative, then the 182behavior is undefined. 183If a non-negative fourth parameter is provided to sqlite3_bind_text() 184or sqlite3_bind_text16() or sqlite3_bind_text64() then that parameter 185must be the byte offset where the NUL terminator would occur assuming 186the string were NUL terminated. 187If any NUL characters occurs at byte offsets less than the value of 188the fourth parameter then the resulting string value will contain embedded 189NULs. 190The result of expressions involving strings with embedded NULs is undefined. 191.Pp 192The fifth argument to the BLOB and string binding interfaces controls 193or indicates the lifetime of the object referenced by the third parameter. 194These three options exist: (1) A destructor to dispose of the BLOB 195or string after SQLite has finished with it may be passed. 196It is called to dispose of the BLOB or string even if the call to the 197bind API fails, except the destructor is not called if the third parameter 198is a NULL pointer or the fourth parameter is negative. 199(2) The special constant, SQLITE_STATIC, may be passed 200to indicate that the application remains responsible for disposing 201of the object. 202In this case, the object and the provided pointer to it must remain 203valid until either the prepared statement is finalized or the same 204SQL parameter is bound to something else, whichever occurs sooner. 205(3) The constant, SQLITE_TRANSIENT, may be passed to 206indicate that the object is to be copied prior to the return from sqlite3_bind_*(). 207The object and pointer to it must remain valid until then. 208SQLite will then manage the lifetime of its private copy. 209.Pp 210The sixth argument to sqlite3_bind_text64() must be one of SQLITE_UTF8, 211SQLITE_UTF16, SQLITE_UTF16BE, or SQLITE_UTF16LE 212to specify the encoding of the text in the third parameter. 213If the sixth argument to sqlite3_bind_text64() is not one of the allowed 214values shown above, or if the text encoding is different from the encoding 215specified by the sixth parameter, then the behavior is undefined. 216.Pp 217The sqlite3_bind_zeroblob() routine binds a BLOB of length N that is 218filled with zeroes. 219A zeroblob uses a fixed amount of memory (just an integer to hold its 220size) while it is being processed. 221Zeroblobs are intended to serve as placeholders for BLOBs whose content 222is later written using incremental BLOB I/O routines. 223A negative value for the zeroblob results in a zero-length BLOB. 224.Pp 225The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter 226in prepared statement S to have an SQL value of NULL, 227but to also be associated with the pointer P of type T. 228D is either a NULL pointer or a pointer to a destructor function for 229P. 230SQLite will invoke the destructor D with a single argument of P when 231it is finished using P. 232The T parameter should be a static string, preferably a string literal. 233The sqlite3_bind_pointer() routine is part of the pointer passing interface 234added for SQLite 3.20.0. 235.Pp 236If any of the sqlite3_bind_*() routines are called with a NULL pointer 237for the prepared statement or with a prepared statement 238for which 239.Fn sqlite3_step 240has been called more recently than 241.Fn sqlite3_reset , 242then the call will return SQLITE_MISUSE. 243If any sqlite3_bind_() routine is passed a prepared statement 244that has been finalized, the result is undefined and probably harmful. 245.Pp 246Bindings are not cleared by the 247.Fn sqlite3_reset 248routine. 249Unbound parameters are interpreted as NULL. 250.Pp 251The sqlite3_bind_* routines return SQLITE_OK on success or 252an error code if anything goes wrong. 253SQLITE_TOOBIG might be returned if the size of a string 254or BLOB exceeds limits imposed by sqlite3_limit(SQLITE_LIMIT_LENGTH) 255or SQLITE_MAX_LENGTH. 256SQLITE_RANGE is returned if the parameter index is out 257of range. 258SQLITE_NOMEM is returned if malloc() fails. 259.Pp 260.Sh IMPLEMENTATION NOTES 261These declarations were extracted from the 262interface documentation at line 4543. 263.Bd -literal 264SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); 265SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64, 266 void(*)(void*)); 267SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double); 268SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int); 269SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); 270SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int); 271SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*)); 272SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); 273SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64, 274 void(*)(void*), unsigned char encoding); 275SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); 276SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*)); 277SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); 278SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64); 279.Ed 280.Sh SEE ALSO 281.Xr sqlite3_bind_parameter_count 3 , 282.Xr sqlite3_bind_parameter_index 3 , 283.Xr sqlite3_bind_parameter_name 3 , 284.Xr sqlite3_blob_open 3 , 285.Xr sqlite3_destructor_type 3 , 286.Xr sqlite3_limit 3 , 287.Xr sqlite3_prepare 3 , 288.Xr sqlite3_reset 3 , 289.Xr sqlite3_step 3 , 290.Xr sqlite3_stmt 3 , 291.Xr SQLITE_LIMIT_LENGTH 3 , 292.Xr SQLITE_OK 3 , 293.Xr SQLITE_UTF8 3 294