108 lines
4.2 KiB
Groff
108 lines
4.2 KiB
Groff
.Dd March 11, 2017
|
|
.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
|