.Dd December 19, 2018
.Dt SQLITE3_COLUMN_BLOB 3
.Os
.Sh NAME
.Nm sqlite3_column_blob ,
.Nm sqlite3_column_double ,
.Nm sqlite3_column_int ,
.Nm sqlite3_column_int64 ,
.Nm sqlite3_column_text ,
.Nm sqlite3_column_text16 ,
.Nm sqlite3_column_value ,
.Nm sqlite3_column_bytes ,
.Nm sqlite3_column_bytes16 ,
.Nm sqlite3_column_type
.Nd Result Values From A Query
.Sh SYNOPSIS
.Ft const void *
.Fo sqlite3_column_blob
.Fa "sqlite3_stmt*"
.Fa "int iCol"
.Fc
.Ft double 
.Fo sqlite3_column_double
.Fa "sqlite3_stmt*"
.Fa "int iCol"
.Fc
.Ft int 
.Fo sqlite3_column_int
.Fa "sqlite3_stmt*"
.Fa "int iCol"
.Fc
.Ft sqlite3_int64 
.Fo sqlite3_column_int64
.Fa "sqlite3_stmt*"
.Fa "int iCol"
.Fc
.Ft const unsigned char *
.Fo sqlite3_column_text
.Fa "sqlite3_stmt*"
.Fa "int iCol"
.Fc
.Ft const void *
.Fo sqlite3_column_text16
.Fa "sqlite3_stmt*"
.Fa "int iCol"
.Fc
.Ft sqlite3_value *
.Fo sqlite3_column_value
.Fa "sqlite3_stmt*"
.Fa "int iCol"
.Fc
.Ft int 
.Fo sqlite3_column_bytes
.Fa "sqlite3_stmt*"
.Fa "int iCol"
.Fc
.Ft int 
.Fo sqlite3_column_bytes16
.Fa "sqlite3_stmt*"
.Fa "int iCol"
.Fc
.Ft int 
.Fo sqlite3_column_type
.Fa "sqlite3_stmt*"
.Fa "int iCol"
.Fc
.Sh DESCRIPTION
\fBSummary:\fP 
.Bd -ragged
<table border=0 cellpadding=0 cellspacing=0> <tr><td>\fBsqlite3_column_blob\fP<td>&rarr;<td>BLOB
result <tr><td>\fBsqlite3_column_double\fP<td>&rarr;<td>REAL result <tr><td>\fBsqlite3_column_int\fP<td>&rarr;<td>32-bit
INTEGER result <tr><td>\fBsqlite3_column_int64\fP<td>&rarr;<td>64-bit INTEGER
result <tr><td>\fBsqlite3_column_text\fP<td>&rarr;<td>UTF-8 TEXT result <tr><td>\fBsqlite3_column_text16\fP<td>&rarr;<td>UTF-16
TEXT result <tr><td>\fBsqlite3_column_value\fP<td>&rarr;<td>The result as
an unprotected sqlite3_value object.
<tr><td> <td> <td>  <tr><td>\fBsqlite3_column_bytes\fP<td>&rarr;<td>Size
of a BLOB or a UTF-8 TEXT result in bytes <tr><td>\fBsqlite3_column_bytes16  \fP
<td>&rarr;  <td>Size of UTF-16 TEXT in bytes <tr><td>\fBsqlite3_column_type\fP<td>&rarr;<td>Default
datatype of the result </table>
.Ed
.Pp
\fBDetails:\fP 
.Pp
These routines return information about a single column of the current
result row of a query.
In every case the first argument is a pointer to the prepared statement
that is being evaluated (the sqlite3_stmt* that was returned
from sqlite3_prepare_v2() or one of its variants)
and the second argument is the index of the column for which information
should be returned.
The leftmost column of the result set has the index 0.
The number of columns in the result can be determined using sqlite3_column_count().
.Pp
If the SQL statement does not currently point to a valid row, or if
the column index is out of range, the result is undefined.
These routines may only be called when the most recent call to sqlite3_step()
has returned SQLITE_ROW and neither sqlite3_reset()
nor sqlite3_finalize() have been called subsequently.
If any of these routines are called after sqlite3_reset()
or sqlite3_finalize() or after sqlite3_step()
has returned something other than SQLITE_ROW, the results
are undefined.
If sqlite3_step() or sqlite3_reset() or
sqlite3_finalize() are called from a different thread
while any of these routines are pending, then the results are undefined.
.Pp
The first six interfaces (_blob, _double, _int, _int64, _text, and
_text16) each return the value of a result column in a specific data
format.
If the result column is not initially in the requested format (for
example, if the query returns an integer but the sqlite3_column_text()
interface is used to extract the value) then an automatic type conversion
is performed.
.Pp
The sqlite3_column_type() routine returns the  datatype code
for the initial data type of the result column.
The returned value is one of SQLITE_INTEGER, SQLITE_FLOAT,
SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL.
The return value of sqlite3_column_type() can be used to decide which
of the first six interface should be used to extract the column value.
The value returned by sqlite3_column_type() is only meaningful if no
automatic type conversions have occurred for the value in question.
After a type conversion, the result of calling sqlite3_column_type()
is undefined, though harmless.
Future versions of SQLite may change the behavior of sqlite3_column_type()
following a type conversion.
.Pp
If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
or sqlite3_column_bytes16() interfaces can be used to determine the
size of that BLOB or string.
.Pp
If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
routine returns the number of bytes in that BLOB or string.
If the result is a UTF-16 string, then sqlite3_column_bytes() converts
the string to UTF-8 and then returns the number of bytes.
If the result is a numeric value then sqlite3_column_bytes() uses sqlite3_snprintf()
to convert that value to a UTF-8 string and returns the number of bytes
in that string.
If the result is NULL, then sqlite3_column_bytes() returns zero.
.Pp
If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
routine returns the number of bytes in that BLOB or string.
If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
the string to UTF-16 and then returns the number of bytes.
If the result is a numeric value then sqlite3_column_bytes16() uses
sqlite3_snprintf() to convert that value to a UTF-16
string and returns the number of bytes in that string.
If the result is NULL, then sqlite3_column_bytes16() returns zero.
.Pp
The values returned by sqlite3_column_bytes()
and sqlite3_column_bytes16() do not include
the zero terminators at the end of the string.
For clarity: the values returned by sqlite3_column_bytes()
and sqlite3_column_bytes16() are the number
of bytes in the string, not the number of characters.
.Pp
Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
even empty strings, are always zero-terminated.
The return value from sqlite3_column_blob() for a zero-length BLOB
is a NULL pointer.
.Pp
\fBWarning:\fP  The object returned by sqlite3_column_value()
is an unprotected sqlite3_value object.
In a multithreaded environment, an unprotected sqlite3_value object
may only be used safely with sqlite3_bind_value()
and sqlite3_result_value().
If the unprotected sqlite3_value object returned
by sqlite3_column_value() is used in any other
way, including calls to routines like sqlite3_value_int(),
sqlite3_value_text(), or sqlite3_value_bytes(),
the behavior is not threadsafe.
Hence, the sqlite3_column_value() interface is normally only useful
within the implementation of application-defined SQL functions
or virtual tables, not within top-level application code.
.Pp
The these routines may attempt to convert the datatype of the result.
For example, if the internal representation is FLOAT and a text result
is requested, sqlite3_snprintf() is used internally
to perform the conversion automatically.
The following table details the conversions that are applied: 
.Bd -ragged
<table border="1"> <tr><th> Internal<br>Type <th> Requested<br>Type
<th>  Conversion 
.Pp
<tr><td>  NULL    <td> INTEGER   <td> Result is 0 <tr><td>  NULL  
<td>  FLOAT    <td> Result is 0.0 <tr><td>  NULL    <td>   TEXT   
<td> Result is a NULL pointer <tr><td>  NULL    <td>   BLOB    <td>
Result is a NULL pointer <tr><td> INTEGER  <td>  FLOAT    <td> Convert
from integer to float <tr><td> INTEGER  <td>   TEXT    <td> ASCII rendering
of the integer <tr><td> INTEGER  <td>   BLOB    <td> Same as INTEGER->TEXT
<tr><td>  FLOAT   <td> INTEGER   <td> CAST to INTEGER <tr><td>
FLOAT   <td>   TEXT    <td> ASCII rendering of the float <tr><td> 
FLOAT   <td>   BLOB    <td> CAST to BLOB <tr><td>  TEXT    <td>
INTEGER   <td> CAST to INTEGER <tr><td>  TEXT    <td>  FLOAT  
<td> CAST to REAL <tr><td>  TEXT    <td>   BLOB    <td> No change
<tr><td>  BLOB    <td> INTEGER   <td> CAST to INTEGER <tr><td>
BLOB    <td>  FLOAT    <td> CAST to REAL <tr><td>  BLOB    <td>
TEXT    <td> Add a zero terminator if needed </table> 
.Ed
.Pp
Note that when type conversions occur, pointers returned by prior calls
to sqlite3_column_blob(), sqlite3_column_text(), and/or sqlite3_column_text16()
may be invalidated.
Type conversions and pointer invalidations might occur in the following
cases: 
.Bl -bullet
.It
The initial content is a BLOB and sqlite3_column_text() or sqlite3_column_text16()
is called.
A zero-terminator might need to be added to the string.
.It
The initial content is UTF-8 text and sqlite3_column_bytes16() or sqlite3_column_text16()
is called.
The content must be converted to UTF-16.
.It
The initial content is UTF-16 text and sqlite3_column_bytes() or sqlite3_column_text()
is called.
The content must be converted to UTF-8.
.El
.Pp
Conversions between UTF-16be and UTF-16le are always done in place
and do not invalidate a prior pointer, though of course the content
of the buffer that the prior pointer references will have been modified.
Other kinds of conversion are done in place when it is possible, but
sometimes they are not possible and in those cases prior pointers are
invalidated.
.Pp
The safest policy is to invoke these routines in one of the following
ways: 
.Bl -bullet
.It
sqlite3_column_text() followed by sqlite3_column_bytes()
.It
sqlite3_column_blob() followed by sqlite3_column_bytes()
.It
sqlite3_column_text16() followed by sqlite3_column_bytes16()
.El
.Pp
In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),
or sqlite3_column_text16() first to force the result into the desired
format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16()
to find the size of the result.
Do not mix calls to sqlite3_column_text() or sqlite3_column_blob()
with calls to sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
with calls to sqlite3_column_bytes().
.Pp
The pointers returned are valid until a type conversion occurs as described
above, or until sqlite3_step() or sqlite3_reset()
or sqlite3_finalize() is called.
The memory space used to hold strings and BLOBs is freed automatically.
Do not pass the pointers returned from sqlite3_column_blob(),
sqlite3_column_text(), etc.
into sqlite3_free().
.Pp
As long as the input parameters are correct, these routines will only
fail if an out-of-memory error occurs during a format conversion.
Only the following subset of interfaces are subject to out-of-memory
errors: 
.Bl -bullet
.It
sqlite3_column_blob() 
.It
sqlite3_column_text() 
.It
sqlite3_column_text16() 
.It
sqlite3_column_bytes() 
.It
sqlite3_column_bytes16() 
.El
.Pp
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.
Valid SQL NULL returns can be distinguished from out-of-memory errors
by invoking the sqlite3_errcode() immediately after
the suspect return value is obtained and before any other SQLite interface
is called on the same database connection.
.Sh SEE ALSO
.Xr sqlite3_create_function 3 ,
.Xr sqlite3 3 ,
.Xr sqlite3_stmt 3 ,
.Xr sqlite3_bind_blob 3 ,
.Xr sqlite3_column_blob 3 ,
.Xr sqlite3_column_count 3 ,
.Xr sqlite3_column_blob 3 ,
.Xr sqlite3_errcode 3 ,
.Xr sqlite3_finalize 3 ,
.Xr sqlite3_malloc 3 ,
.Xr sqlite3_prepare 3 ,
.Xr sqlite3_reset 3 ,
.Xr sqlite3_result_blob 3 ,
.Xr sqlite3_mprintf 3 ,
.Xr sqlite3_step 3 ,
.Xr sqlite3_value 3 ,
.Xr sqlite3_value_blob 3 ,
.Xr SQLITE_INTEGER 3 ,
.Xr SQLITE_OK 3 ,
.Xr SQLITE_INTEGER 3 ,
.Xr sqlite3_value 3