~ubuntu-branches/ubuntu/wily/sqlite3/wily

onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">

112

113

</form>

114

</div>

115

</table>

116

</div></div></div></div>

117

</td></tr></table>

118

119

120

<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Initialize The SQLite Library</h2><blockquote><pre>int sqlite3_initialize(void);

121

int sqlite3_shutdown(void);

122

int sqlite3_os_init(void);

123

int sqlite3_os_end(void);

124

</pre></blockquote><p>

125

The sqlite3_initialize() routine initializes the

126

SQLite library. The sqlite3_shutdown() routine

127

deallocates any resources that were allocated by sqlite3_initialize().

128

These routines are designed to aid in process initialization and

129

shutdown on embedded systems. Workstation applications using

130

SQLite normally do not need to invoke either of these routines.</p>

131

132

<p>A call to sqlite3_initialize() is an "effective" call if it is

133

the first time sqlite3_initialize() is invoked during the lifetime of

134

the process, or if it is the first time sqlite3_initialize() is invoked

135

following a call to sqlite3_shutdown(). Only an effective call

136

of sqlite3_initialize() does any initialization. All other calls

137

are harmless no-ops.</p>

138

139

<p>A call to sqlite3_shutdown() is an "effective" call if it is the first

140

call to sqlite3_shutdown() since the last sqlite3_initialize(). Only

141

an effective call to sqlite3_shutdown() does any deinitialization.

142

All other valid calls to sqlite3_shutdown() are harmless no-ops.</p>

143

144

<p>The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()

145

is not. The sqlite3_shutdown() interface must only be called from a

146

single thread. All open <a href="../c3ref/sqlite3.html">database connections</a> must be closed and all

147

other SQLite resources must be deallocated prior to invoking

148

sqlite3_shutdown().</p>

149

150

<p>Among other things, sqlite3_initialize() will invoke

151

sqlite3_os_init(). Similarly, sqlite3_shutdown()

152

will invoke sqlite3_os_end().</p>

153

154

<p>The sqlite3_initialize() routine returns <a href="../c3ref/c_abort.html">SQLITE_OK</a> on success.

155

If for some reason, sqlite3_initialize() is unable to initialize

156

the library (perhaps it is unable to allocate a needed resource such

157

as a mutex) it returns an <a href="../c3ref/c_abort.html">error code</a> other than <a href="../c3ref/c_abort.html">SQLITE_OK</a>.</p>

158

159

<p>The sqlite3_initialize() routine is called internally by many other

160

SQLite interfaces so that an application usually does not need to

161

invoke sqlite3_initialize() directly. For example, <a href="../c3ref/open.html">sqlite3_open()</a>

162

calls sqlite3_initialize() so the SQLite library will be automatically

163

initialized when <a href="../c3ref/open.html">sqlite3_open()</a> is called if it has not be initialized

164

already. However, if SQLite is compiled with the <a href="../compile.html#omit_autoinit">SQLITE_OMIT_AUTOINIT</a>

165

compile-time option, then the automatic calls to sqlite3_initialize()

166

are omitted and the application must call sqlite3_initialize() directly

167

prior to using any other SQLite interface. For maximum portability,

168

it is recommended that applications always invoke sqlite3_initialize()

169

directly prior to using any other SQLite interface. Future releases

170

of SQLite may require this. In other words, the behavior exhibited

171

when SQLite is compiled with <a href="../compile.html#omit_autoinit">SQLITE_OMIT_AUTOINIT</a> might become the

172

default behavior in some future release of SQLite.</p>

173

174

<p>The sqlite3_os_init() routine does operating-system specific

175

initialization of the SQLite library. The sqlite3_os_end()

176

routine undoes the effect of sqlite3_os_init(). Typical tasks

177

performed by these routines include allocation or deallocation

178

of static resources, initialization of global variables,

179

setting up a default <a href="../c3ref/vfs.html">sqlite3_vfs</a> module, or setting up

180

a default configuration using <a href="../c3ref/config.html">sqlite3_config()</a>.</p>

181

182

<p>The application should never invoke either sqlite3_os_init()

183

or sqlite3_os_end() directly. The application should only invoke

184

sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init()

185

interface is called automatically by sqlite3_initialize() and

186

sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate

187

implementations for sqlite3_os_init() and sqlite3_os_end()

188

are built into SQLite when it is compiled for Unix, Windows, or OS/2.

189

When <a href="../custombuild.html">built for other platforms</a>

190

(using the <a href="../compile.html#os_other">SQLITE_OS_OTHER=1</a> compile-time

191

option) the application must supply a suitable implementation for

192

sqlite3_os_init() and sqlite3_os_end(). An application-supplied

193

implementation of sqlite3_os_init() or sqlite3_os_end()

194

must return <a href="../c3ref/c_abort.html">SQLITE_OK</a> on success and some other <a href="../c3ref/c_abort.html">error code</a> upon

195

failure.

196

</p><p>See also lists of

197

<a href="objlist.html">Objects</a>,

198

<a href="constlist.html">Constants</a>, and

199

<a href="funclist.html">Functions</a>.</p>