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