sqlite3_initialize(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
SQLITE3_INITIALIZE(3)   NetBSD Library Functions Manual  SQLITE3_INITIALIZE(3)


NAME

     sqlite3_initialize, sqlite3_shutdown, sqlite3_os_init, sqlite3_os_end --
     initialize the SQLite library


SYNOPSIS

     #include <sqlite3.h>

     int
     sqlite3_initialize(void);

     int
     sqlite3_shutdown(void);

     int
     sqlite3_os_init(void);

     int
     sqlite3_os_end(void);


DESCRIPTION

     The sqlite3_initialize() routine initializes the SQLite library.  The
     sqlite3_shutdown() routine deallocates any resources that were allocated
     by sqlite3_initialize().  These routines are designed to aid in process
     initialization and shutdown on embedded systems.  Workstation applica-
     tions using SQLite normally do not need to invoke either of these rou-
     tines.

     A call to sqlite3_initialize() is an "effective" call if it is the first
     time sqlite3_initialize() is invoked during the lifetime of the process,
     or if it is the first time sqlite3_initialize() is invoked following a
     call to sqlite3_shutdown().  Only an effective call of sqlite3_initial-
     ize() does any initialization.  All other calls are harmless no-ops.

     A call to sqlite3_shutdown() is an "effective" call if it is the first
     call to sqlite3_shutdown() since the last sqlite3_initialize().  Only an
     effective call to sqlite3_shutdown() does any deinitialization.  All
     other valid calls to sqlite3_shutdown() are harmless no-ops.

     The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
     is not.  The sqlite3_shutdown() interface must only be called from a sin-
     gle thread.  All open database connections must be closed and all other
     SQLite resources must be deallocated prior to invoking sqlite3_shut-
     down().

     Among other things, sqlite3_initialize() will invoke sqlite3_os_init().
     Similarly, sqlite3_shutdown() will invoke sqlite3_os_end().

     The sqlite3_initialize() routine returns SQLITE_OK on success.  If for
     some reason, sqlite3_initialize() is unable to initialize the library
     (perhaps it is unable to allocate a needed resource such as a mutex) it
     returns an error code other than SQLITE_OK.

     The sqlite3_initialize() routine is called internally by many other
     SQLite interfaces so that an application usually does not need to invoke
     sqlite3_initialize() directly.  For example, sqlite3_open() calls
     sqlite3_initialize() so the SQLite library will be automatically initial-
     ized when sqlite3_open() is called if it has not be initialized already.
     However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT compile-time
     option, then the automatic calls to sqlite3_initialize() are omitted and
     the application must call sqlite3_initialize() directly prior to using
     any other SQLite interface.  For maximum portability, it is recommended
     that applications always invoke sqlite3_initialize() directly prior to
     using any other SQLite interface.  Future releases of SQLite may require
     this.  In other words, the behavior exhibited when SQLite is compiled
     with SQLITE_OMIT_AUTOINIT might become the default behavior in some
     future release of SQLite.

     The sqlite3_os_init() routine does operating-system specific initializa-
     tion of the SQLite library.  The sqlite3_os_end() routine undoes the
     effect of sqlite3_os_init().  Typical tasks performed by these routines
     include allocation or deallocation of static resources, initialization of
     global variables, setting up a default sqlite3_vfs module, or setting up
     a default configuration using sqlite3_config().  The application should
     never invoke either sqlite3_os_init() or sqlite3_os_end() directly.  The
     application should only invoke sqlite3_initialize() and sqlite3_shut-
     down().  The sqlite3_os_init() interface is called automatically by
     sqlite3_initialize() and sqlite3_os_end() is called by sqlite3_shut-
     down().  Appropriate implementations for sqlite3_os_init() and
     sqlite3_os_end() are built into SQLite when it is compiled for Unix, Win-
     dows, or OS/2.  When built for other platforms (using the
     SQLITE_OS_OTHER=1 compile-time option) the application must supply a
     suitable implementation for sqlite3_os_init() and sqlite3_os_end().  An
     application-supplied implementation of sqlite3_os_init() or
     sqlite3_os_end() must return SQLITE_OK on success and some other error
     code upon failure.


IMPLEMENTATION NOTES

     These declarations were extracted from the interface documentation at
     line 1567.

     SQLITE_API int sqlite3_initialize(void);
     SQLITE_API int sqlite3_shutdown(void);
     SQLITE_API int sqlite3_os_init(void);
     SQLITE_API int sqlite3_os_end(void);


SEE ALSO

     sqlite3(3), sqlite3_config(3), sqlite3_open(3), sqlite3_vfs(3),
     SQLITE_OK(3)

NetBSD 10.99                   January 24, 2024                   NetBSD 10.99