1.Dd $Mdocdate$ 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 form the "result set" interface. 69.Pp 70These routines return information about a single column of the current 71result row of a query. 72In every case the first argument is a pointer to the prepared statement 73that is being evaluated (the sqlite3_stmt* that was returned 74from sqlite3_prepare_v2() or one of its variants) 75and the second argument is the index of the column for which information 76should be returned. 77The leftmost column of the result set has the index 0. 78The number of columns in the result can be determined using sqlite3_column_count(). 79.Pp 80If the SQL statement does not currently point to a valid row, or if 81the column index is out of range, the result is undefined. 82These routines may only be called when the most recent call to sqlite3_step() 83has returned SQLITE_ROW and neither sqlite3_reset() 84nor sqlite3_finalize() have been called subsequently. 85If any of these routines are called after sqlite3_reset() 86or sqlite3_finalize() or after sqlite3_step() 87has returned something other than SQLITE_ROW, the results 88are undefined. 89If sqlite3_step() or sqlite3_reset() or 90sqlite3_finalize() are called from a different thread 91while any of these routines are pending, then the results are undefined. 92.Pp 93The sqlite3_column_type() routine returns the datatype code 94for the initial data type of the result column. 95The returned value is one of SQLITE_INTEGER, SQLITE_FLOAT, 96SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL. 97The value returned by sqlite3_column_type() is only meaningful if no 98type conversions have occurred as described below. 99After a type conversion, the value returned by sqlite3_column_type() 100is undefined. 101Future versions of SQLite may change the behavior of sqlite3_column_type() 102following a type conversion. 103.Pp 104If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() 105routine returns the number of bytes in that BLOB or string. 106If the result is a UTF-16 string, then sqlite3_column_bytes() converts 107the string to UTF-8 and then returns the number of bytes. 108If the result is a numeric value then sqlite3_column_bytes() uses sqlite3_snprintf() 109to convert that value to a UTF-8 string and returns the number of bytes 110in that string. 111If the result is NULL, then sqlite3_column_bytes() returns zero. 112.Pp 113If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16() 114routine returns the number of bytes in that BLOB or string. 115If the result is a UTF-8 string, then sqlite3_column_bytes16() converts 116the string to UTF-16 and then returns the number of bytes. 117If the result is a numeric value then sqlite3_column_bytes16() uses 118sqlite3_snprintf() to convert that value to a UTF-16 119string and returns the number of bytes in that string. 120If the result is NULL, then sqlite3_column_bytes16() returns zero. 121.Pp 122The values returned by sqlite3_column_bytes() 123and sqlite3_column_bytes16() do not include 124the zero terminators at the end of the string. 125For clarity: the values returned by sqlite3_column_bytes() 126and sqlite3_column_bytes16() are the number 127of bytes in the string, not the number of characters. 128.Pp 129Strings returned by sqlite3_column_text() and sqlite3_column_text16(), 130even empty strings, are always zero-terminated. 131The return value from sqlite3_column_blob() for a zero-length BLOB 132is a NULL pointer. 133.Pp 134The object returned by sqlite3_column_value() 135is an unprotected sqlite3_value object. 136An unprotected sqlite3_value object may only be used with sqlite3_bind_value() 137and sqlite3_result_value(). 138If the unprotected sqlite3_value object returned 139by sqlite3_column_value() is used in any other 140way, including calls to routines like sqlite3_value_int(), 141sqlite3_value_text(), or sqlite3_value_bytes(), 142then the behavior is undefined. 143.Pp 144These routines attempt to convert the value where appropriate. 145For example, if the internal representation is FLOAT and a text result 146is requested, sqlite3_snprintf() is used internally 147to perform the conversion automatically. 148The following table details the conversions that are applied: 149.Bd -ragged 150<table border="1"> <tr><th> Internal<br>Type <th> Requested<br>Type 151<th> Conversion 152.Pp 153<tr><td> NULL <td> INTEGER <td> Result is 0 <tr><td> NULL 154<td> FLOAT <td> Result is 0.0 <tr><td> NULL <td> TEXT 155<td> Result is a NULL pointer <tr><td> NULL <td> BLOB <td> 156Result is a NULL pointer <tr><td> INTEGER <td> FLOAT <td> Convert 157from integer to float <tr><td> INTEGER <td> TEXT <td> ASCII rendering 158of the integer <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT 159<tr><td> FLOAT <td> INTEGER <td> CAST to INTEGER <tr><td> 160FLOAT <td> TEXT <td> ASCII rendering of the float <tr><td> 161FLOAT <td> BLOB <td> CAST to BLOB <tr><td> TEXT <td> 162INTEGER <td> CAST to INTEGER <tr><td> TEXT <td> FLOAT 163<td> CAST to REAL <tr><td> TEXT <td> BLOB <td> No change 164<tr><td> BLOB <td> INTEGER <td> CAST to INTEGER <tr><td> 165BLOB <td> FLOAT <td> CAST to REAL <tr><td> BLOB <td> 166TEXT <td> Add a zero terminator if needed </table> 167.Ed 168.Pp 169The table above makes reference to standard C library functions atoi() 170and atof(). 171SQLite does not really use these functions. 172It has its own equivalent internal routines. 173The atoi() and atof() names are used in the table for brevity and because 174they are familiar to most C programmers. 175.Pp 176Note that when type conversions occur, pointers returned by prior calls 177to sqlite3_column_blob(), sqlite3_column_text(), and/or sqlite3_column_text16() 178may be invalidated. 179Type conversions and pointer invalidations might occur in the following 180cases: 181.Bl -bullet 182.It 183The initial content is a BLOB and sqlite3_column_text() or sqlite3_column_text16() 184is called. 185A zero-terminator might need to be added to the string. 186.It 187The initial content is UTF-8 text and sqlite3_column_bytes16() or sqlite3_column_text16() 188is called. 189The content must be converted to UTF-16. 190.It 191The initial content is UTF-16 text and sqlite3_column_bytes() or sqlite3_column_text() 192is called. 193The content must be converted to UTF-8. 194.El 195.Pp 196Conversions between UTF-16be and UTF-16le are always done in place 197and do not invalidate a prior pointer, though of course the content 198of the buffer that the prior pointer references will have been modified. 199Other kinds of conversion are done in place when it is possible, but 200sometimes they are not possible and in those cases prior pointers are 201invalidated. 202.Pp 203The safest and easiest to remember policy is to invoke these routines 204in one of the following ways: 205.Bl -bullet 206.It 207sqlite3_column_text() followed by sqlite3_column_bytes() 208.It 209sqlite3_column_blob() followed by sqlite3_column_bytes() 210.It 211sqlite3_column_text16() followed by sqlite3_column_bytes16() 212.El 213.Pp 214In other words, you should call sqlite3_column_text(), sqlite3_column_blob(), 215or sqlite3_column_text16() first to force the result into the desired 216format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() 217to find the size of the result. 218Do not mix calls to sqlite3_column_text() or sqlite3_column_blob() 219with calls to sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16() 220with calls to sqlite3_column_bytes(). 221.Pp 222The pointers returned are valid until a type conversion occurs as described 223above, or until sqlite3_step() or sqlite3_reset() 224or sqlite3_finalize() is called. 225The memory space used to hold strings and BLOBs is freed automatically. 226Do \fBnot\fP pass the pointers returned from sqlite3_column_blob(), 227sqlite3_column_text(), etc. 228into sqlite3_free(). 229.Pp 230If a memory allocation error occurs during the evaluation of any of 231these routines, a default value is returned. 232The default value is either the integer 0, the floating point number 2330.0, or a NULL pointer. 234Subsequent calls to sqlite3_errcode() will return 235SQLITE_NOMEM. 236.Sh SEE ALSO 237.Xr sqlite3_stmt 3 , 238.Xr sqlite3_bind_blob 3 , 239.Xr sqlite3_column_blob 3 , 240.Xr sqlite3_column_count 3 , 241.Xr sqlite3_column_blob 3 , 242.Xr sqlite3_errcode 3 , 243.Xr sqlite3_finalize 3 , 244.Xr sqlite3_malloc 3 , 245.Xr sqlite3_prepare 3 , 246.Xr sqlite3_reset 3 , 247.Xr sqlite3_result_blob 3 , 248.Xr sqlite3_mprintf 3 , 249.Xr sqlite3_step 3 , 250.Xr sqlite3_value_blob 3 , 251.Xr SQLITE_INTEGER 3 , 252.Xr SQLITE_OK 3 , 253.Xr SQLITE_INTEGER 3 , 254.Xr SQLITE_OK 3 , 255.Xr SQLITE_INTEGER 3 , 256.Xr sqlite3_value 3 257