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