.Dd January 24, 2024
.Dt SQLITE3_VALUE 3
.Os
.Sh NAME
.Nm sqlite3_value
.Nd dynamically typed value object
.Sh SYNOPSIS
.In sqlite3.h
.Vt typedef struct sqlite3_value sqlite3_value;
.Sh DESCRIPTION
SQLite uses the sqlite3_value object to represent all values that can
be stored in a database table.
SQLite uses dynamic typing for the values it stores.
Values stored in sqlite3_value objects can be integers, floating point
values, strings, BLOBs, or NULL.
.Pp
An sqlite3_value object may be either "protected" or "unprotected".
Some interfaces require a protected sqlite3_value.
Other interfaces will accept either a protected or an unprotected sqlite3_value.
Every interface that accepts sqlite3_value arguments specifies whether
or not it requires a protected sqlite3_value.
The
.Fn sqlite3_value_dup
interface can be used to construct a new protected sqlite3_value from
an unprotected sqlite3_value.
.Pp
The terms "protected" and "unprotected" refer to whether or not a mutex
is held.
An internal mutex is held for a protected sqlite3_value object but
no mutex is held for an unprotected sqlite3_value object.
If SQLite is compiled to be single-threaded (with SQLITE_THREADSAFE=0
and with
.Fn sqlite3_threadsafe
returning 0) or if SQLite is run in one of reduced mutex modes SQLITE_CONFIG_SINGLETHREAD
or SQLITE_CONFIG_MULTITHREAD then there is
no distinction between protected and unprotected sqlite3_value objects
and they can be used interchangeably.
However, for maximum code portability it is recommended that applications
still make the distinction between protected and unprotected sqlite3_value
objects even when not strictly required.
.Pp
The sqlite3_value objects that are passed as parameters into the implementation
of application-defined SQL functions
are protected.
The sqlite3_value objects returned by
.Fn sqlite3_vtab_rhs_value
are protected.
The sqlite3_value object returned by
.Fn sqlite3_column_value
is unprotected.
Unprotected sqlite3_value objects may only be used as arguments to
.Fn sqlite3_result_value ,
.Fn sqlite3_bind_value ,
and
.Fn sqlite3_value_dup .
The sqlite3_value_type() family of interfaces require
protected sqlite3_value objects.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 4485.
.Bd -literal
typedef struct sqlite3_value sqlite3_value;
.Ed
.Sh SEE ALSO
.Xr sqlite3_bind_blob 3 ,
.Xr sqlite3_column_blob 3 ,
.Xr sqlite3_result_blob 3 ,
.Xr sqlite3_threadsafe 3 ,
.Xr sqlite3_value_blob 3 ,
.Xr sqlite3_value_dup 3 ,
.Xr sqlite3_vtab_rhs_value 3 ,
.Xr SQLITE_CONFIG_SINGLETHREAD 3