1.Dd December 19, 2018 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.Ft void 28.Fo sqlite3_result_blob 29.Fa "sqlite3_context*" 30.Fa "const void*" 31.Fa "int" 32.Fa "void(*)(void*)" 33.Fc 34.Ft void 35.Fo sqlite3_result_blob64 36.Fa "sqlite3_context*" 37.Fa "const void*" 38.Fa "sqlite3_uint64" 39.Fa "void(*)(void*)" 40.Fc 41.Ft void 42.Fo sqlite3_result_double 43.Fa "sqlite3_context*" 44.Fa "double" 45.Fc 46.Ft void 47.Fo sqlite3_result_error 48.Fa "sqlite3_context*" 49.Fa "const char*" 50.Fa "int" 51.Fc 52.Ft void 53.Fo sqlite3_result_error16 54.Fa "sqlite3_context*" 55.Fa "const void*" 56.Fa "int" 57.Fc 58.Ft void 59.Fo sqlite3_result_error_toobig 60.Fa "sqlite3_context*" 61.Fc 62.Ft void 63.Fo sqlite3_result_error_nomem 64.Fa "sqlite3_context*" 65.Fc 66.Ft void 67.Fo sqlite3_result_error_code 68.Fa "sqlite3_context*" 69.Fa "int" 70.Fc 71.Ft void 72.Fo sqlite3_result_int 73.Fa "sqlite3_context*" 74.Fa "int" 75.Fc 76.Ft void 77.Fo sqlite3_result_int64 78.Fa "sqlite3_context*" 79.Fa "sqlite3_int64" 80.Fc 81.Ft void 82.Fo sqlite3_result_null 83.Fa "sqlite3_context*" 84.Fc 85.Ft void 86.Fo sqlite3_result_text 87.Fa "sqlite3_context*" 88.Fa "const char*" 89.Fa "int" 90.Fa "void(*)(void*)" 91.Fc 92.Ft void 93.Fo sqlite3_result_text64 94.Fa "sqlite3_context*" 95.Fa "const char*" 96.Fa "sqlite3_uint64" 97.Fa "void(*)(void*)" 98.Fa "unsigned char encoding" 99.Fc 100.Ft void 101.Fo sqlite3_result_text16 102.Fa "sqlite3_context*" 103.Fa "const void*" 104.Fa "int" 105.Fa "void(*)(void*)" 106.Fc 107.Ft void 108.Fo sqlite3_result_text16le 109.Fa "sqlite3_context*" 110.Fa "const void*" 111.Fa "int" 112.Fa "void(*)(void*)" 113.Fc 114.Ft void 115.Fo sqlite3_result_text16be 116.Fa "sqlite3_context*" 117.Fa "const void*" 118.Fa "int" 119.Fa "void(*)(void*)" 120.Fc 121.Ft void 122.Fo sqlite3_result_value 123.Fa "sqlite3_context*" 124.Fa "sqlite3_value*" 125.Fc 126.Ft void 127.Fo sqlite3_result_pointer 128.Fa "sqlite3_context*" 129.Fa "void*" 130.Fa "const char*" 131.Fa "void(*)(void*)" 132.Fc 133.Ft void 134.Fo sqlite3_result_zeroblob 135.Fa "sqlite3_context*" 136.Fa "int n" 137.Fc 138.Ft int 139.Fo sqlite3_result_zeroblob64 140.Fa "sqlite3_context*" 141.Fa "sqlite3_uint64 n" 142.Fc 143.Sh DESCRIPTION 144These routines are used by the xFunc or xFinal callbacks that implement 145SQL functions and aggregates. 146See sqlite3_create_function() and sqlite3_create_function16() 147for additional information. 148.Pp 149These functions work very much like the parameter binding 150family of functions used to bind values to host parameters in prepared 151statements. 152Refer to the SQL parameter documentation for additional 153information. 154.Pp 155The sqlite3_result_blob() interface sets the result from an application-defined 156function to be the BLOB whose content is pointed to by the second parameter 157and which is N bytes long where N is the third parameter. 158.Pp 159The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N) 160interfaces set the result of the application-defined function to be 161a BLOB containing all zero bytes and N bytes in size. 162.Pp 163The sqlite3_result_double() interface sets the result from an application-defined 164function to be a floating point value specified by its 2nd argument. 165.Pp 166The sqlite3_result_error() and sqlite3_result_error16() functions cause 167the implemented SQL function to throw an exception. 168SQLite uses the string pointed to by the 2nd parameter of sqlite3_result_error() 169or sqlite3_result_error16() as the text of an error message. 170SQLite interprets the error message string from sqlite3_result_error() 171as UTF-8. 172SQLite interprets the string from sqlite3_result_error16() as UTF-16 173in native byte order. 174If the third parameter to sqlite3_result_error() or sqlite3_result_error16() 175is negative then SQLite takes as the error message all text up through 176the first zero character. 177If the third parameter to sqlite3_result_error() or sqlite3_result_error16() 178is non-negative then SQLite takes that many bytes (not characters) 179from the 2nd parameter as the error message. 180The sqlite3_result_error() and sqlite3_result_error16() routines make 181a private copy of the error message text before they return. 182Hence, the calling function can deallocate or modify the text after 183they return without harm. 184The sqlite3_result_error_code() function changes the error code returned 185by SQLite as a result of an error in a function. 186By default, the error code is SQLITE_ERROR. 187A subsequent call to sqlite3_result_error() or sqlite3_result_error16() 188resets the error code to SQLITE_ERROR. 189.Pp 190The sqlite3_result_error_toobig() interface causes SQLite to throw 191an error indicating that a string or BLOB is too long to represent. 192.Pp 193The sqlite3_result_error_nomem() interface causes SQLite to throw an 194error indicating that a memory allocation failed. 195.Pp 196The sqlite3_result_int() interface sets the return value of the application-defined 197function to be the 32-bit signed integer value given in the 2nd argument. 198The sqlite3_result_int64() interface sets the return value of the application-defined 199function to be the 64-bit signed integer value given in the 2nd argument. 200.Pp 201The sqlite3_result_null() interface sets the return value of the application-defined 202function to be NULL. 203.Pp 204The sqlite3_result_text(), sqlite3_result_text16(), sqlite3_result_text16le(), 205and sqlite3_result_text16be() interfaces set the return value of the 206application-defined function to be a text string which is represented 207as UTF-8, UTF-16 native byte order, UTF-16 little endian, or UTF-16 208big endian, respectively. 209The sqlite3_result_text64() interface sets the return value of an application-defined 210function to be a text string in an encoding specified by the fifth 211(and last) parameter, which must be one of SQLITE_UTF8, 212SQLITE_UTF16, SQLITE_UTF16BE, or SQLITE_UTF16LE. 213SQLite takes the text result from the application from the 2nd parameter 214of the sqlite3_result_text* interfaces. 215If the 3rd parameter to the sqlite3_result_text* interfaces is negative, 216then SQLite takes result text from the 2nd parameter through the first 217zero character. 218If the 3rd parameter to the sqlite3_result_text* interfaces is non-negative, 219then as many bytes (not characters) of the text pointed to by the 2nd 220parameter are taken as the application-defined function result. 221If the 3rd parameter is non-negative, then it must be the byte offset 222into the string where the NUL terminator would appear if the string 223where NUL terminated. 224If any NUL characters occur in the string at a byte offset that is 225less than the value of the 3rd parameter, then the resulting string 226will contain embedded NULs and the result of expressions operating 227on strings with embedded NULs is undefined. 228If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob 229is a non-NULL pointer, then SQLite calls that function as the destructor 230on the text or BLOB result when it has finished using that result. 231If the 4th parameter to the sqlite3_result_text* interfaces or to sqlite3_result_blob 232is the special constant SQLITE_STATIC, then SQLite assumes that the 233text or BLOB result is in constant space and does not copy the content 234of the parameter nor call a destructor on the content when it has finished 235using that result. 236If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob 237is the special constant SQLITE_TRANSIENT then SQLite makes a copy of 238the result into space obtained from sqlite3_malloc() 239before it returns. 240.Pp 241The sqlite3_result_value() interface sets the result of the application-defined 242function to be a copy of the unprotected sqlite3_value 243object specified by the 2nd parameter. 244The sqlite3_result_value() interface makes a copy of the sqlite3_value 245so that the sqlite3_value specified in the parameter may 246change or be deallocated after sqlite3_result_value() returns without 247harm. 248A protected sqlite3_value object may always 249be used where an unprotected sqlite3_value 250object is required, so either kind of sqlite3_value object 251can be used with this interface. 252.Pp 253The sqlite3_result_pointer(C,P,T,D) interface sets the result to an 254SQL NULL value, just like sqlite3_result_null(C), 255except that it also associates the host-language pointer P or type 256T with that NULL value such that the pointer can be retrieved within 257an application-defined SQL function 258using sqlite3_value_pointer(). 259If the D parameter is not NULL, then it is a pointer to a destructor 260for the P parameter. 261SQLite invokes D with P as its only argument when SQLite is finished 262with P. 263The T parameter should be a static string and preferably a string literal. 264The sqlite3_result_pointer() routine is part of the pointer passing interface 265added for SQLite 3.20.0. 266.Pp 267If these routines are called from within the different thread than 268the one containing the application-defined function that received the 269sqlite3_context pointer, the results are undefined. 270.Sh SEE ALSO 271.Xr sqlite3_create_function 3 , 272.Xr sqlite3_bind_blob 3 , 273.Xr sqlite3_value 3 , 274.Xr sqlite3_bind_blob 3 , 275.Xr sqlite3_context 3 , 276.Xr sqlite3_create_function 3 , 277.Xr sqlite3_malloc 3 , 278.Xr sqlite3_value 3 , 279.Xr sqlite3_value_blob 3 , 280.Xr SQLITE_UTF8 3 , 281.Xr sqlite3_value 3 282