.Dd April 29, 2026
.Dt SQLITE3_RESULT_BLOB 3
.Os
.Sh NAME
.Nm sqlite3_result_blob ,
.Nm sqlite3_result_blob64 ,
.Nm sqlite3_result_double ,
.Nm sqlite3_result_error ,
.Nm sqlite3_result_error16 ,
.Nm sqlite3_result_error_toobig ,
.Nm sqlite3_result_error_nomem ,
.Nm sqlite3_result_error_code ,
.Nm sqlite3_result_int ,
.Nm sqlite3_result_int64 ,
.Nm sqlite3_result_null ,
.Nm sqlite3_result_text ,
.Nm sqlite3_result_text64 ,
.Nm sqlite3_result_text16 ,
.Nm sqlite3_result_text16le ,
.Nm sqlite3_result_text16be ,
.Nm sqlite3_result_value ,
.Nm sqlite3_result_pointer ,
.Nm sqlite3_result_zeroblob ,
.Nm sqlite3_result_zeroblob64
.Nd setting the result of an SQL function
.Sh SYNOPSIS
.In sqlite3.h
.Ft void
.Fo sqlite3_result_blob
.Fa "sqlite3_context*"
.Fa "const void*"
.Fa "int"
.Fa "void(*)(void*)"
.Fc
.Ft void
.Fo sqlite3_result_blob64
.Fa "sqlite3_context*"
.Fa "const void*"
.Fa "sqlite3_uint64"
.Fa "void(*)(void*)"
.Fc
.Ft void
.Fo sqlite3_result_double
.Fa "sqlite3_context*"
.Fa "double"
.Fc
.Ft void
.Fo sqlite3_result_error
.Fa "sqlite3_context*"
.Fa "const char*"
.Fa "int"
.Fc
.Ft void
.Fo sqlite3_result_error16
.Fa "sqlite3_context*"
.Fa "const void*"
.Fa "int"
.Fc
.Ft void
.Fo sqlite3_result_error_toobig
.Fa "sqlite3_context*"
.Fc
.Ft void
.Fo sqlite3_result_error_nomem
.Fa "sqlite3_context*"
.Fc
.Ft void
.Fo sqlite3_result_error_code
.Fa "sqlite3_context*"
.Fa "int"
.Fc
.Ft void
.Fo sqlite3_result_int
.Fa "sqlite3_context*"
.Fa "int"
.Fc
.Ft void
.Fo sqlite3_result_int64
.Fa "sqlite3_context*"
.Fa "sqlite3_int64"
.Fc
.Ft void
.Fo sqlite3_result_null
.Fa "sqlite3_context*"
.Fc
.Ft void
.Fo sqlite3_result_text
.Fa "sqlite3_context*"
.Fa "const char*"
.Fa "int"
.Fa "void(*)(void*)"
.Fc
.Ft void
.Fo sqlite3_result_text64
.Fa "sqlite3_context*"
.Fa "const char *z"
.Fa "sqlite3_uint64 n"
.Fa "void(*)(void*)"
.Fa "unsigned char encoding"
.Fc
.Ft void
.Fo sqlite3_result_text16
.Fa "sqlite3_context*"
.Fa "const void*"
.Fa "int"
.Fa "void(*)(void*)"
.Fc
.Ft void
.Fo sqlite3_result_text16le
.Fa "sqlite3_context*"
.Fa "const void*"
.Fa "int"
.Fa "void(*)(void*)"
.Fc
.Ft void
.Fo sqlite3_result_text16be
.Fa "sqlite3_context*"
.Fa "const void*"
.Fa "int"
.Fa "void(*)(void*)"
.Fc
.Ft void
.Fo sqlite3_result_value
.Fa "sqlite3_context*"
.Fa "sqlite3_value*"
.Fc
.Ft void
.Fo sqlite3_result_pointer
.Fa "sqlite3_context*"
.Fa "void*"
.Fa "const char*"
.Fa "void(*)(void*)"
.Fc
.Ft void
.Fo sqlite3_result_zeroblob
.Fa "sqlite3_context*"
.Fa "int n"
.Fc
.Ft int
.Fo sqlite3_result_zeroblob64
.Fa "sqlite3_context*"
.Fa "sqlite3_uint64 n"
.Fc
.Sh DESCRIPTION
These routines are used by the xFunc or xFinal callbacks that implement
SQL functions and aggregates.
See
.Fn sqlite3_create_function
and
.Fn sqlite3_create_function16
for additional information.
.Pp
These functions work very much like the parameter binding
family of functions used to bind values to host parameters in prepared
statements.
Refer to the SQL parameter documentation for additional
information.
.Pp
The sqlite3_result_blob() interface sets the result from an application-defined
function to be the BLOB whose content is pointed to by the second parameter
and which is N bytes long where N is the third parameter.
.Pp
The sqlite3_result_zeroblob(C,N) and sqlite3_result_zeroblob64(C,N)
interfaces set the result of the application-defined function to be
a BLOB containing all zero bytes and N bytes in size.
.Pp
The sqlite3_result_double() interface sets the result from an application-defined
function to be a floating point value specified by its 2nd argument.
.Pp
The sqlite3_result_error() and sqlite3_result_error16() functions cause
the implemented SQL function to throw an exception.
SQLite uses the string pointed to by the 2nd parameter of sqlite3_result_error()
or sqlite3_result_error16() as the text of an error message.
SQLite interprets the error message string from sqlite3_result_error()
as UTF-8.
SQLite interprets the string from sqlite3_result_error16() as UTF-16
using the same byte-order determination rules
as
.Fn sqlite3_bind_text16 .
If the third parameter to sqlite3_result_error() or sqlite3_result_error16()
is negative then SQLite takes as the error message all text up through
the first zero character.
If the third parameter to sqlite3_result_error() or sqlite3_result_error16()
is non-negative then SQLite takes that many bytes (not characters)
from the 2nd parameter as the error message.
The sqlite3_result_error() and sqlite3_result_error16() routines make
a private copy of the error message text before they return.
Hence, the calling function can deallocate or modify the text after
they return without harm.
The sqlite3_result_error_code() function changes the error code returned
by SQLite as a result of an error in a function.
By default, the error code is SQLITE_ERROR.
A subsequent call to sqlite3_result_error() or sqlite3_result_error16()
resets the error code to SQLITE_ERROR.
.Pp
The sqlite3_result_error_toobig() interface causes SQLite to throw
an error indicating that a string or BLOB is too long to represent.
.Pp
The sqlite3_result_error_nomem() interface causes SQLite to throw an
error indicating that a memory allocation failed.
.Pp
The sqlite3_result_int() interface sets the return value of the application-defined
function to be the 32-bit signed integer value given in the 2nd argument.
The sqlite3_result_int64() interface sets the return value of the application-defined
function to be the 64-bit signed integer value given in the 2nd argument.
.Pp
The sqlite3_result_null() interface sets the return value of the application-defined
function to be NULL.
.Pp
The sqlite3_result_text(), sqlite3_result_text16(), sqlite3_result_text16le(),
and sqlite3_result_text16be() interfaces set the return value of the
application-defined function to be a text string which is represented
as UTF-8, UTF-16 native byte order, UTF-16 little endian, or UTF-16
big endian, respectively.
The sqlite3_result_text64(C,Z,N,D,E) interface sets the return value
of an application-defined function to be a text string in an encoding
specified the E parameter, which must be one of SQLITE_UTF8,
SQLITE_UTF8_ZT, SQLITE_UTF16, SQLITE_UTF16BE,
or SQLITE_UTF16LE.
The special value SQLITE_UTF8_ZT means that the result
text is both UTF-8 and zero-terminated.
In other words, SQLITE_UTF8_ZT means that the Z array holds at least
N+1 bytes and that the Z[N] is zero.
SQLite takes the text result from the application from the 2nd parameter
of the sqlite3_result_text* interfaces.
If the 3rd parameter to any of the sqlite3_result_text* interfaces
other than sqlite3_result_text64() is negative, then SQLite computes
the string length itself by searching the 2nd parameter for the first
zero character.
If the 3rd parameter to the sqlite3_result_text* interfaces is non-negative,
then as many bytes (not characters) of the text pointed to by the 2nd
parameter are taken as the application-defined function result.
If the 3rd parameter is non-negative, then it must be the byte offset
into the string where the NUL terminator would appear if the string
were NUL terminated.
If any NUL characters occur in the string at a byte offset that is
less than the value of the 3rd parameter, then the resulting string
will contain embedded NULs and the result of expressions operating
on strings with embedded NULs is undefined.
If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob
is a non-NULL pointer, then SQLite calls that function as the destructor
on the text or BLOB result when it has finished using that result.
If the 4th parameter to the sqlite3_result_text* interfaces or to sqlite3_result_blob
is the special constant SQLITE_STATIC, then SQLite assumes that the
text or BLOB result is in constant space and does not copy the content
of the parameter nor call a destructor on the content when it has finished
using that result.
If the 4th parameter to the sqlite3_result_text* interfaces or sqlite3_result_blob
is the special constant SQLITE_TRANSIENT then SQLite makes a copy of
the result into space obtained from
.Fn sqlite3_malloc
before it returns.
.Pp
For the sqlite3_result_text16(), sqlite3_result_text16le(), and sqlite3_result_text16be()
routines, and for sqlite3_result_text64() when the encoding is not
UTF8, if the input UTF16 begins with a byte-order mark (BOM, U+FEFF)
then the BOM is removed from the string and the rest of the string
is interpreted according to the byte-order specified by the BOM.
The byte-order specified by the BOM at the beginning of the text overrides
the byte-order specified by the interface procedure.
So, for example, if sqlite3_result_text16le() is invoked with text
that begins with bytes 0xfe, 0xff (a big-endian byte-order mark) then
the first two bytes of input are skipped and the remaining input is
interpreted as UTF16BE text.
.Pp
For UTF16 input text to the sqlite3_result_text16(), sqlite3_result_text16be(),
sqlite3_result_text16le(), and sqlite3_result_text64() routines, if
the text contains invalid UTF16 characters, the invalid characters
might be converted into the unicode replacement character, U+FFFD.
.Pp
The sqlite3_result_value() interface sets the result of the application-defined
function to be a copy of the unprotected sqlite3_value
object specified by the 2nd parameter.
The sqlite3_result_value() interface makes a copy of the sqlite3_value
so that the sqlite3_value specified in the parameter may
change or be deallocated after sqlite3_result_value() returns without
harm.
A protected sqlite3_value object may always
be used where an unprotected sqlite3_value
object is required, so either kind of sqlite3_value object
can be used with this interface.
.Pp
The sqlite3_result_pointer(C,P,T,D) interface sets the result to an
SQL NULL value, just like sqlite3_result_null(C),
except that it also associates the host-language pointer P or type
T with that NULL value such that the pointer can be retrieved within
an application-defined SQL function
using
.Fn sqlite3_value_pointer .
If the D parameter is not NULL, then it is a pointer to a destructor
for the P parameter.
SQLite invokes D with P as its only argument when SQLite is finished
with P.
The T parameter should be a static string and preferably a string literal.
The sqlite3_result_pointer() routine is part of the pointer passing interface
added for SQLite 3.20.0.
.Pp
If these routines are called from within a different thread than the
one containing the application-defined function that received the sqlite3_context
pointer, the results are undefined.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 6431.
.Bd -literal
SQLITE_API void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
SQLITE_API void sqlite3_result_blob64(sqlite3_context*,const void*,
                           sqlite3_uint64,void(*)(void*));
