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