1.Dd $Mdocdate$ 2.Dt SQLITE3_RESULT_BLOB 3 3.Os 4.Sh NAME 5.Nm sqlite3_result_blob , 6.Nm sqlite3_result_double , 7.Nm sqlite3_result_error , 8.Nm sqlite3_result_error16 , 9.Nm sqlite3_result_error_toobig , 10.Nm sqlite3_result_error_nomem , 11.Nm sqlite3_result_error_code , 12.Nm sqlite3_result_int , 13.Nm sqlite3_result_int64 , 14.Nm sqlite3_result_null , 15.Nm sqlite3_result_text , 16.Nm sqlite3_result_text16 , 17.Nm sqlite3_result_text16le , 18.Nm sqlite3_result_text16be , 19.Nm sqlite3_result_value , 20.Nm sqlite3_result_zeroblob 21.Nd Setting The Result Of An SQL Function 22.Sh SYNOPSIS 23.Ft void 24.Fo sqlite3_result_blob 25.Fa "sqlite3_context*" 26.Fa "const void*" 27.Fa "int" 28.Fa "void(*)(void*)" 29.Fc 30.Ft void 31.Fo sqlite3_result_double 32.Fa "sqlite3_context*" 33.Fa "double" 34.Fc 35.Ft void 36.Fo sqlite3_result_error 37.Fa "sqlite3_context*" 38.Fa "const char*" 39.Fa "int" 40.Fc 41.Ft void 42.Fo sqlite3_result_error16 43.Fa "sqlite3_context*" 44.Fa "const void*" 45.Fa "int" 46.Fc 47.Ft void 48.Fo sqlite3_result_error_toobig 49.Fa "sqlite3_context*" 50.Fc 51.Ft void 52.Fo sqlite3_result_error_nomem 53.Fa "sqlite3_context*" 54.Fc 55.Ft void 56.Fo sqlite3_result_error_code 57.Fa "sqlite3_context*" 58.Fa "int" 59.Fc 60.Ft void 61.Fo sqlite3_result_int 62.Fa "sqlite3_context*" 63.Fa "int" 64.Fc 65.Ft void 66.Fo sqlite3_result_int64 67.Fa "sqlite3_context*" 68.Fa "sqlite3_int64" 69.Fc 70.Ft void 71.Fo sqlite3_result_null 72.Fa "sqlite3_context*" 73.Fc 74.Ft void 75.Fo sqlite3_result_text 76.Fa "sqlite3_context*" 77.Fa "const char*" 78.Fa "int" 79.Fa "void(*)(void*)" 80.Fc 81.Ft void 82.Fo sqlite3_result_text16 83.Fa "sqlite3_context*" 84.Fa "const void*" 85.Fa "int" 86.Fa "void(*)(void*)" 87.Fc 88.Ft void 89.Fo sqlite3_result_text16le 90.Fa "sqlite3_context*" 91.Fa "const void*" 92.Fa "int" 93.Fa "void(*)(void*)" 94.Fc 95.Ft void 96.Fo sqlite3_result_text16be 97.Fa "sqlite3_context*" 98.Fa "const void*" 99.Fa "int" 100.Fa "void(*)(void*)" 101.Fc 102.Ft void 103.Fo sqlite3_result_value 104.Fa "sqlite3_context*" 105.Fa "sqlite3_value*" 106.Fc 107.Ft void 108.Fo sqlite3_result_zeroblob 109.Fa "sqlite3_context*" 110.Fa "int n" 111.Fc 112.Sh DESCRIPTION 113These routines are used by the xFunc or xFinal callbacks that implement 114SQL functions and aggregates. 115See sqlite3_create_function() and sqlite3_create_function16() 116for additional information. 117.Pp 118These functions work very much like the parameter binding 119family of functions used to bind values to host parameters in prepared 120statements. 121Refer to the SQL parameter documentation for additional 122information. 123.Pp 124The sqlite3_result_blob() interface sets the result from an application-defined 125function to be the BLOB whose content is pointed to by the second parameter 126and which is N bytes long where N is the third parameter. 127.Pp 128The sqlite3_result_zeroblob() interfaces set the result of the application-defined 129function to be a BLOB containing all zero bytes and N bytes in size, 130where N is the value of the 2nd parameter. 131.Pp 132The sqlite3_result_double() interface sets the result from an application-defined 133function to be a floating point value specified by its 2nd argument. 134.Pp 135The sqlite3_result_error() and sqlite3_result_error16() functions cause 136the implemented SQL function to throw an exception. 137SQLite uses the string pointed to by the 2nd parameter of sqlite3_result_error() 138or sqlite3_result_error16() as the text of an error message. 139SQLite interprets the error message string from sqlite3_result_error() 140as UTF-8. 141SQLite interprets the string from sqlite3_result_error16() as UTF-16 142in native byte order. 143If the third parameter to sqlite3_result_error() or sqlite3_result_error16() 144is negative then SQLite takes as the error message all text up through 145the first zero character. 146If the third parameter to sqlite3_result_error() or sqlite3_result_error16() 147is non-negative then SQLite takes that many bytes (not characters) 148from the 2nd parameter as the error message. 149The sqlite3_result_error() and sqlite3_result_error16() routines make 150a private copy of the error message text before they return. 151Hence, the calling function can deallocate or modify the text after 152they return without harm. 153The sqlite3_result_error_code() function changes the error code returned 154by SQLite as a result of an error in a function. 155By default, the error code is SQLITE_ERROR. 156A subsequent call to sqlite3_result_error() or sqlite3_result_error16() 157resets the error code to SQLITE_ERROR. 158.Pp 159The sqlite3_result_error_toobig() interface causes SQLite to throw 160an error indicating that a string or BLOB is too long to represent. 161.Pp 162The sqlite3_result_error_nomem() interface causes SQLite to throw an 163error indicating that a memory allocation failed. 164.Pp 165The sqlite3_result_int() interface sets the return value of the application-defined 166function to be the 32-bit signed integer value given in the 2nd argument. 167The sqlite3_result_int64() interface sets the return value of the application-defined 168function to be the 64-bit signed integer value given in the 2nd argument. 169.Pp 170The sqlite3_result_null() interface sets the return value of the application-defined 171function to be NULL. 172.Pp 173The sqlite3_result_text(), sqlite3_result_text16(), sqlite3_result_text16le(), 174and sqlite3_result_text16be() interfaces set the return value of the 175application-defined function to be a text string which is represented 176as UTF-8, UTF-16 native byte order, UTF-16 little endian, or UTF-16 177big endian, respectively. 178SQLite takes the text result from the application from the 2nd parameter 179of the sqlite3_result_text* interfaces. 180If the 3rd parameter to the sqlite3_result_text* interfaces is negative, 181then SQLite takes result text from the 2nd parameter through the first 182zero character. 183If the 3rd parameter to the sqlite3_result_text* interfaces is non-negative, 184then as many bytes (not characters) of the text pointed to by the 2nd 185parameter are taken as the application-defined function result. 186If the 3rd parameter is non-negative, then it must be the byte offset 187into the string where the NUL terminator would appear if the string 188where NUL terminated. 189If any NUL characters occur in the string at a byte offset that is 190less than the value of the 3rd parameter, then the resulting string 191will contain embedded NULs and the result of expressions operating 192on strings with embedded NULs is undefined. 193If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob 194is a non-NULL pointer, then SQLite calls that function as the destructor 195on the text or BLOB result when it has finished using that result. 196If the 4th parameter to the sqlite3_result_text* interfaces or to sqlite3_result_blob 197is the special constant SQLITE_STATIC, then SQLite assumes that the 198text or BLOB result is in constant space and does not copy the content 199of the parameter nor call a destructor on the content when it has finished 200using that result. 201If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob 202is the special constant SQLITE_TRANSIENT then SQLite makes a copy of 203the result into space obtained from from sqlite3_malloc() 204before it returns. 205.Pp 206The sqlite3_result_value() interface sets the result of the application-defined 207function to be a copy the unprotected sqlite3_value 208object specified by the 2nd parameter. 209The sqlite3_result_value() interface makes a copy of the sqlite3_value 210so that the sqlite3_value specified in the parameter may 211change or be deallocated after sqlite3_result_value() returns without 212harm. 213A protected sqlite3_value object may always 214be used where an unprotected sqlite3_value 215object is required, so either kind of sqlite3_value object 216can be used with this interface. 217.Pp 218If these routines are called from within the different thread than 219the one containing the application-defined function that received the 220sqlite3_context pointer, the results are undefined. 221.Sh SEE ALSO 222.Xr sqlite3_bind_blob 3 , 223.Xr sqlite3_value 3 , 224.Xr sqlite3_bind_blob 3 , 225.Xr sqlite3_context 3 , 226.Xr sqlite3_create_function 3 , 227.Xr sqlite3_malloc 3 , 228.Xr sqlite3_value 3 229