diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_bind_blob.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_bind_blob.3 | 293 |
1 files changed, 293 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_bind_blob.3 b/static/netbsd/man3/sqlite3_bind_blob.3 new file mode 100644 index 00000000..1f319956 --- /dev/null +++ b/static/netbsd/man3/sqlite3_bind_blob.3 @@ -0,0 +1,293 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BIND_BLOB 3 +.Os +.Sh NAME +.Nm sqlite3_bind_blob , +.Nm sqlite3_bind_blob64 , +.Nm sqlite3_bind_double , +.Nm sqlite3_bind_int , +.Nm sqlite3_bind_int64 , +.Nm sqlite3_bind_null , +.Nm sqlite3_bind_text , +.Nm sqlite3_bind_text16 , +.Nm sqlite3_bind_text64 , +.Nm sqlite3_bind_value , +.Nm sqlite3_bind_pointer , +.Nm sqlite3_bind_zeroblob , +.Nm sqlite3_bind_zeroblob64 +.Nd binding values to prepared statements +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_bind_blob +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "const void*" +.Fa "int n" +.Fa "void(*)(void*)" +.Fc +.Ft int +.Fo sqlite3_bind_blob64 +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "const void*" +.Fa "sqlite3_uint64" +.Fa "void(*)(void*)" +.Fc +.Ft int +.Fo sqlite3_bind_double +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "double" +.Fc +.Ft int +.Fo sqlite3_bind_int +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "int" +.Fc +.Ft int +.Fo sqlite3_bind_int64 +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "sqlite3_int64" +.Fc +.Ft int +.Fo sqlite3_bind_null +.Fa "sqlite3_stmt*" +.Fa "int" +.Fc +.Ft int +.Fo sqlite3_bind_text +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "const char*" +.Fa "int" +.Fa "void(*)(void*)" +.Fc +.Ft int +.Fo sqlite3_bind_text16 +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "const void*" +.Fa "int" +.Fa "void(*)(void*)" +.Fc +.Ft int +.Fo sqlite3_bind_text64 +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "const char*" +.Fa "sqlite3_uint64" +.Fa "void(*)(void*)" +.Fa "unsigned char encoding" +.Fc +.Ft int +.Fo sqlite3_bind_value +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "const sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_bind_pointer +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "void*" +.Fa "const char*" +.Fa "void(*)(void*)" +.Fc +.Ft int +.Fo sqlite3_bind_zeroblob +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "int n" +.Fc +.Ft int +.Fo sqlite3_bind_zeroblob64 +.Fa "sqlite3_stmt*" +.Fa "int" +.Fa "sqlite3_uint64" +.Fc +.Sh DESCRIPTION +In the SQL statement text input to +.Fn sqlite3_prepare_v2 +and its variants, literals may be replaced by a parameter +that matches one of following templates: +.Bl -bullet +.It +? +.It +?NNN +.It +:VVV +.It +@VVV +.It +$VVV +.El +.Pp +In the templates above, NNN represents an integer literal, and VVV +represents an alphanumeric identifier. +The values of these parameters (also called "host parameter names" +or "SQL parameters") can be set using the sqlite3_bind_*() routines +defined here. +.Pp +The first argument to the sqlite3_bind_*() routines is always a pointer +to the sqlite3_stmt object returned from +.Fn sqlite3_prepare_v2 +or its variants. +.Pp +The second argument is the index of the SQL parameter to be set. +The leftmost SQL parameter has an index of 1. +When the same named SQL parameter is used more than once, second and +subsequent occurrences have the same index as the first occurrence. +The index for named parameters can be looked up using the +.Fn sqlite3_bind_parameter_index +API if desired. +The index for "?NNN" parameters is the value of NNN. +The NNN value must be between 1 and the +.Fn sqlite3_limit +parameter SQLITE_LIMIT_VARIABLE_NUMBER +(default value: 32766). +.Pp +The third argument is the value to bind to the parameter. +If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16() +or sqlite3_bind_blob() is a NULL pointer then the fourth parameter +is ignored and the end result is the same as sqlite3_bind_null(). +If the third parameter to sqlite3_bind_text() is not NULL, then it +should be a pointer to well-formed UTF8 text. +If the third parameter to sqlite3_bind_text16() is not NULL, then it +should be a pointer to well-formed UTF16 text. +If the third parameter to sqlite3_bind_text64() is not NULL, then it +should be a pointer to a well-formed unicode string that is either +UTF8 if the sixth parameter is SQLITE_UTF8, or UTF16 otherwise. +.Pp +The byte-order of UTF16 input text is determined by the byte-order +mark (BOM, U+FEFF) found in first character, which is removed, or in +the absence of a BOM the byte order is the native byte order of the +host machine for sqlite3_bind_text16() or the byte order specified +in the 6th parameter for sqlite3_bind_text64(). +If UTF16 input text contains invalid unicode characters, then SQLite +might change those invalid characters into the unicode replacement +character: U+FFFD. +.Pp +In those routines that have a fourth argument, its value is the number +of bytes in the parameter. +To be clear: the value is the number of \fIbytes\fP in the value, not the +number of characters. +If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16() +is negative, then the length of the string is the number of bytes up +to the first zero terminator. +If the fourth parameter to sqlite3_bind_blob() is negative, then the +behavior is undefined. +If a non-negative fourth parameter is provided to sqlite3_bind_text() +or sqlite3_bind_text16() or sqlite3_bind_text64() then that parameter +must be the byte offset where the NUL terminator would occur assuming +the string were NUL terminated. +If any NUL characters occurs at byte offsets less than the value of +the fourth parameter then the resulting string value will contain embedded +NULs. +The result of expressions involving strings with embedded NULs is undefined. +.Pp +The fifth argument to the BLOB and string binding interfaces controls +or indicates the lifetime of the object referenced by the third parameter. +These three options exist: (1) A destructor to dispose of the BLOB +or string after SQLite has finished with it may be passed. +It is called to dispose of the BLOB or string even if the call to the +bind API fails, except the destructor is not called if the third parameter +is a NULL pointer or the fourth parameter is negative. +(2) The special constant, SQLITE_STATIC, may be passed +to indicate that the application remains responsible for disposing +of the object. +In this case, the object and the provided pointer to it must remain +valid until either the prepared statement is finalized or the same +SQL parameter is bound to something else, whichever occurs sooner. +(3) The constant, SQLITE_TRANSIENT, may be passed to +indicate that the object is to be copied prior to the return from sqlite3_bind_*(). +The object and pointer to it must remain valid until then. +SQLite will then manage the lifetime of its private copy. +.Pp +The sixth argument to sqlite3_bind_text64() must be one of SQLITE_UTF8, +SQLITE_UTF16, SQLITE_UTF16BE, or SQLITE_UTF16LE +to specify the encoding of the text in the third parameter. +If the sixth argument to sqlite3_bind_text64() is not one of the allowed +values shown above, or if the text encoding is different from the encoding +specified by the sixth parameter, then the behavior is undefined. +.Pp +The sqlite3_bind_zeroblob() routine binds a BLOB of length N that is +filled with zeroes. +A zeroblob uses a fixed amount of memory (just an integer to hold its +size) while it is being processed. +Zeroblobs are intended to serve as placeholders for BLOBs whose content +is later written using incremental BLOB I/O routines. +A negative value for the zeroblob results in a zero-length BLOB. +.Pp +The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter +in prepared statement S to have an SQL value of NULL, +but to also be associated with the pointer P of type T. +D is either a NULL pointer or a pointer to a destructor function for +P. +SQLite will invoke the destructor D with a single argument of P when +it is finished using P. +The T parameter should be a static string, preferably a string literal. +The sqlite3_bind_pointer() routine is part of the pointer passing interface +added for SQLite 3.20.0. +.Pp +If any of the sqlite3_bind_*() routines are called with a NULL pointer +for the prepared statement or with a prepared statement +for which +.Fn sqlite3_step +has been called more recently than +.Fn sqlite3_reset , +then the call will return SQLITE_MISUSE. +If any sqlite3_bind_() routine is passed a prepared statement +that has been finalized, the result is undefined and probably harmful. +.Pp +Bindings are not cleared by the +.Fn sqlite3_reset +routine. +Unbound parameters are interpreted as NULL. +.Pp +The sqlite3_bind_* routines return SQLITE_OK on success or +an error code if anything goes wrong. +SQLITE_TOOBIG might be returned if the size of a string +or BLOB exceeds limits imposed by sqlite3_limit(SQLITE_LIMIT_LENGTH) +or SQLITE_MAX_LENGTH. +SQLITE_RANGE is returned if the parameter index is out +of range. +SQLITE_NOMEM is returned if malloc() fails. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 4543. +.Bd -literal +SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*)); +SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64, + void(*)(void*)); +SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double); +SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int); +SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64); +SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int); +SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*)); +SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*)); +SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64, + void(*)(void*), unsigned char encoding); +SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*); +SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*)); +SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n); +SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64); +.Ed +.Sh SEE ALSO +.Xr sqlite3_bind_parameter_count 3 , +.Xr sqlite3_bind_parameter_index 3 , +.Xr sqlite3_bind_parameter_name 3 , +.Xr sqlite3_blob_open 3 , +.Xr sqlite3_destructor_type 3 , +.Xr sqlite3_limit 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_reset 3 , +.Xr sqlite3_step 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_LIMIT_LENGTH 3 , +.Xr SQLITE_OK 3 , +.Xr SQLITE_UTF8 3 |