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 - Configuration
     Options

SYNOPSIS
     #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

DESCRIPTION
     These constants are the available integer configuration options that can
     be passed as the first argument to the sqlite3_config() interface.

     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_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-define 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
             <i>default</i> 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.

SEE ALSO
     sqlite3(3), sqlite3_stmt(3), sqlite3_config(3), sqlite3_db_config(3),
     sqlite3_log(3), sqlite3_malloc(3), sqlite3_mem_methods(3),
     sqlite3_memory_used(3), sqlite3_mutex_methods(3), sqlite3_open(3),
     sqlite3_pcache_methods2(3), sqlite3_mprintf(3),
     sqlite3_soft_heap_limit64(3), sqlite3_status(3),
     SQLITE_CONFIG_SINGLETHREAD(3), SQLITE_DBCONFIG_MAINDBNAME(3),
     SQLITE_OK(3), SQLITE_FCNTL_LOCKSTATE(3), SQLITE_OPEN_READONLY(3)

NetBSD 9.99                    December 19, 2018                   NetBSD 9.99