1.Dd December 19, 2018 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.Ft int 21.Fo sqlite3_bind_blob 22.Fa "sqlite3_stmt*" 23.Fa "int" 24.Fa "const void*" 25.Fa "int n" 26.Fa "void(*)(void*)" 27.Fc 28.Ft int 29.Fo sqlite3_bind_blob64 30.Fa "sqlite3_stmt*" 31.Fa "int" 32.Fa "const void*" 33.Fa "sqlite3_uint64" 34.Fa "void(*)(void*)" 35.Fc 36.Ft int 37.Fo sqlite3_bind_double 38.Fa "sqlite3_stmt*" 39.Fa "int" 40.Fa "double" 41.Fc 42.Ft int 43.Fo sqlite3_bind_int 44.Fa "sqlite3_stmt*" 45.Fa "int" 46.Fa "int" 47.Fc 48.Ft int 49.Fo sqlite3_bind_int64 50.Fa "sqlite3_stmt*" 51.Fa "int" 52.Fa "sqlite3_int64" 53.Fc 54.Ft int 55.Fo sqlite3_bind_null 56.Fa "sqlite3_stmt*" 57.Fa "int" 58.Fc 59.Ft int 60.Fo sqlite3_bind_text 61.Fa "sqlite3_stmt*" 62.Fa "int" 63.Fa "const char*" 64.Fa "int" 65.Fa "void(*)(void*)" 66.Fc 67.Ft int 68.Fo sqlite3_bind_text16 69.Fa "sqlite3_stmt*" 70.Fa "int" 71.Fa "const void*" 72.Fa "int" 73.Fa "void(*)(void*)" 74.Fc 75.Ft int 76.Fo sqlite3_bind_text64 77.Fa "sqlite3_stmt*" 78.Fa "int" 79.Fa "const char*" 80.Fa "sqlite3_uint64" 81.Fa "void(*)(void*)" 82.Fa "unsigned char encoding" 83.Fc 84.Ft int 85.Fo sqlite3_bind_value 86.Fa "sqlite3_stmt*" 87.Fa "int" 88.Fa "const sqlite3_value*" 89.Fc 90.Ft int 91.Fo sqlite3_bind_pointer 92.Fa "sqlite3_stmt*" 93.Fa "int" 94.Fa "void*" 95.Fa "const char*" 96.Fa "void(*)(void*)" 97.Fc 98.Ft int 99.Fo sqlite3_bind_zeroblob 100.Fa "sqlite3_stmt*" 101.Fa "int" 102.Fa "int n" 103.Fc 104.Ft int 105.Fo sqlite3_bind_zeroblob64 106.Fa "sqlite3_stmt*" 107.Fa "int" 108.Fa "sqlite3_uint64" 109.Fc 110.Sh DESCRIPTION 111In the SQL statement text input to sqlite3_prepare_v2() 112and its variants, literals may be replaced by a parameter 113that matches one of following templates: 114.Bl -bullet 115.It 116? 117.It 118?NNN 119.It 120:VVV 121.It 122@VVV 123.It 124$VVV 125.El 126.Pp 127In the templates above, NNN represents an integer literal, and VVV 128represents an alphanumeric identifier. 129The values of these parameters (also called "host parameter names" 130or "SQL parameters") can be set using the sqlite3_bind_*() routines 131defined here. 132.Pp 133The first argument to the sqlite3_bind_*() routines is always a pointer 134to the sqlite3_stmt object returned from sqlite3_prepare_v2() 135or its variants. 136.Pp 137The second argument is the index of the SQL parameter to be set. 138The leftmost SQL parameter has an index of 1. 139When the same named SQL parameter is used more than once, second and 140subsequent occurrences have the same index as the first occurrence. 141The index for named parameters can be looked up using the sqlite3_bind_parameter_index() 142API if desired. 143The index for "?NNN" parameters is the value of NNN. 144The NNN value must be between 1 and the sqlite3_limit() 145parameter SQLITE_LIMIT_VARIABLE_NUMBER 146(default value: 999). 147.Pp 148The third argument is the value to bind to the parameter. 149If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16() 150or sqlite3_bind_blob() is a NULL pointer then the fourth parameter 151is ignored and the end result is the same as sqlite3_bind_null(). 152.Pp 153In those routines that have a fourth argument, its value is the number 154of bytes in the parameter. 155To be clear: the value is the number of <u>bytes</u> in the value, 156not the number of characters. 157If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16() 158is negative, then the length of the string is the number of bytes up 159to the first zero terminator. 160If the fourth parameter to sqlite3_bind_blob() is negative, then the 161behavior is undefined. 162If a non-negative fourth parameter is provided to sqlite3_bind_text() 163or sqlite3_bind_text16() or sqlite3_bind_text64() then that parameter 164must be the byte offset where the NUL terminator would occur assuming 165the string were NUL terminated. 166If any NUL characters occur at byte offsets less than the value of 167the fourth parameter then the resulting string value will contain embedded 168NULs. 169The result of expressions involving strings with embedded NULs is undefined. 170.Pp 171The fifth argument to the BLOB and string binding interfaces is a destructor 172used to dispose of the BLOB or string after SQLite has finished with 173it. 174The destructor is called to dispose of the BLOB or string even if the 175call to bind API fails. 176If the fifth argument is the special value SQLITE_STATIC, 177then SQLite assumes that the information is in static, unmanaged space 178and does not need to be freed. 179If the fifth argument has the value SQLITE_TRANSIENT, 180then SQLite makes its own private copy of the data immediately, before 181the sqlite3_bind_*() routine returns. 182.Pp 183The sixth argument to sqlite3_bind_text64() must be one of SQLITE_UTF8, 184SQLITE_UTF16, SQLITE_UTF16BE, or SQLITE_UTF16LE 185to specify the encoding of the text in the third parameter. 186If the sixth argument to sqlite3_bind_text64() is not one of the allowed 187values shown above, or if the text encoding is different from the encoding 188specified by the sixth parameter, then the behavior is undefined. 189.Pp 190The sqlite3_bind_zeroblob() routine binds a BLOB of length N that is 191filled with zeroes. 192A zeroblob uses a fixed amount of memory (just an integer to hold its 193size) while it is being processed. 194Zeroblobs are intended to serve as placeholders for BLOBs whose content 195is later written using incremental BLOB I/O routines. 196A negative value for the zeroblob results in a zero-length BLOB. 197.Pp 198The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter 199in prepared statement S to have an SQL value of NULL, 200but to also be associated with the pointer P of type T. 201D is either a NULL pointer or a pointer to a destructor function for 202P. 203SQLite will invoke the destructor D with a single argument of P when 204it is finished using P. 205The T parameter should be a static string, preferably a string literal. 206The sqlite3_bind_pointer() routine is part of the pointer passing interface 207added for SQLite 3.20.0. 208.Pp 209If any of the sqlite3_bind_*() routines are called with a NULL pointer 210for the prepared statement or with a prepared statement 211for which sqlite3_step() has been called more recently 212than sqlite3_reset(), then the call will return SQLITE_MISUSE. 213If any sqlite3_bind_() routine is passed a prepared statement 214that has been finalized, the result is undefined and probably harmful. 215.Pp 216Bindings are not cleared by the sqlite3_reset() routine. 217Unbound parameters are interpreted as NULL. 218.Pp 219The sqlite3_bind_* routines return SQLITE_OK on success or 220an error code if anything goes wrong. 221SQLITE_TOOBIG might be returned if the size of a string 222or BLOB exceeds limits imposed by sqlite3_limit(SQLITE_LIMIT_LENGTH) 223or SQLITE_MAX_LENGTH. 224SQLITE_RANGE is returned if the parameter index is out 225of range. 226SQLITE_NOMEM is returned if malloc() fails. 227.Pp 228.Sh SEE ALSO 229.Xr sqlite3_stmt 3 , 230.Xr sqlite3_bind_parameter_count 3 , 231.Xr sqlite3_bind_parameter_index 3 , 232.Xr sqlite3_bind_parameter_name 3 , 233.Xr sqlite3_blob_open 3 , 234.Xr sqlite3_limit 3 , 235.Xr sqlite3_prepare 3 , 236.Xr sqlite3_reset 3 , 237.Xr sqlite3_step 3 , 238.Xr sqlite3_stmt 3 , 239.Xr SQLITE_LIMIT_LENGTH 3 , 240.Xr SQLITE_OK 3 , 241.Xr sqlite3_destructor_type 3 , 242.Xr SQLITE_OK 3 , 243.Xr sqlite3_destructor_type 3 , 244.Xr SQLITE_UTF8 3 245