diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_value_blob.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_value_blob.3 | 250 |
1 files changed, 250 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_value_blob.3 b/static/netbsd/man3/sqlite3_value_blob.3 new file mode 100644 index 00000000..df74210d --- /dev/null +++ b/static/netbsd/man3/sqlite3_value_blob.3 @@ -0,0 +1,250 @@ +.Dd January 24, 2024 +.Dt SQLITE3_VALUE_BLOB 3 +.Os +.Sh NAME +.Nm sqlite3_value_blob , +.Nm sqlite3_value_double , +.Nm sqlite3_value_int , +.Nm sqlite3_value_int64 , +.Nm sqlite3_value_pointer , +.Nm sqlite3_value_text , +.Nm sqlite3_value_text16 , +.Nm sqlite3_value_text16le , +.Nm sqlite3_value_text16be , +.Nm sqlite3_value_bytes , +.Nm sqlite3_value_bytes16 , +.Nm sqlite3_value_type , +.Nm sqlite3_value_numeric_type , +.Nm sqlite3_value_nochange , +.Nm sqlite3_value_frombind +.Nd obtaining SQL values +.Sh SYNOPSIS +.In sqlite3.h +.Ft const void * +.Fo sqlite3_value_blob +.Fa "sqlite3_value*" +.Fc +.Ft double +.Fo sqlite3_value_double +.Fa "sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_value_int +.Fa "sqlite3_value*" +.Fc +.Ft sqlite3_int64 +.Fo sqlite3_value_int64 +.Fa "sqlite3_value*" +.Fc +.Ft void * +.Fo sqlite3_value_pointer +.Fa "sqlite3_value*" +.Fa "const char*" +.Fc +.Ft const unsigned char * +.Fo sqlite3_value_text +.Fa "sqlite3_value*" +.Fc +.Ft const void * +.Fo sqlite3_value_text16 +.Fa "sqlite3_value*" +.Fc +.Ft const void * +.Fo sqlite3_value_text16le +.Fa "sqlite3_value*" +.Fc +.Ft const void * +.Fo sqlite3_value_text16be +.Fa "sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_value_bytes +.Fa "sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_value_bytes16 +.Fa "sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_value_type +.Fa "sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_value_numeric_type +.Fa "sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_value_nochange +.Fa "sqlite3_value*" +.Fc +.Ft int +.Fo sqlite3_value_frombind +.Fa "sqlite3_value*" +.Fc +.Sh DESCRIPTION +\fBSummary:\fP +.Bd -ragged +.Pp + \fBsqlite3_value_blob\fP \(-> BLOB value + \fBsqlite3_value_double\fP \(-> REAL value + \fBsqlite3_value_int\fP \(-> 32-bit INTEGER value + \fBsqlite3_value_int64\fP \(-> 64-bit INTEGER value + \fBsqlite3_value_pointer\fP \(-> Pointer value + \fBsqlite3_value_text\fP \(-> UTF-8 TEXT value + \fBsqlite3_value_text16\fP \(-> UTF-16 TEXT value in the native byteorder + \fBsqlite3_value_text16be\fP \(-> UTF-16be TEXT value + \fBsqlite3_value_text16le\fP \(-> UTF-16le TEXT value + + \fBsqlite3_value_bytes\fP \(-> Size of a BLOB or a UTF-8 TEXT in bytes + \fBsqlite3_value_bytes16 \fP \(-> Size of UTF-16 TEXT in bytes + \fBsqlite3_value_type\fP \(-> Default datatype of the value + \fBsqlite3_value_numeric_type \fP \(-> Best numeric datatype of the value + \fBsqlite3_value_nochange \fP \(-> True if the column is unchanged in an +UPDATE against a virtual table. + \fBsqlite3_value_frombind \fP \(-> True if value originated from a bound parameter +.Pp +.Ed +.Pp +\fBDetails:\fP +.Pp +These routines extract type, size, and content information from protected sqlite3_value +objects. +Protected sqlite3_value objects are used to pass parameter information +into the functions that implement application-defined SQL functions +and virtual tables. +.Pp +These routines work only with protected sqlite3_value +objects. +Any attempt to use these routines on an unprotected sqlite3_value +is not threadsafe. +.Pp +These routines work just like the corresponding column access functions +except that these routines take a single protected sqlite3_value +object pointer instead of a sqlite3_stmt* pointer and +an integer column number. +.Pp +The sqlite3_value_text16() interface extracts a UTF-16 string in the +native byte-order of the host machine. +The sqlite3_value_text16be() and sqlite3_value_text16le() interfaces +extract UTF-16 strings as big-endian and little-endian respectively. +.Pp +If sqlite3_value object V was initialized using sqlite3_bind_pointer(S,I,P,X,D) +or sqlite3_result_pointer(C,P,X,D) and +if X and Y are strings that compare equal according to strcmp(X,Y), +then sqlite3_value_pointer(V,Y) will return the pointer P. +Otherwise, sqlite3_value_pointer(V,Y) returns a NULL. +The sqlite3_bind_pointer() routine is part of the pointer passing interface +added for SQLite 3.20.0. +.Pp +The sqlite3_value_type(V) interface returns the datatype code +for the initial datatype of the sqlite3_value object V. +The returned value is one of SQLITE_INTEGER, SQLITE_FLOAT, +SQLITE_TEXT, SQLITE_BLOB, or SQLITE_NULL. +Other interfaces might change the datatype for an sqlite3_value object. +For example, if the datatype is initially SQLITE_INTEGER and sqlite3_value_text(V) +is called to extract a text value for that integer, then subsequent +calls to sqlite3_value_type(V) might return SQLITE_TEXT. +Whether or not a persistent internal datatype conversion occurs is +undefined and may change from one release of SQLite to the next. +.Pp +The sqlite3_value_numeric_type() interface attempts to apply numeric +affinity to the value. +This means that an attempt is made to convert the value to an integer +or floating point. +If such a conversion is possible without loss of information (in other +words, if the value is a string that looks like a number) then the +conversion is performed. +Otherwise no conversion occurs. +The datatype after conversion is returned. +.Pp +Within the xUpdate method of a virtual table, the +sqlite3_value_nochange(X) interface returns true if and only if the +column corresponding to X is unchanged by the UPDATE operation that +the xUpdate method call was invoked to implement and if and the prior +xColumn method call that was invoked to extracted the value +for that column returned without setting a result (probably because +it queried +.Fn sqlite3_vtab_nochange +and found that the column was unchanging). +Within an xUpdate method, any value for which sqlite3_value_nochange(X) +is true will in all other respects appear to be a NULL value. +If sqlite3_value_nochange(X) is invoked anywhere other than within +an xUpdate method call for an UPDATE statement, then the return +value is arbitrary and meaningless. +.Pp +The sqlite3_value_frombind(X) interface returns non-zero if the value +X originated from one of the sqlite3_bind() interfaces. +If X comes from an SQL literal value, or a table column, or an expression, +then sqlite3_value_frombind(X) returns zero. +.Pp +Please pay particular attention to the fact that the pointer returned +from +.Fn sqlite3_value_blob , +.Fn sqlite3_value_text , +or +.Fn sqlite3_value_text16 +can be invalidated by a subsequent call to +.Fn sqlite3_value_bytes , +.Fn sqlite3_value_bytes16 , +.Fn sqlite3_value_text , +or +.Fn sqlite3_value_text16 . +These routines must be called from the same thread as the SQL function +that supplied the sqlite3_value* parameters. +.Pp +As long as the input parameter is correct, these routines can 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_value_blob() +.It +sqlite3_value_text() +.It +sqlite3_value_text16() +.It +sqlite3_value_text16le() +.It +sqlite3_value_text16be() +.It +sqlite3_value_bytes() +.It +sqlite3_value_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 5629. +.Bd -literal +SQLITE_API const void *sqlite3_value_blob(sqlite3_value*); +SQLITE_API double sqlite3_value_double(sqlite3_value*); +SQLITE_API int sqlite3_value_int(sqlite3_value*); +SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*); +SQLITE_API void *sqlite3_value_pointer(sqlite3_value*, const char*); +SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*); +SQLITE_API const void *sqlite3_value_text16(sqlite3_value*); +SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*); +SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*); +SQLITE_API int sqlite3_value_bytes(sqlite3_value*); +SQLITE_API int sqlite3_value_bytes16(sqlite3_value*); +SQLITE_API int sqlite3_value_type(sqlite3_value*); +SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*); +SQLITE_API int sqlite3_value_nochange(sqlite3_value*); +SQLITE_API int sqlite3_value_frombind(sqlite3_value*); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_bind_blob 3 , +.Xr sqlite3_column_blob 3 , +.Xr sqlite3_errcode 3 , +.Xr sqlite3_value 3 , +.Xr sqlite3_vtab_nochange 3 , +.Xr SQLITE_INTEGER 3 |