Updated: 2022/Sep/29
Please read Privacy Policy. It's for your privacy.
SQLITE_CONFIG_SINGLETHREAD(3) Library Functions Manual
NAME
SQLITE_CONFIG_SINGLETHREAD, SQLITE_CONFIG_MULTITHREAD,
SQLITE_CONFIG_SERIALIZED, SQLITE_CONFIG_MALLOC, SQLITE_CONFIG_GETMALLOC,
SQLITE_CONFIG_SCRATCH, SQLITE_CONFIG_PAGECACHE, SQLITE_CONFIG_HEAP,
SQLITE_CONFIG_MEMSTATUS, SQLITE_CONFIG_MUTEX, SQLITE_CONFIG_GETMUTEX,
SQLITE_CONFIG_LOOKASIDE, SQLITE_CONFIG_PCACHE, SQLITE_CONFIG_GETPCACHE,
SQLITE_CONFIG_LOG, SQLITE_CONFIG_URI, SQLITE_CONFIG_PCACHE2,
SQLITE_CONFIG_GETPCACHE2, SQLITE_CONFIG_COVERING_INDEX_SCAN,
SQLITE_CONFIG_SQLLOG, SQLITE_CONFIG_MMAP_SIZE,
SQLITE_CONFIG_WIN32_HEAPSIZE, SQLITE_CONFIG_PCACHE_HDRSZ,
SQLITE_CONFIG_PMASZ, SQLITE_CONFIG_STMTJRNL_SPILL,
SQLITE_CONFIG_SMALL_MALLOC, SQLITE_CONFIG_SORTERREF_SIZE,
SQLITE_CONFIG_MEMDB_MAXSIZE - configuration options
SYNOPSIS
#include <sqlite3.h>
#define SQLITE_CONFIG_SINGLETHREAD
#define SQLITE_CONFIG_MULTITHREAD
#define SQLITE_CONFIG_SERIALIZED
#define SQLITE_CONFIG_MALLOC
#define SQLITE_CONFIG_GETMALLOC
#define SQLITE_CONFIG_SCRATCH
#define SQLITE_CONFIG_PAGECACHE
#define SQLITE_CONFIG_HEAP
#define SQLITE_CONFIG_MEMSTATUS
#define SQLITE_CONFIG_MUTEX
#define SQLITE_CONFIG_GETMUTEX
#define SQLITE_CONFIG_LOOKASIDE
#define SQLITE_CONFIG_PCACHE
#define SQLITE_CONFIG_GETPCACHE
#define SQLITE_CONFIG_LOG
#define SQLITE_CONFIG_URI
#define SQLITE_CONFIG_PCACHE2
#define SQLITE_CONFIG_GETPCACHE2
#define SQLITE_CONFIG_COVERING_INDEX_SCAN
#define SQLITE_CONFIG_SQLLOG
#define SQLITE_CONFIG_MMAP_SIZE
#define SQLITE_CONFIG_WIN32_HEAPSIZE
#define SQLITE_CONFIG_PCACHE_HDRSZ
#define SQLITE_CONFIG_PMASZ
#define SQLITE_CONFIG_STMTJRNL_SPILL
#define SQLITE_CONFIG_SMALL_MALLOC
#define SQLITE_CONFIG_SORTERREF_SIZE
#define SQLITE_CONFIG_MEMDB_MAXSIZE
DESCRIPTION
These constants are the available integer configuration options that can
be passed as the first argument to the sqlite3_config() interface.
Most of the configuration options for sqlite3_config() will only work if
invoked prior to sqlite3_initialize() or after sqlite3_shutdown(). The
few exceptions to this rule are called "anytime configuration options".
Calling sqlite3_config() with a first argument that is not an anytime
configuration option in between calls to sqlite3_initialize() and
sqlite3_shutdown() is a no-op that returns SQLITE_MISUSE.
The set of anytime configuration options can change (by insertions and/or
deletions) from one release of SQLite to the next. As of SQLite version
3.42.0, the complete set of anytime configuration options is:
⊕ SQLITE_CONFIG_LOG
⊕ SQLITE_CONFIG_PCACHE_HDRSZ
New configuration options may be added in future releases of SQLite.
Existing configuration options might be discontinued. Applications
should check the return code from sqlite3_config() to make sure that the
call worked. The sqlite3_config() interface will return a non-zero error
code if a discontinued or unsupported configuration option is invoked.
SQLITE_CONFIG_SINGLETHREAD
There are no arguments to this option. This option sets the
threading mode to Single-thread. In other words, it disables all
mutexing and puts SQLite into a mode where it can only be used by
a single thread. If SQLite is compiled with the
SQLITE_THREADSAFE=0 compile-time option then it is not possible
to change the threading mode from its default value of Single-
thread and so sqlite3_config() will return SQLITE_ERROR if called
with the SQLITE_CONFIG_SINGLETHREAD configuration option.
SQLITE_CONFIG_MULTITHREAD
There are no arguments to this option. This option sets the
threading mode to Multi-thread. In other words, it disables
mutexing on database connection and prepared statement objects.
The application is responsible for serializing access to database
connections and prepared statements. But other mutexes are
enabled so that SQLite will be safe to use in a multi-threaded
environment as long as no two threads attempt to use the same
database connection at the same time. If SQLite is compiled with
the SQLITE_THREADSAFE=0 compile-time option then it is not
possible to set the Multi-thread threading mode and
sqlite3_config() will return SQLITE_ERROR if called with the
SQLITE_CONFIG_MULTITHREAD configuration option.
SQLITE_CONFIG_SERIALIZED
There are no arguments to this option. This option sets the
threading mode to Serialized. In other words, this option
enables all mutexes including the recursive mutexes on database
connection and prepared statement objects. In this mode (which
is the default when SQLite is compiled with SQLITE_THREADSAFE=1)
the SQLite library will itself serialize access to database
connections and prepared statements so that the application is
free to use the same database connection or the same prepared
statement in different threads at the same time. If SQLite is
compiled with the SQLITE_THREADSAFE=0 compile-time option then it
is not possible to set the Serialized threading mode and
sqlite3_config() will return SQLITE_ERROR if called with the
SQLITE_CONFIG_SERIALIZED configuration option.
SQLITE_CONFIG_MALLOC
The SQLITE_CONFIG_MALLOC option takes a single argument which is
a pointer to an instance of the sqlite3_mem_methods structure.
The argument specifies alternative low-level memory allocation
routines to be used in place of the memory allocation routines
built into SQLite. SQLite makes its own private copy of the
content of the sqlite3_mem_methods structure before the
sqlite3_config() call returns.
SQLITE_CONFIG_GETMALLOC
The SQLITE_CONFIG_GETMALLOC option takes a single argument which
is a pointer to an instance of the sqlite3_mem_methods structure.
The sqlite3_mem_methods structure is filled with the currently
defined memory allocation routines. This option can be used to
overload the default memory allocation routines with a wrapper
that simulations memory allocation failure or tracks memory
usage, for example.
SQLITE_CONFIG_SMALL_MALLOC
The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of
type int, interpreted as a boolean, which if true provides a hint
to SQLite that it should avoid large memory allocations if
possible. SQLite will run faster if it is free to make large
memory allocations, but some application might prefer to run
slower in exchange for guarantees about memory fragmentation that
are possible if large allocations are avoided. This hint is
normally off.
SQLITE_CONFIG_MEMSTATUS
The SQLITE_CONFIG_MEMSTATUS option takes single argument of type
int, interpreted as a boolean, which enables or disables the
collection of memory allocation statistics. When memory
allocation statistics are disabled, the following SQLite
interfaces become non-operational:
⊕ sqlite3_hard_heap_limit64()
⊕ sqlite3_memory_used()
⊕ sqlite3_memory_highwater()
⊕ sqlite3_soft_heap_limit64()
⊕ sqlite3_status64()
Memory allocation statistics are enabled by default unless SQLite
is compiled with SQLITE_DEFAULT_MEMSTATUS=0 in which case memory
allocation statistics are disabled by default.
SQLITE_CONFIG_SCRATCH
The SQLITE_CONFIG_SCRATCH option is no longer used.
SQLITE_CONFIG_PAGECACHE
The SQLITE_CONFIG_PAGECACHE option specifies a memory pool that
SQLite can use for the database page cache with the default page
cache implementation. This configuration option is a no-op if an
application-defined page cache implementation is loaded using the
SQLITE_CONFIG_PCACHE2. There are three arguments to
SQLITE_CONFIG_PAGECACHE: A pointer to 8-byte aligned memory
(pMem), the size of each page cache line (sz), and the number of
cache lines (N). The sz argument should be the size of the
largest database page (a power of two between 512 and 65536) plus
some extra bytes for each page header. The number of extra bytes
needed by the page header can be determined using
SQLITE_CONFIG_PCACHE_HDRSZ. It is harmless, apart from the
wasted memory, for the sz parameter to be larger than necessary.
The pMem argument must be either a NULL pointer or a pointer to
an 8-byte aligned block of memory of at least sz*N bytes,
otherwise subsequent behavior is undefined. When pMem is not
NULL, SQLite will strive to use the memory provided to satisfy
page cache needs, falling back to sqlite3_malloc() if a page
cache line is larger than sz bytes or if all of the pMem buffer
is exhausted. If pMem is NULL and N is non-zero, then each
database connection does an initial bulk allocation for page
cache memory from sqlite3_malloc() sufficient for N cache lines
if N is positive or of -1024*N bytes if N is negative, . If
additional page cache memory is needed beyond what is provided by
the initial allocation, then SQLite goes to sqlite3_malloc()
separately for each additional cache line.
SQLITE_CONFIG_HEAP
The SQLITE_CONFIG_HEAP option specifies a static memory buffer
that SQLite will use for all of its dynamic memory allocation
needs beyond those provided for by SQLITE_CONFIG_PAGECACHE. The
SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
with either SQLITE_ENABLE_MEMSYS3 or SQLITE_ENABLE_MEMSYS5 and
returns SQLITE_ERROR if invoked otherwise. There are three
arguments to SQLITE_CONFIG_HEAP: An 8-byte aligned pointer to the
memory, the number of bytes in the memory buffer, and the minimum
allocation size. If the first pointer (the memory pointer) is
NULL, then SQLite reverts to using its default memory allocator
(the system malloc() implementation), undoing any prior
invocation of SQLITE_CONFIG_MALLOC. If the memory pointer is not
NULL then the alternative memory allocator is engaged to handle
all of SQLites memory allocation needs. The first pointer (the
memory pointer) must be aligned to an 8-byte boundary or
subsequent behavior of SQLite will be undefined. The minimum
allocation size is capped at 2**12. Reasonable values for the
minimum allocation size are 2**5 through 2**8.
SQLITE_CONFIG_MUTEX
The SQLITE_CONFIG_MUTEX option takes a single argument which is a
pointer to an instance of the sqlite3_mutex_methods structure.
The argument specifies alternative low-level mutex routines to be
used in place the mutex routines built into SQLite. SQLite makes
a copy of the content of the sqlite3_mutex_methods structure
before the call to sqlite3_config() returns. If SQLite is
compiled with the SQLITE_THREADSAFE=0 compile-time option then
the entire mutexing subsystem is omitted from the build and hence
calls to sqlite3_config() with the SQLITE_CONFIG_MUTEX
configuration option will return SQLITE_ERROR.
SQLITE_CONFIG_GETMUTEX
The SQLITE_CONFIG_GETMUTEX option takes a single argument which
is a pointer to an instance of the sqlite3_mutex_methods
structure. The sqlite3_mutex_methods structure is filled with
the currently defined mutex routines. This option can be used to
overload the default mutex allocation routines with a wrapper
used to track mutex usage for performance profiling or testing,
for example. If SQLite is compiled with the SQLITE_THREADSAFE=0
compile-time option then the entire mutexing subsystem is omitted
from the build and hence calls to sqlite3_config() with the
SQLITE_CONFIG_GETMUTEX configuration option will return
SQLITE_ERROR.
SQLITE_CONFIG_LOOKASIDE
The SQLITE_CONFIG_LOOKASIDE option takes two arguments that
determine the default size of lookaside memory on each database
connection. The first argument is the size of each lookaside
buffer slot and the second is the number of slots allocated to
each database connection. SQLITE_CONFIG_LOOKASIDE sets the
default lookaside size. The SQLITE_DBCONFIG_LOOKASIDE option to
sqlite3_db_config() can be used to change the lookaside
configuration on individual connections.
SQLITE_CONFIG_PCACHE2
The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
a pointer to an sqlite3_pcache_methods2 object. This object
specifies the interface to a custom page cache implementation.
SQLite makes a copy of the sqlite3_pcache_methods2 object.
SQLITE_CONFIG_GETPCACHE2
The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
is a pointer to an sqlite3_pcache_methods2 object. SQLite copies
of the current page cache implementation into that object.
SQLITE_CONFIG_LOG
The SQLITE_CONFIG_LOG option is used to configure the SQLite
global error log. (The SQLITE_CONFIG_LOG option takes two
arguments: a pointer to a function with a call signature of
void(*)(void*,int,const char*), and a pointer to void. If the
function pointer is not NULL, it is invoked by sqlite3_log() to
process each logging event. If the function pointer is NULL, the
sqlite3_log() interface becomes a no-op. The void pointer that
is the second argument to SQLITE_CONFIG_LOG is passed through as
the first parameter to the application-defined logger function
whenever that function is invoked. The second parameter to the
logger function is a copy of the first parameter to the
corresponding sqlite3_log() call and is intended to be a result
code or an extended result code. The third parameter passed to
the logger is log message after formatting via
sqlite3_snprintf(). The SQLite logging interface is not
reentrant; the logger function supplied by the application must
not invoke any SQLite interface. In a multi-threaded
application, the application-defined logger function must be
threadsafe.
SQLITE_CONFIG_URI
The SQLITE_CONFIG_URI option takes a single argument of type int.
If non-zero, then URI handling is globally enabled. If the
parameter is zero, then URI handling is globally disabled. If
URI handling is globally enabled, all filenames passed to
sqlite3_open(), sqlite3_open_v2(), sqlite3_open16() or specified
as part of ATTACH commands are interpreted as URIs, regardless of
whether or not the SQLITE_OPEN_URI flag is set when the database
connection is opened. If it is globally disabled, filenames are
only interpreted as URIs if the SQLITE_OPEN_URI flag is set when
the database connection is opened. By default, URI handling is
globally disabled. The default value may be changed by compiling
with the SQLITE_USE_URI symbol defined.
SQLITE_CONFIG_COVERING_INDEX_SCAN
The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single
integer argument which is interpreted as a boolean in order to
enable or disable the use of covering indices for full table
scans in the query optimizer. The default setting is determined
by the SQLITE_ALLOW_COVERING_INDEX_SCAN compile-time option, or
is "on" if that compile-time option is omitted. The ability to
disable the use of covering indices for full table scans is
because some incorrectly coded legacy applications might
malfunction when the optimization is enabled. Providing the
ability to disable the optimization allows the older, buggy
application code to work without change even with newer versions
of SQLite.
SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
These options are obsolete and should not be used by new code.
They are retained for backwards compatibility but are now no-ops.
SQLITE_CONFIG_SQLLOG
This option is only available if sqlite is compiled with the
SQLITE_ENABLE_SQLLOG pre-processor macro defined. The first
argument should be a pointer to a function of type
void(*)(void*,sqlite3*,const char*, int). The second should be
of type (void*). The callback is invoked by the library in three
separate circumstances, identified by the value passed as the
fourth parameter. If the fourth parameter is 0, then the
database connection passed as the second argument has just been
opened. The third argument points to a buffer containing the
name of the main database file. If the fourth parameter is 1,
then the SQL statement that the third parameter points to has
just been executed. Or, if the fourth parameter is 2, then the
connection being passed as the second parameter is being closed.
The third parameter is passed NULL In this case. An example of
using this configuration option can be seen in the
"test_sqllog.c" source file in the canonical SQLite source tree.
SQLITE_CONFIG_MMAP_SIZE
SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64)
values that are the default mmap size limit (the default setting
for PRAGMA mmap_size) and the maximum allowed mmap size limit.
The default setting can be overridden by each database connection
using either the PRAGMA mmap_size command, or by using the
SQLITE_FCNTL_MMAP_SIZE file control. The maximum allowed mmap
size will be silently truncated if necessary so that it does not
exceed the compile-time maximum mmap size set by the
SQLITE_MAX_MMAP_SIZE compile-time option. If either argument to
this option is negative, then that argument is changed to its
compile-time default.
SQLITE_CONFIG_WIN32_HEAPSIZE
The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if
SQLite is compiled for Windows with the SQLITE_WIN32_MALLOC pre-
processor macro defined. SQLITE_CONFIG_WIN32_HEAPSIZE takes a
32-bit unsigned integer value that specifies the maximum size of
the created heap.
SQLITE_CONFIG_PCACHE_HDRSZ
The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter
which is a pointer to an integer and writes into that integer the
number of extra bytes per page required for each page in
SQLITE_CONFIG_PAGECACHE. The amount of extra space required can
change depending on the compiler, target platform, and SQLite
version.
SQLITE_CONFIG_PMASZ
The SQLITE_CONFIG_PMASZ option takes a single parameter which is
an unsigned integer and sets the "Minimum PMA Size" for the
multithreaded sorter to that integer. The default minimum PMA
Size is set by the SQLITE_SORTER_PMASZ compile-time option. New
threads are launched to help with sort operations when
multithreaded sorting is enabled (using the PRAGMA threads
command) and the amount of content to be sorted exceeds the page
size times the minimum of the PRAGMA cache_size setting and this
value.
SQLITE_CONFIG_STMTJRNL_SPILL
The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter
which becomes the statement journal spill-to-disk threshold.
Statement journals are held in memory until their size (in bytes)
exceeds this threshold, at which point they are written to disk.
Or if the threshold is -1, statement journals are always held
exclusively in memory. Since many statement journals never
become large, setting the spill threshold to a value such as
64KiB can greatly reduce the amount of I/O required to support
statement rollback. The default value for this setting is
controlled by the SQLITE_STMTJRNL_SPILL compile-time option.
SQLITE_CONFIG_SORTERREF_SIZE
The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single
parameter of type (int) - the new value of the sorter-reference
size threshold. Usually, when SQLite uses an external sort to
order records according to an ORDER BY clause, all fields
required by the caller are present in the sorted records.
However, if SQLite determines based on the declared type of a
table column that its values are likely to be very large - larger
than the configured sorter-reference size threshold - then a
reference is stored in each sorted record and the required column
values loaded from the database as records are returned in sorted
order. The default value for this option is to never use this
optimization. Specifying a negative value for this option
restores the default behaviour. This option is only available if
SQLite is compiled with the SQLITE_ENABLE_SORTER_REFERENCES
compile-time option.
SQLITE_CONFIG_MEMDB_MAXSIZE
The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter
sqlite3_int64 parameter which is the default maximum size for an
in-memory database created using sqlite3_deserialize(). This
default maximum size can be adjusted up or down for individual
databases using the SQLITE_FCNTL_SIZE_LIMIT file-control. If
this configuration setting is never used, then the default
maximum is determined by the SQLITE_MEMDB_DEFAULT_MAXSIZE
compile-time option. If that compile-time option is not set,
then the default maximum is 1073741824.
IMPLEMENTATION NOTES
These declarations were extracted from the interface documentation at
line 1777.
#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
#define SQLITE_CONFIG_SERIALIZED 3 /* nil */
#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
#define SQLITE_CONFIG_SCRATCH 6 /* No longer used */
#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
#define SQLITE_CONFIG_PCACHE 14 /* no-op */
#define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
#define SQLITE_CONFIG_URI 17 /* int */
#define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */
#define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */
#define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
#define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
#define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
#define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */
#define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
#define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */
#define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */
#define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */
#define SQLITE_CONFIG_MEMDB_MAXSIZE 29 /* sqlite3_int64 */
SEE ALSO
sqlite3(3), sqlite3_config(3), sqlite3_db_config(3),
sqlite3_deserialize(3), sqlite3_file_control(3), sqlite3_initialize(3),
sqlite3_log(3), sqlite3_malloc(3), sqlite3_mem_methods(3),
sqlite3_memory_used(3), sqlite3_mprintf(3), sqlite3_mutex_methods(3),
sqlite3_open(3), sqlite3_pcache_methods2(3),
sqlite3_soft_heap_limit64(3), sqlite3_status(3), sqlite3_stmt(3),
SQLITE_DBCONFIG_MAINDBNAME(3), SQLITE_FCNTL_LOCKSTATE(3),
sqlite_int64(3), SQLITE_OK(3), SQLITE_OPEN_READONLY(3)
NetBSD 10.99 August 24, 2023 NetBSD 10.99