1.Dd January 24, 2024 2.Dt SQLITE3_RESULT_BLOB 3 3.Os 4.Sh NAME 5.Nm sqlite3_result_blob , 6.Nm sqlite3_result_blob64 , 7.Nm sqlite3_result_double , 8.Nm sqlite3_result_error , 9.Nm sqlite3_result_error16 , 10.Nm sqlite3_result_error_toobig , 11.Nm sqlite3_result_error_nomem , 12.Nm sqlite3_result_error_code , 13.Nm sqlite3_result_int , 14.Nm sqlite3_result_int64 , 15.Nm sqlite3_result_null , 16.Nm sqlite3_result_text , 17.Nm sqlite3_result_text64 , 18.Nm sqlite3_result_text16 , 19.Nm sqlite3_result_text16le , 20.Nm sqlite3_result_text16be , 21.Nm sqlite3_result_value , 22.Nm sqlite3_result_pointer , 23.Nm sqlite3_result_zeroblob , 24.Nm sqlite3_result_zeroblob64 25.Nd setting the result of an SQL function 26.Sh SYNOPSIS 27.In sqlite3.h 28.Ft void 29.Fo sqlite3_result_blob 30.Fa "sqlite3_context*" 31.Fa "const void*" 32.Fa "int" 33.Fa "void(*)(void*)" 34.Fc 35.Ft void 36.Fo sqlite3_result_blob64 37.Fa "sqlite3_context*" 38.Fa "const void*" 39.Fa "sqlite3_uint64" 40.Fa "void(*)(void*)" 41.Fc 42.Ft void 43.Fo sqlite3_result_double 44.Fa "sqlite3_context*" 45.Fa "double" 46.Fc 47.Ft void 48.Fo sqlite3_result_error 49.Fa "sqlite3_context*" 50.Fa "const char*" 51.Fa "int" 52.Fc 53.Ft void 54.Fo sqlite3_result_error16 55.Fa "sqlite3_context*" 56.Fa "const void*" 57.Fa "int" 58.Fc 59.Ft void 60.Fo sqlite3_result_error_toobig 61.Fa "sqlite3_context*" 62.Fc 63.Ft void 64.Fo sqlite3_result_error_nomem 65.Fa "sqlite3_context*" 66.Fc 67.Ft void 68.Fo sqlite3_result_error_code 69.Fa "sqlite3_context*" 70.Fa "int" 71.Fc 72.Ft void 73.Fo sqlite3_result_int 74.Fa "sqlite3_context*" 75.Fa "int" 76.Fc 77.Ft void 78.Fo sqlite3_result_int64 79.Fa "sqlite3_context*" 80.Fa "sqlite3_int64" 81.Fc 82.Ft void 83.Fo sqlite3_result_null 84.Fa "sqlite3_context*" 85.Fc 86.Ft void 87.Fo sqlite3_result_text 88.Fa "sqlite3_context*" 89.Fa "const char*" 90.Fa "int" 91.Fa "void(*)(void*)" 92.Fc 93.Ft void 94.Fo sqlite3_result_text64 95.Fa "sqlite3_context*" 96.Fa "const char*" 97.Fa "sqlite3_uint64" 98.Fa "void(*)(void*)" 99.Fa "unsigned char encoding" 100.Fc 101.Ft void 102.Fo sqlite3_result_text16 103.Fa "sqlite3_context*" 104.Fa "const void*" 105.Fa "int" 106.Fa "void(*)(void*)" 107.Fc 108.Ft void 109.Fo sqlite3_result_text16le 110.Fa "sqlite3_context*" 111.Fa "const void*" 112.Fa "int" 113.Fa "void(*)(void*)" 114.Fc 115.Ft void 116.Fo sqlite3_result_text16be 117.Fa "sqlite3_context*" 118.Fa "const void*" 119.Fa "int" 120.Fa "void(*)(void*)" 121.Fc 122.Ft void 123.Fo sqlite3_result_value 124.Fa "sqlite3_context*" 125.Fa "sqlite3_value*" 126.Fc 127.Ft void 128.Fo sqlite3_result_pointer 129.Fa "sqlite3_context*" 130.Fa "void*" 131.Fa "const char*" 132.Fa "void(*)(void*)" 133.Fc 134.Ft void 135.Fo sqlite3_result_zeroblob 136.Fa "sqlite3_context*" 137.Fa "int n" 138.Fc 139.Ft int 140.Fo sqlite3_result_zeroblob64 141.Fa "sqlite3_context*" 142.Fa "sqlite3_uint64 n" 143.Fc 144.Sh DESCRIPTION 145These routines are used by the xFunc or xFinal callbacks that implement 146SQL functions and aggregates. 147See 148.Fn sqlite3_create_function 149and 150.Fn sqlite3_create_function16 151for additional information. 152.Pp 153These functions work very much like the parameter binding 154family of functions used to bind values to host parameters in prepared 155statements. 156Refer to the SQL parameter documentation for additional 157information. 158.Pp 159The sqlite3_result_blob() interface sets the result from an application-defined 160function to be the BLOB whose content is pointed to by the second parameter 161and which is N bytes long where N is the third parameter. 162.Pp 163The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N) 164interfaces set the result of the application-defined function to be 165a BLOB containing all zero bytes and N bytes in size. 166.Pp 167The sqlite3_result_double() interface sets the result from an application-defined 168function to be a floating point value specified by its 2nd argument. 169.Pp 170The sqlite3_result_error() and sqlite3_result_error16() functions cause 171the implemented SQL function to throw an exception. 172SQLite uses the string pointed to by the 2nd parameter of sqlite3_result_error() 173or sqlite3_result_error16() as the text of an error message. 174SQLite interprets the error message string from sqlite3_result_error() 175as UTF-8. 176SQLite interprets the string from sqlite3_result_error16() as UTF-16 177using the same byte-order determination rules 178as 179.Fn sqlite3_bind_text16 . 180If the third parameter to sqlite3_result_error() or sqlite3_result_error16() 181is negative then SQLite takes as the error message all text up through 182the first zero character. 183If the third parameter to sqlite3_result_error() or sqlite3_result_error16() 184is non-negative then SQLite takes that many bytes (not characters) 185from the 2nd parameter as the error message. 186The sqlite3_result_error() and sqlite3_result_error16() routines make 187a private copy of the error message text before they return. 188Hence, the calling function can deallocate or modify the text after 189they return without harm. 190The sqlite3_result_error_code() function changes the error code returned 191by SQLite as a result of an error in a function. 192By default, the error code is SQLITE_ERROR. 193A subsequent call to sqlite3_result_error() or sqlite3_result_error16() 194resets the error code to SQLITE_ERROR. 195.Pp 196The sqlite3_result_error_toobig() interface causes SQLite to throw 197an error indicating that a string or BLOB is too long to represent. 198.Pp 199The sqlite3_result_error_nomem() interface causes SQLite to throw an 200error indicating that a memory allocation failed. 201.Pp 202The sqlite3_result_int() interface sets the return value of the application-defined 203function to be the 32-bit signed integer value given in the 2nd argument. 204The sqlite3_result_int64() interface sets the return value of the application-defined 205function to be the 64-bit signed integer value given in the 2nd argument. 206.Pp 207The sqlite3_result_null() interface sets the return value of the application-defined 208function to be NULL. 209.Pp 210The sqlite3_result_text(), sqlite3_result_text16(), sqlite3_result_text16le(), 211and sqlite3_result_text16be() interfaces set the return value of the 212application-defined function to be a text string which is represented 213as UTF-8, UTF-16 native byte order, UTF-16 little endian, or UTF-16 214big endian, respectively. 215The sqlite3_result_text64() interface sets the return value of an application-defined 216function to be a text string in an encoding specified by the fifth 217(and last) parameter, which must be one of SQLITE_UTF8, 218SQLITE_UTF16, SQLITE_UTF16BE, or SQLITE_UTF16LE. 219SQLite takes the text result from the application from the 2nd parameter 220of the sqlite3_result_text* interfaces. 221If the 3rd parameter to any of the sqlite3_result_text* interfaces 222other than sqlite3_result_text64() is negative, then SQLite computes 223the string length itself by searching the 2nd parameter for the first 224zero character. 225If the 3rd parameter to the sqlite3_result_text* interfaces is non-negative, 226then as many bytes (not characters) of the text pointed to by the 2nd 227parameter are taken as the application-defined function result. 228If the 3rd parameter is non-negative, then it must be the byte offset 229into the string where the NUL terminator would appear if the string 230where NUL terminated. 231If any NUL characters occur in the string at a byte offset that is 232less than the value of the 3rd parameter, then the resulting string 233will contain embedded NULs and the result of expressions operating 234on strings with embedded NULs is undefined. 235If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob 236is a non-NULL pointer, then SQLite calls that function as the destructor 237on the text or BLOB result when it has finished using that result. 238If the 4th parameter to the sqlite3_result_text* interfaces or to sqlite3_result_blob 239is the special constant SQLITE_STATIC, then SQLite assumes that the 240text or BLOB result is in constant space and does not copy the content 241of the parameter nor call a destructor on the content when it has finished 242using that result. 243If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob 244is the special constant SQLITE_TRANSIENT then SQLite makes a copy of 245the result into space obtained from 246.Fn sqlite3_malloc 247before it returns. 248.Pp 249For the sqlite3_result_text16(), sqlite3_result_text16le(), and sqlite3_result_text16be() 250routines, and for sqlite3_result_text64() when the encoding is not 251UTF8, if the input UTF16 begins with a byte-order mark (BOM, U+FEFF) 252then the BOM is removed from the string and the rest of the string 253is interpreted according to the byte-order specified by the BOM. 254The byte-order specified by the BOM at the beginning of the text overrides 255the byte-order specified by the interface procedure. 256So, for example, if sqlite3_result_text16le() is invoked with text 257that begins with bytes 0xfe, 0xff (a big-endian byte-order mark) then 258the first two bytes of input are skipped and the remaining input is 259interpreted as UTF16BE text. 260.Pp 261For UTF16 input text to the sqlite3_result_text16(), sqlite3_result_text16be(), 262sqlite3_result_text16le(), and sqlite3_result_text64() routines, if 263the text contains invalid UTF16 characters, the invalid characters 264might be converted into the unicode replacement character, U+FFFD. 265.Pp 266The sqlite3_result_value() interface sets the result of the application-defined 267function to be a copy of the unprotected sqlite3_value 268object specified by the 2nd parameter. 269The sqlite3_result_value() interface makes a copy of the sqlite3_value 270so that the sqlite3_value specified in the parameter may 271change or be deallocated after sqlite3_result_value() returns without 272harm. 273A protected sqlite3_value object may always 274be used where an unprotected sqlite3_value 275object is required, so either kind of sqlite3_value object 276can be used with this interface. 277.Pp 278The sqlite3_result_pointer(C,P,T,D) interface sets the result to an 279SQL NULL value, just like sqlite3_result_null(C), 280except that it also associates the host-language pointer P or type 281T with that NULL value such that the pointer can be retrieved within 282an application-defined SQL function 283using 284.Fn sqlite3_value_pointer . 285If the D parameter is not NULL, then it is a pointer to a destructor 286for the P parameter. 287SQLite invokes D with P as its only argument when SQLite is finished 288with P. 289The T parameter should be a static string and preferably a string literal. 290The sqlite3_result_pointer() routine is part of the pointer passing interface 291added for SQLite 3.20.0. 292.Pp 293If these routines are called from within the different thread than 294the one containing the application-defined function that received the 295sqlite3_context pointer, the results are undefined. 296.Sh IMPLEMENTATION NOTES 297These declarations were extracted from the 298interface documentation at line 6047. 299.Bd -literal 300SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*)); 301SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*, 302 sqlite3_uint64,void(*)(void*)); 303SQLITE_API void sqlite3_result_double(sqlite3_context*, double); 304SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int); 305SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int); 306SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*); 307SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*); 308SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int); 309SQLITE_API void sqlite3_result_int(sqlite3_context*, int); 310SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64); 311SQLITE_API void sqlite3_result_null(sqlite3_context*); 312SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*)); 313SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char*,sqlite3_uint64, 314 void(*)(void*), unsigned char encoding); 315SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*)); 316SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*)); 317SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*)); 318SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*); 319SQLITE_API void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*)); 320SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n); 321SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n); 322.Ed 323.Sh SEE ALSO 324.Xr sqlite3_bind_blob 3 , 325.Xr sqlite3_context 3 , 326.Xr sqlite3_create_function 3 , 327.Xr sqlite3_malloc 3 , 328.Xr sqlite3_value 3 , 329.Xr sqlite3_value_blob 3 , 330.Xr SQLITE_UTF8 3 331