.Dd April 29, 2026
.Dt SQLITE3_VALUE_BLOB 3
.Os
.Sh NAME
.Nm sqlite3_value_blob ,
.Nm sqlite3_value_double ,
.Nm sqlite3_value_int ,
.Nm sqlite3_value_int64 ,
.Nm sqlite3_value_pointer ,
.Nm sqlite3_value_text ,
.Nm sqlite3_value_text16 ,
.Nm sqlite3_value_text16le ,
.Nm sqlite3_value_text16be ,
.Nm sqlite3_value_bytes ,
.Nm sqlite3_value_bytes16 ,
.Nm sqlite3_value_type ,
.Nm sqlite3_value_numeric_type ,
.Nm sqlite3_value_nochange ,
.Nm sqlite3_value_frombind
.Nd obtaining SQL values
.Sh SYNOPSIS
.In sqlite3.h
.Ft const void *
.Fo sqlite3_value_blob
.Fa "sqlite3_value*"
.Fc
.Ft double
.Fo sqlite3_value_double
.Fa "sqlite3_value*"
.Fc
.Ft int
.Fo sqlite3_value_int
.Fa "sqlite3_value*"
.Fc
.Ft sqlite3_int64
.Fo sqlite3_value_int64
.Fa "sqlite3_value*"
.Fc
.Ft void *
.Fo sqlite3_value_pointer
.Fa "sqlite3_value*"
.Fa "const char*"
.Fc
.Ft const unsigned char *
.Fo sqlite3_value_text
.Fa "sqlite3_value*"
.Fc
.Ft const void *
.Fo sqlite3_value_text16
.Fa "sqlite3_value*"
.Fc
.Ft const void *
.Fo sqlite3_value_text16le
.Fa "sqlite3_value*"
.Fc
.Ft const void *
.Fo sqlite3_value_text16be
.Fa "sqlite3_value*"
.Fc
.Ft int
.Fo sqlite3_value_bytes
.Fa "sqlite3_value*"
.Fc
.Ft int
.Fo sqlite3_value_bytes16
.Fa "sqlite3_value*"
.Fc
.Ft int
.Fo sqlite3_value_type
.Fa "sqlite3_value*"
.Fc
.Ft int
.Fo sqlite3_value_numeric_type
.Fa "sqlite3_value*"
.Fc
.Ft int
.Fo sqlite3_value_nochange
.Fa "sqlite3_value*"
.Fc
.Ft int
.Fo sqlite3_value_frombind
.Fa "sqlite3_value*"
.Fc
.Sh DESCRIPTION
\fBSummary:\fP
.Bd -ragged
.Pp
  \fBsqlite3_value_blob\fP \(-> BLOB value
  \fBsqlite3_value_double\fP \(-> REAL value
  \fBsqlite3_value_int\fP \(-> 32-bit INTEGER value
  \fBsqlite3_value_int64\fP \(-> 64-bit INTEGER value
  \fBsqlite3_value_pointer\fP \(-> Pointer value
  \fBsqlite3_value_text\fP \(-> UTF-8 TEXT value
  \fBsqlite3_value_text16\fP \(-> UTF-16 TEXT value in the native byteorder
  \fBsqlite3_value_text16be\fP \(-> UTF-16be TEXT value
  \fBsqlite3_value_text16le\fP \(-> UTF-16le TEXT value
       
  \fBsqlite3_value_bytes\fP \(-> Size of a BLOB or a UTF-8 TEXT in bytes
  \fBsqlite3_value_bytes16  \fP  \(->   Size of UTF-16 TEXT in bytes
  \fBsqlite3_value_type\fP \(-> Default datatype of the value
  \fBsqlite3_value_numeric_type  \fP  \(->   Best numeric datatype of the value
  \fBsqlite3_value_nochange  \fP  \(->   True if the column is unchanged in an
UPDATE against a virtual table.
  \fBsqlite3_value_frombind  \fP  \(->   True if value originated from a bound parameter
.Pp
.Ed
.Pp
\fBDetails:\fP
.Pp
These routines extract type, size, and content information from protected sqlite3_value
objects.
Protected sqlite3_value objects are used to pass parameter information
into the functions that implement application-defined SQL functions
and virtual tables.
.Pp
These routines work only with protected sqlite3_value
objects.
Any attempt to use these routines on an unprotected sqlite3_value
is not threadsafe.
.Pp
These routines work just like the corresponding column access functions
except that these routines take a single protected sqlite3_value
object pointer instead of a sqlite3_stmt* pointer and
an integer column number.
.Pp
The sqlite3_value_text16() interface extracts a UTF-16 string in the
native byte-order of the host machine.
The sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
extract UTF-16 strings as big-endian and little-endian respectively.
.Pp
If sqlite3_value object V was initialized using sqlite3_bind_pointer(S,I,P,X,D)
or sqlite3_result_pointer(C,P,X,D) and
if X and Y are strings that compare equal according to strcmp(X,Y),
then sqlite3_value_pointer(V,Y) will return the pointer P.
Otherwise, sqlite3_value_pointer(V,Y) returns a NULL.
The sqlite3_bind_pointer() routine is part of the pointer passing interface
added for SQLite 3.20.0.
.Pp
The sqlite3_value_type(V) interface returns the datatype code
for the initial datatype of the sqlite3_value object V.
The returned value is one of SQLITE_INTEGER, SQLITE_FLOAT,
SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL.
Other interfaces might change the datatype for an sqlite3_value object.
For example, if the datatype is initially SQLITE_INTEGER and sqlite3_value_text(V)
is called to extract a text value for that integer, then subsequent
calls to sqlite3_value_type(V) might return SQLITE_TEXT.
Whether or not a persistent internal datatype conversion occurs is
undefined and may change from one release of SQLite to the next.
.Pp
The sqlite3_value_numeric_type() interface attempts to apply numeric
affinity to the value.
This means that an attempt is made to convert the value to an integer
or floating point.
If such a conversion is possible without loss of information (in other
words, if the value is a string that looks like a number) then the
conversion is performed.
Otherwise no conversion occurs.
The datatype after conversion is returned.
.Pp
Within the xUpdate method of a virtual table, the
sqlite3_value_nochange(X) interface returns true if and only if the
column corresponding to X is unchanged by the UPDATE operation that
the xUpdate method call was invoked to implement and if the prior xColumn
method call that was invoked to extract the value for that column returned
without setting a result (probably because it queried
.Fn sqlite3_vtab_nochange
and found that the column was unchanging).
Within an xUpdate method, any value for which sqlite3_value_nochange(X)
is true will in all other respects appear to be a NULL value.
If sqlite3_value_nochange(X) is invoked anywhere other than within
an xUpdate method call for an UPDATE statement, then the return
value is arbitrary and meaningless.
.Pp
The sqlite3_value_frombind(X) interface returns non-zero if the value
X originated from one of the sqlite3_bind() interfaces.
If X comes from an SQL literal value, or a table column, or an expression,
then sqlite3_value_frombind(X) returns zero.
.Pp
Please pay particular attention to the fact that the pointer returned
from
.Fn sqlite3_value_blob ,
.Fn sqlite3_value_text ,
or
.Fn sqlite3_value_text16
can be invalidated by a subsequent call to
.Fn sqlite3_value_bytes ,
.Fn sqlite3_value_bytes16 ,
.Fn sqlite3_value_text ,
or
.Fn sqlite3_value_text16 .
These routines must be called from the same thread as the SQL function
that supplied the sqlite3_value* parameters.
.Pp
As long as the input parameter is correct, these routines can only
fail if an out-of-memory error occurs while trying to do a UTF8\(->UTF16
or UTF16\(->UTF8 conversion.
If an out-of-memory error occurs, then the return value from these
routines is the same as if the column had contained an SQL NULL value.
If the input sqlite3_value was not obtained from
.Fn sqlite3_value_dup ,
then valid SQL NULL returns can also be distinguished from out-of-memory
errors after extracting the value by invoking the
.Fn sqlite3_errcode
immediately after the suspicious return value is obtained and before
any other SQLite interface is called on the same database connection.
If the input sqlite3_value was obtained from sqlite3_value_dup() then
it is disconnected from the database connection and so sqlite3_errcode()
will not work.
In that case, the only way to distinguish an out-of-memory condition
from a true SQL NULL is to invoke sqlite3_value_type() on the input
to see if it is NULL prior to trying to extract the value.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 6011.
.Bd -literal
SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
SQLITE_API double sqlite3_value_double(sqlite3_value*);
SQLITE_API int sqlite3_value_int(sqlite3_value*);
SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
SQLITE_API void *sqlite3_value_pointer(sqlite3_value*, const char*);
SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
SQLITE_API int sqlite3_value_type(sqlite3_value*);
SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
SQLITE_API int sqlite3_value_nochange(sqlite3_value*);
SQLITE_API int sqlite3_value_frombind(sqlite3_value*);
.Ed
.Sh SEE ALSO
.Xr sqlite3 3 ,
.Xr sqlite3_bind_blob 3 ,
.Xr sqlite3_column_blob 3 ,
.Xr sqlite3_errcode 3 ,
.Xr sqlite3_value 3 ,
.Xr sqlite3_value_dup 3 ,
.Xr sqlite3_vtab_nochange 3 ,
.Xr SQLITE_INTEGER 3