249 lines
9.1 KiB
Groff
249 lines
9.1 KiB
Groff
.Dd December 18, 2016
|
|
.Dt SQLITE3_COLUMN_BLOB 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sqlite3_column_blob ,
|
|
.Nm sqlite3_column_bytes ,
|
|
.Nm sqlite3_column_bytes16 ,
|
|
.Nm sqlite3_column_double ,
|
|
.Nm sqlite3_column_int ,
|
|
.Nm sqlite3_column_int64 ,
|
|
.Nm sqlite3_column_text ,
|
|
.Nm sqlite3_column_text16 ,
|
|
.Nm sqlite3_column_type ,
|
|
.Nm sqlite3_column_value
|
|
.Nd Result Values From A Query
|
|
.Sh SYNOPSIS
|
|
.Ft const void *SQLITE_STDCALL
|
|
.Fo sqlite3_column_blob
|
|
.Fa "sqlite3_stmt*"
|
|
.Fa "int iCol"
|
|
.Fc
|
|
.Ft int SQLITE_STDCALL
|
|
.Fo sqlite3_column_bytes
|
|
.Fa "sqlite3_stmt*"
|
|
.Fa "int iCol"
|
|
.Fc
|
|
.Ft int SQLITE_STDCALL
|
|
.Fo sqlite3_column_bytes16
|
|
.Fa "sqlite3_stmt*"
|
|
.Fa "int iCol"
|
|
.Fc
|
|
.Ft double SQLITE_STDCALL
|
|
.Fo sqlite3_column_double
|
|
.Fa "sqlite3_stmt*"
|
|
.Fa "int iCol"
|
|
.Fc
|
|
.Ft int SQLITE_STDCALL
|
|
.Fo sqlite3_column_int
|
|
.Fa "sqlite3_stmt*"
|
|
.Fa "int iCol"
|
|
.Fc
|
|
.Ft sqlite3_int64 SQLITE_STDCALL
|
|
.Fo sqlite3_column_int64
|
|
.Fa "sqlite3_stmt*"
|
|
.Fa "int iCol"
|
|
.Fc
|
|
.Ft const unsigned char *SQLITE_STDCALL
|
|
.Fo sqlite3_column_text
|
|
.Fa "sqlite3_stmt*"
|
|
.Fa "int iCol"
|
|
.Fc
|
|
.Ft const void *SQLITE_STDCALL
|
|
.Fo sqlite3_column_text16
|
|
.Fa "sqlite3_stmt*"
|
|
.Fa "int iCol"
|
|
.Fc
|
|
.Ft int SQLITE_STDCALL
|
|
.Fo sqlite3_column_type
|
|
.Fa "sqlite3_stmt*"
|
|
.Fa "int iCol"
|
|
.Fc
|
|
.Ft sqlite3_value *SQLITE_STDCALL
|
|
.Fo sqlite3_column_value
|
|
.Fa "sqlite3_stmt*"
|
|
.Fa "int iCol"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
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 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 value returned by sqlite3_column_type() is only meaningful if no
|
|
type conversions have occurred as described below.
|
|
After a type conversion, the value returned by sqlite3_column_type()
|
|
is undefined.
|
|
Future versions of SQLite may change the behavior of sqlite3_column_type()
|
|
following a type conversion.
|
|
.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.
|
|
.Pp
|
|
These routines attempt to convert the value where appropriate.
|
|
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 <em>not</em> pass the pointers returned from sqlite3_column_blob(),
|
|
sqlite3_column_text(), etc.
|
|
into sqlite3_free().
|
|
.Pp
|
|
If a memory allocation error occurs during the evaluation of any of
|
|
these routines, a default value is returned.
|
|
The default value is either the integer 0, the floating point number
|
|
0.0, or a NULL pointer.
|
|
Subsequent calls to sqlite3_errcode() will return
|
|
SQLITE_NOMEM.
|
|
.Sh SEE ALSO
|
|
.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_blob 3 ,
|
|
.Xr SQLITE_INTEGER 3 ,
|
|
.Xr SQLITE_OK 3 ,
|
|
.Xr SQLITE_INTEGER 3 ,
|
|
.Xr SQLITE_OK 3 ,
|
|
.Xr SQLITE_INTEGER 3 ,
|
|
.Xr sqlite3_value 3
|