1.Dd March 11, 2017 2.Dt SQLITE3_COLUMN_BLOB 3 3.Os 4.Sh NAME 5.Nm sqlite3_column_blob , 6.Nm sqlite3_column_bytes , 7.Nm sqlite3_column_bytes16 , 8.Nm sqlite3_column_double , 9.Nm sqlite3_column_int , 10.Nm sqlite3_column_int64 , 11.Nm sqlite3_column_text , 12.Nm sqlite3_column_text16 , 13.Nm sqlite3_column_type , 14.Nm sqlite3_column_value 15.Nd Result Values From A Query 16.Sh SYNOPSIS 17.Ft const void * 18.Fo sqlite3_column_blob 19.Fa "sqlite3_stmt*" 20.Fa "int iCol" 21.Fc 22.Ft int 23.Fo sqlite3_column_bytes 24.Fa "sqlite3_stmt*" 25.Fa "int iCol" 26.Fc 27.Ft int 28.Fo sqlite3_column_bytes16 29.Fa "sqlite3_stmt*" 30.Fa "int iCol" 31.Fc 32.Ft double 33.Fo sqlite3_column_double 34.Fa "sqlite3_stmt*" 35.Fa "int iCol" 36.Fc 37.Ft int 38.Fo sqlite3_column_int 39.Fa "sqlite3_stmt*" 40.Fa "int iCol" 41.Fc 42.Ft sqlite3_int64 43.Fo sqlite3_column_int64 44.Fa "sqlite3_stmt*" 45.Fa "int iCol" 46.Fc 47.Ft const unsigned char * 48.Fo sqlite3_column_text 49.Fa "sqlite3_stmt*" 50.Fa "int iCol" 51.Fc 52.Ft const void * 53.Fo sqlite3_column_text16 54.Fa "sqlite3_stmt*" 55.Fa "int iCol" 56.Fc 57.Ft int 58.Fo sqlite3_column_type 59.Fa "sqlite3_stmt*" 60.Fa "int iCol" 61.Fc 62.Ft sqlite3_value * 63.Fo sqlite3_column_value 64.Fa "sqlite3_stmt*" 65.Fa "int iCol" 66.Fc 67.Sh DESCRIPTION 68These routines return information about a single column of the current 69result row of a query. 70In every case the first argument is a pointer to the prepared statement 71that is being evaluated (the sqlite3_stmt* that was returned 72from sqlite3_prepare_v2() or one of its variants) 73and the second argument is the index of the column for which information 74should be returned. 75The leftmost column of the result set has the index 0. 76The number of columns in the result can be determined using sqlite3_column_count(). 77.Pp 78If the SQL statement does not currently point to a valid row, or if 79the column index is out of range, the result is undefined. 80These routines may only be called when the most recent call to sqlite3_step() 81has returned SQLITE_ROW and neither sqlite3_reset() 82nor sqlite3_finalize() have been called subsequently. 83If any of these routines are called after sqlite3_reset() 84or sqlite3_finalize() or after sqlite3_step() 85has returned something other than SQLITE_ROW, the results 86are undefined. 87If sqlite3_step() or sqlite3_reset() or 88sqlite3_finalize() are called from a different thread 89while any of these routines are pending, then the results are undefined. 90.Pp 91The sqlite3_column_type() routine returns the datatype code 92for the initial data type of the result column. 93The returned value is one of SQLITE_INTEGER, SQLITE_FLOAT, 94SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL. 95The value returned by sqlite3_column_type() is only meaningful if no 96type conversions have occurred as described below. 97After a type conversion, the value returned by sqlite3_column_type() 98is undefined. 99Future versions of SQLite may change the behavior of sqlite3_column_type() 100following a type conversion. 101.Pp 102If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() 103routine returns the number of bytes in that BLOB or string. 104If the result is a UTF-16 string, then sqlite3_column_bytes() converts 105the string to UTF-8 and then returns the number of bytes. 106If the result is a numeric value then sqlite3_column_bytes() uses sqlite3_snprintf() 107to convert that value to a UTF-8 string and returns the number of bytes 108in that string. 109If the result is NULL, then sqlite3_column_bytes() returns zero. 110.Pp 111If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16() 112routine returns the number of bytes in that BLOB or string. 113If the result is a UTF-8 string, then sqlite3_column_bytes16() converts 114the string to UTF-16 and then returns the number of bytes. 115If the result is a numeric value then sqlite3_column_bytes16() uses 116sqlite3_snprintf() to convert that value to a UTF-16 117string and returns the number of bytes in that string. 118If the result is NULL, then sqlite3_column_bytes16() returns zero. 119.Pp 120The values returned by sqlite3_column_bytes() 121and sqlite3_column_bytes16() do not include 122the zero terminators at the end of the string. 123For clarity: the values returned by sqlite3_column_bytes() 124and sqlite3_column_bytes16() are the number 125of bytes in the string, not the number of characters. 126.Pp 127Strings returned by sqlite3_column_text() and sqlite3_column_text16(), 128even empty strings, are always zero-terminated. 129The return value from sqlite3_column_blob() for a zero-length BLOB 130is a NULL pointer. 131.Pp 132\fBWarning:\fP The object returned by sqlite3_column_value() 133is an unprotected sqlite3_value object. 134In a multithreaded environment, an unprotected sqlite3_value object 135may only be used safely with sqlite3_bind_value() 136and sqlite3_result_value(). 137If the unprotected sqlite3_value object returned 138by sqlite3_column_value() is used in any other 139way, including calls to routines like sqlite3_value_int(), 140sqlite3_value_text(), or sqlite3_value_bytes(), 141the behavior is not threadsafe. 142.Pp 143These routines attempt to convert the value where appropriate. 144For example, if the internal representation is FLOAT and a text result 145is requested, sqlite3_snprintf() is used internally 146to perform the conversion automatically. 147The following table details the conversions that are applied: 148.Bd -ragged 149<table border="1"> <tr><th> Internal<br>Type <th> Requested<br>Type 150<th> Conversion 151.Pp 152<tr><td> NULL <td> INTEGER <td> Result is 0 <tr><td> NULL 153<td> FLOAT <td> Result is 0.0 <tr><td> NULL <td> TEXT 154<td> Result is a NULL pointer <tr><td> NULL <td> BLOB <td> 155Result is a NULL pointer <tr><td> INTEGER <td> FLOAT <td> Convert 156from integer to float <tr><td> INTEGER <td> TEXT <td> ASCII rendering 157of the integer <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT 158<tr><td> FLOAT <td> INTEGER <td> CAST to INTEGER <tr><td> 159FLOAT <td> TEXT <td> ASCII rendering of the float <tr><td> 160FLOAT <td> BLOB <td> CAST to BLOB <tr><td> TEXT <td> 161INTEGER <td> CAST to INTEGER <tr><td> TEXT <td> FLOAT 162<td> CAST to REAL <tr><td> TEXT <td> BLOB <td> No change 163<tr><td> BLOB <td> INTEGER <td> CAST to INTEGER <tr><td> 164BLOB <td> FLOAT <td> CAST to REAL <tr><td> BLOB <td> 165TEXT <td> Add a zero terminator if needed </table> 166.Ed 167.Pp 168Note that when type conversions occur, pointers returned by prior calls 169to sqlite3_column_blob(), sqlite3_column_text(), and/or sqlite3_column_text16() 170may be invalidated. 171Type conversions and pointer invalidations might occur in the following 172cases: 173.Bl -bullet 174.It 175The initial content is a BLOB and sqlite3_column_text() or sqlite3_column_text16() 176is called. 177A zero-terminator might need to be added to the string. 178.It 179The initial content is UTF-8 text and sqlite3_column_bytes16() or sqlite3_column_text16() 180is called. 181The content must be converted to UTF-16. 182.It 183The initial content is UTF-16 text and sqlite3_column_bytes() or sqlite3_column_text() 184is called. 185The content must be converted to UTF-8. 186.El 187.Pp 188Conversions between UTF-16be and UTF-16le are always done in place 189and do not invalidate a prior pointer, though of course the content 190of the buffer that the prior pointer references will have been modified. 191Other kinds of conversion are done in place when it is possible, but 192sometimes they are not possible and in those cases prior pointers are 193invalidated. 194.Pp 195The safest policy is to invoke these routines in one of the following 196ways: 197.Bl -bullet 198.It 199sqlite3_column_text() followed by sqlite3_column_bytes() 200.It 201sqlite3_column_blob() followed by sqlite3_column_bytes() 202.It 203sqlite3_column_text16() followed by sqlite3_column_bytes16() 204.El 205.Pp 206In other words, you should call sqlite3_column_text(), sqlite3_column_blob(), 207or sqlite3_column_text16() first to force the result into the desired 208format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() 209to find the size of the result. 210Do not mix calls to sqlite3_column_text() or sqlite3_column_blob() 211with calls to sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() 212with calls to sqlite3_column_bytes(). 213.Pp 214The pointers returned are valid until a type conversion occurs as described 215above, or until sqlite3_step() or sqlite3_reset() 216or sqlite3_finalize() is called. 217The memory space used to hold strings and BLOBs is freed automatically. 218Do <em>not</em> pass the pointers returned from sqlite3_column_blob(), 219sqlite3_column_text(), etc. 220into sqlite3_free(). 221.Pp 222If a memory allocation error occurs during the evaluation of any of 223these routines, a default value is returned. 224The default value is either the integer 0, the floating point number 2250.0, or a NULL pointer. 226Subsequent calls to sqlite3_errcode() will return 227SQLITE_NOMEM. 228.Sh SEE ALSO 229.Xr sqlite3_stmt 3 , 230.Xr sqlite3_bind_blob 3 , 231.Xr sqlite3_column_blob 3 , 232.Xr sqlite3_column_count 3 , 233.Xr sqlite3_column_blob 3 , 234.Xr sqlite3_errcode 3 , 235.Xr sqlite3_finalize 3 , 236.Xr sqlite3_malloc 3 , 237.Xr sqlite3_prepare 3 , 238.Xr sqlite3_reset 3 , 239.Xr sqlite3_result_blob 3 , 240.Xr sqlite3_mprintf 3 , 241.Xr sqlite3_step 3 , 242.Xr sqlite3_value_blob 3 , 243.Xr SQLITE_INTEGER 3 , 244.Xr SQLITE_OK 3 , 245.Xr SQLITE_INTEGER 3 , 246.Xr SQLITE_OK 3 , 247.Xr SQLITE_INTEGER 3 , 248.Xr sqlite3_value 3 249