diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_column_blob.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_column_blob.3 | 356 |
1 files changed, 356 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_column_blob.3 b/static/netbsd/man3/sqlite3_column_blob.3 new file mode 100644 index 00000000..38c2cf92 --- /dev/null +++ b/static/netbsd/man3/sqlite3_column_blob.3 @@ -0,0 +1,356 @@ +.Dd January 24, 2024 +.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 +.In sqlite3.h +.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 +.Pp + \fBsqlite3_column_blob\fP \(-> BLOB result + \fBsqlite3_column_double\fP \(-> REAL result + \fBsqlite3_column_int\fP \(-> 32-bit INTEGER result + \fBsqlite3_column_int64\fP \(-> 64-bit INTEGER result + \fBsqlite3_column_text\fP \(-> UTF-8 TEXT result + \fBsqlite3_column_text16\fP \(-> UTF-16 TEXT result + \fBsqlite3_column_value\fP \(-> The result as an unprotected sqlite3_value +object. + + \fBsqlite3_column_bytes\fP \(-> Size of a BLOB or a UTF-8 TEXT result in bytes + \fBsqlite3_column_bytes16 \fP \(-> Size of UTF-16 TEXT in bytes + \fBsqlite3_column_type\fP \(-> Default datatype of the result +.Pp +.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 +.Fn 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 +.Fn sqlite3_column_count . +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 +.Fn sqlite3_step +has returned SQLITE_ROW and neither +.Fn sqlite3_reset +nor +.Fn sqlite3_finalize +have been called subsequently. +If any of these routines are called after +.Fn sqlite3_reset +or +.Fn sqlite3_finalize +or after +.Fn sqlite3_step +has returned something other than SQLITE_ROW, the results +are undefined. +If +.Fn sqlite3_step +or +.Fn sqlite3_reset +or +.Fn 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 +.Fn 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 +.Fn 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 +.Fn sqlite3_column_bytes +and +.Fn sqlite3_column_bytes16 +do not include the zero terminators at the end of the string. +For clarity: the values returned by +.Fn sqlite3_column_bytes +and +.Fn 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 +Strings returned by sqlite3_column_text16() always have the endianness +which is native to the platform, regardless of the text encoding set +for the database. +.Pp +\fBWarning:\fP The object returned by +.Fn sqlite3_column_value +is an unprotected sqlite3_value object. +In a multithreaded environment, an unprotected sqlite3_value object +may only be used safely with +.Fn sqlite3_bind_value +and +.Fn sqlite3_result_value . +If the unprotected sqlite3_value object returned +by +.Fn sqlite3_column_value +is used in any other way, including calls to routines like +.Fn sqlite3_value_int , +.Fn sqlite3_value_text , +or +.Fn 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 +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, +.Fn sqlite3_snprintf +is used internally to perform the conversion automatically. +The following table details the conversions that are applied: +.Bd -ragged +.Pp + Internal Type Requested Type Conversion + NULL INTEGER Result is 0 + NULL FLOAT Result is 0.0 + NULL TEXT Result is a NULL pointer + NULL BLOB Result is a NULL pointer + INTEGER FLOAT Convert from integer to float + INTEGER TEXT ASCII rendering of the integer + INTEGER BLOB Same as INTEGER->TEXT + FLOAT INTEGER CAST to INTEGER + FLOAT TEXT ASCII rendering of the float + FLOAT BLOB CAST to BLOB + TEXT INTEGER CAST to INTEGER + TEXT FLOAT CAST to REAL + TEXT BLOB No change + BLOB INTEGER CAST to INTEGER + BLOB FLOAT CAST to REAL + BLOB TEXT CAST to TEXT, ensure zero terminator +.Pp +.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 +.Fn sqlite3_step +or +.Fn sqlite3_reset +or +.Fn sqlite3_finalize +is called. +The memory space used to hold strings and BLOBs is freed automatically. +Do not pass the pointers returned from +.Fn sqlite3_column_blob , +.Fn sqlite3_column_text , +etc. +into +.Fn sqlite3_free . +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 +.Fn sqlite3_errcode +immediately after the suspect return value is obtained and before any +other SQLite interface is called on the same database connection. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 5041. +.Bd -literal +SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol); +SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol); +SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol); +SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol); +SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol); +SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol); +SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol); +SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol); +SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol); +SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_bind_blob 3 , +.Xr sqlite3_column_count 3 , +.Xr sqlite3_errcode 3 , +.Xr sqlite3_finalize 3 , +.Xr sqlite3_malloc 3 , +.Xr sqlite3_mprintf 3 , +.Xr sqlite3_prepare 3 , +.Xr sqlite3_reset 3 , +.Xr sqlite3_result_blob 3 , +.Xr sqlite3_step 3 , +.Xr sqlite3_stmt 3 , +.Xr sqlite3_value 3 , +.Xr sqlite3_value_blob 3 , +.Xr SQLITE_INTEGER 3 , +.Xr SQLITE_OK 3 |