300 lines
11 KiB
Groff
300 lines
11 KiB
Groff
.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>→<td>BLOB
|
|
result <tr><td>\fBsqlite3_column_double\fP<td>→<td>REAL result <tr><td>\fBsqlite3_column_int\fP<td>→<td>32-bit
|
|
INTEGER result <tr><td>\fBsqlite3_column_int64\fP<td>→<td>64-bit INTEGER
|
|
result <tr><td>\fBsqlite3_column_text\fP<td>→<td>UTF-8 TEXT result <tr><td>\fBsqlite3_column_text16\fP<td>→<td>UTF-16
|
|
TEXT result <tr><td>\fBsqlite3_column_value\fP<td>→<td>The result as
|
|
an unprotected sqlite3_value object.
|
|
<tr><td> <td> <td> <tr><td>\fBsqlite3_column_bytes\fP<td>→<td>Size
|
|
of a BLOB or a UTF-8 TEXT result in bytes <tr><td>\fBsqlite3_column_bytes16 \fP
|
|
<td>→ <td>Size of UTF-16 TEXT in bytes <tr><td>\fBsqlite3_column_type\fP<td>→<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
|