Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


SQLITE3_BIND_BLOB(3)       Library Functions Manual       SQLITE3_BIND_BLOB(3)

NAME
     sqlite3_bind_blob, sqlite3_bind_blob64, sqlite3_bind_double,
     sqlite3_bind_int, sqlite3_bind_int64, sqlite3_bind_null,
     sqlite3_bind_text, sqlite3_bind_text16, sqlite3_bind_text64,
     sqlite3_bind_value, sqlite3_bind_pointer, sqlite3_bind_zeroblob,
     sqlite3_bind_zeroblob64 - Binding Values To Prepared Statements

SYNOPSIS
     int
     sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n,
         void(*)(void*));

     int
     sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
         void(*)(void*));

     int
     sqlite3_bind_double(sqlite3_stmt*, int, double);

     int
     sqlite3_bind_int(sqlite3_stmt*, int, int);

     int
     sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);

     int
     sqlite3_bind_null(sqlite3_stmt*, int);

     int
     sqlite3_bind_text(sqlite3_stmt*, int, const char*, int, void(*)(void*));

     int
     sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int,
         void(*)(void*));

     int
     sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
         void(*)(void*), unsigned char encoding);

     int
     sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);

     int
     sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,
         void(*)(void*));

     int
     sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);

     int
     sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);

DESCRIPTION
     In the SQL statement text input to sqlite3_prepare_v2() and its variants,
     literals may be replaced by a parameter that matches one of following
     templates:

        ?

        ?NNN

        :VVV

        @VVV

        $VVV

     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.

     The first argument to the sqlite3_bind_*() routines is always a pointer
     to the sqlite3_stmt object returned from sqlite3_prepare_v2() or its
     variants.

     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 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 sqlite3_limit() parameter
     SQLITE_LIMIT_VARIABLE_NUMBER (default value: 999).

     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().

     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
     <u>bytes</u> 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 occur 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.

     The fifth argument to the BLOB and string binding interfaces is a
     destructor used to dispose of the BLOB or string after SQLite has
     finished with it.  The destructor is called to dispose of the BLOB or
     string even if the call to bind API fails.  If the fifth argument is the
     special value SQLITE_STATIC, then SQLite assumes that the information is
     in static, unmanaged space and does not need to be freed.  If the fifth
     argument has the value SQLITE_TRANSIENT, then SQLite makes its own
     private copy of the data immediately, before the sqlite3_bind_*() routine
     returns.

     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.

     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.

     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.

     If any of the sqlite3_bind_*() routines are called with a NULL pointer
     for the prepared statement or with a prepared statement for which
     sqlite3_step() has been called more recently than 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.

     Bindings are not cleared by the sqlite3_reset() routine.  Unbound
     parameters are interpreted as NULL.

     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.

SEE ALSO
     sqlite3_stmt(3), sqlite3_bind_parameter_count(3),
     sqlite3_bind_parameter_index(3), sqlite3_bind_parameter_name(3),
     sqlite3_blob_open(3), sqlite3_limit(3), sqlite3_prepare(3),
     sqlite3_reset(3), sqlite3_step(3), sqlite3_stmt(3),
     SQLITE_LIMIT_LENGTH(3), SQLITE_OK(3), sqlite3_destructor_type(3),
     SQLITE_OK(3), sqlite3_destructor_type(3), SQLITE_UTF8(3)

NetBSD 9.99                    December 19, 2018                   NetBSD 9.99