1.Dd December 19, 2018 2.Dt SQLITE3_INITIALIZE 3 3.Os 4.Sh NAME 5.Nm sqlite3_initialize , 6.Nm sqlite3_shutdown , 7.Nm sqlite3_os_init , 8.Nm sqlite3_os_end 9.Nd Initialize The SQLite Library 10.Sh SYNOPSIS 11.Ft int 12.Fo sqlite3_initialize 13.Fa "void" 14.Fc 15.Ft int 16.Fo sqlite3_shutdown 17.Fa "void" 18.Fc 19.Ft int 20.Fo sqlite3_os_init 21.Fa "void" 22.Fc 23.Ft int 24.Fo sqlite3_os_end 25.Fa "void" 26.Fc 27.Sh DESCRIPTION 28The sqlite3_initialize() routine initializes the SQLite library. 29The sqlite3_shutdown() routine deallocates any resources that were 30allocated by sqlite3_initialize(). 31These routines are designed to aid in process initialization and shutdown 32on embedded systems. 33Workstation applications using SQLite normally do not need to invoke 34either of these routines. 35.Pp 36A call to sqlite3_initialize() is an "effective" call if it is the 37first time sqlite3_initialize() is invoked during the lifetime of the 38process, or if it is the first time sqlite3_initialize() is invoked 39following a call to sqlite3_shutdown(). 40Only an effective call of sqlite3_initialize() does any initialization. 41All other calls are harmless no-ops. 42.Pp 43A call to sqlite3_shutdown() is an "effective" call if it is the first 44call to sqlite3_shutdown() since the last sqlite3_initialize(). 45Only an effective call to sqlite3_shutdown() does any deinitialization. 46All other valid calls to sqlite3_shutdown() are harmless no-ops. 47.Pp 48The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown() 49is not. 50The sqlite3_shutdown() interface must only be called from a single 51thread. 52All open database connections must be closed and 53all other SQLite resources must be deallocated prior to invoking sqlite3_shutdown(). 54.Pp 55Among other things, sqlite3_initialize() will invoke sqlite3_os_init(). 56Similarly, sqlite3_shutdown() will invoke sqlite3_os_end(). 57.Pp 58The sqlite3_initialize() routine returns SQLITE_OK on success. 59If for some reason, sqlite3_initialize() is unable to initialize the 60library (perhaps it is unable to allocate a needed resource such as 61a mutex) it returns an error code other than SQLITE_OK. 62.Pp 63The sqlite3_initialize() routine is called internally by many other 64SQLite interfaces so that an application usually does not need to invoke 65sqlite3_initialize() directly. 66For example, sqlite3_open() calls sqlite3_initialize() 67so the SQLite library will be automatically initialized when sqlite3_open() 68is called if it has not be initialized already. 69However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT 70compile-time option, then the automatic calls to sqlite3_initialize() 71are omitted and the application must call sqlite3_initialize() directly 72prior to using any other SQLite interface. 73For maximum portability, it is recommended that applications always 74invoke sqlite3_initialize() directly prior to using any other SQLite 75interface. 76Future releases of SQLite may require this. 77In other words, the behavior exhibited when SQLite is compiled with 78SQLITE_OMIT_AUTOINIT might become the default behavior 79in some future release of SQLite. 80.Pp 81The sqlite3_os_init() routine does operating-system specific initialization 82of the SQLite library. 83The sqlite3_os_end() routine undoes the effect of sqlite3_os_init(). 84Typical tasks performed by these routines include allocation or deallocation 85of static resources, initialization of global variables, setting up 86a default sqlite3_vfs module, or setting up a default configuration 87using sqlite3_config(). 88.Pp 89The application should never invoke either sqlite3_os_init() or sqlite3_os_end() 90directly. 91The application should only invoke sqlite3_initialize() and sqlite3_shutdown(). 92The sqlite3_os_init() interface is called automatically by sqlite3_initialize() 93and sqlite3_os_end() is called by sqlite3_shutdown(). 94Appropriate implementations for sqlite3_os_init() and sqlite3_os_end() 95are built into SQLite when it is compiled for Unix, Windows, or OS/2. 96When built for other platforms (using the 97SQLITE_OS_OTHER=1 compile-time option) the application 98must supply a suitable implementation for sqlite3_os_init() and sqlite3_os_end(). 99An application-supplied implementation of sqlite3_os_init() or sqlite3_os_end() 100must return SQLITE_OK on success and some other error code 101upon failure. 102.Sh SEE ALSO 103.Xr sqlite3 3 , 104.Xr sqlite3_config 3 , 105.Xr sqlite3_open 3 , 106.Xr sqlite3_vfs 3 , 107.Xr SQLITE_OK 3 108