.Dd December 19, 2018
.Dt SQLITE3_INITIALIZE 3
.Os
.Sh NAME
.Nm sqlite3_initialize ,
.Nm sqlite3_shutdown ,
.Nm sqlite3_os_init ,
.Nm sqlite3_os_end
.Nd Initialize The SQLite Library
.Sh SYNOPSIS
.Ft int 
.Fo sqlite3_initialize
.Fa "void"
.Fc
.Ft int 
.Fo sqlite3_shutdown
.Fa "void"
.Fc
.Ft int 
.Fo sqlite3_os_init
.Fa "void"
.Fc
.Ft int 
.Fo sqlite3_os_end
.Fa "void"
.Fc
.Sh 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 applications using SQLite normally do not need to invoke
either of these routines.
.Pp
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_initialize() does any initialization.
All other calls are harmless no-ops.
.Pp
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.
.Pp
The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
is not.
The sqlite3_shutdown() interface must only be called from a single
thread.
All open database connections must be closed and
all other SQLite resources must be deallocated prior to invoking sqlite3_shutdown().
.Pp
Among other things,  sqlite3_initialize() will invoke sqlite3_os_init().
Similarly,  sqlite3_shutdown() will invoke sqlite3_os_end().
.Pp
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.
.Pp
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 initialized 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.
.Pp
The sqlite3_os_init() routine does operating-system specific initialization
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().
.Pp
The application should never invoke either sqlite3_os_init() or sqlite3_os_end()
directly.
The application should only invoke sqlite3_initialize() and sqlite3_shutdown().
The sqlite3_os_init() interface is called automatically by sqlite3_initialize()
and sqlite3_os_end() is called by sqlite3_shutdown().
Appropriate implementations for sqlite3_os_init() and sqlite3_os_end()
are built into SQLite when it is compiled for Unix, Windows, 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.
.Sh SEE ALSO
.Xr sqlite3 3 ,
.Xr sqlite3_config 3 ,
.Xr sqlite3_open 3 ,
.Xr sqlite3_vfs 3 ,
.Xr SQLITE_OK 3