1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
.Dd January 24, 2024
.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
.In sqlite3.h
.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,
.Fn sqlite3_open
calls sqlite3_initialize() so the SQLite library will be automatically
initialized when
.Fn 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
.Fn 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_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 IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 1567.
.Bd -literal
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);
.Ed
.Sh SEE ALSO
.Xr sqlite3 3 ,
.Xr sqlite3_config 3 ,
.Xr sqlite3_open 3 ,
.Xr sqlite3_vfs 3 ,
.Xr SQLITE_OK 3
|
