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