SQLITE_API void sqlite3_result_double(sqlite3_context*, double);
SQLITE_API void sqlite3_result_error(sqlite3_context*, const char*, int);
SQLITE_API void sqlite3_result_error16(sqlite3_context*, const void*, int);
SQLITE_API void sqlite3_result_error_toobig(sqlite3_context*);
SQLITE_API void sqlite3_result_error_nomem(sqlite3_context*);
SQLITE_API void sqlite3_result_error_code(sqlite3_context*, int);
SQLITE_API void sqlite3_result_int(sqlite3_context*, int);
SQLITE_API void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
SQLITE_API void sqlite3_result_null(sqlite3_context*);
SQLITE_API void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
SQLITE_API void sqlite3_result_text64(sqlite3_context*, const char *z, sqlite3_uint64 n,
                           void(*)(void*), unsigned char encoding);
SQLITE_API void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
SQLITE_API void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
SQLITE_API void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
SQLITE_API void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
SQLITE_API void sqlite3_result_pointer(sqlite3_context*, void*,const char*,void(*)(void*));
SQLITE_API void sqlite3_result_zeroblob(sqlite3_context*, int n);
SQLITE_API int sqlite3_result_zeroblob64(sqlite3_context*, sqlite3_uint64 n);
.Ed
.Sh SEE ALSO
.Xr sqlite3_bind_blob 3 ,
.Xr sqlite3_context 3 ,
.Xr sqlite3_create_function 3 ,
.Xr sqlite3_malloc 3 ,
.Xr sqlite3_value 3 ,
.Xr sqlite3_value_blob 3 ,
.Xr SQLITE_UTF8 3