.Dd January 24, 2024
.Dt SQLITE3_LOAD_EXTENSION 3
.Os
.Sh NAME
.Nm sqlite3_load_extension
.Nd load an extension
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3_load_extension
.Fa "sqlite3 *db"
.Fa "const char *zFile"
.Fa "const char *zProc"
.Fa "char **pzErrMsg"
.Fc
.Sh DESCRIPTION
This interface loads an SQLite extension library from the named file.
.Pp
The sqlite3_load_extension() interface attempts to load an SQLite extension
library contained in the file zFile.
If the file cannot be loaded directly, attempts are made to load with
various operating-system specific extensions added.
So for example, if "samplelib" cannot be loaded, then names like "samplelib.so"
or "samplelib.dylib" or "samplelib.dll" might be tried also.
.Pp
The entry point is zProc.
zProc may be 0, in which case SQLite will try to come up with an entry
point name on its own.
It first tries "sqlite3_extension_init".
If that does not work, it constructs a name "sqlite3_X_init" where
the X is consists of the lower-case equivalent of all ASCII alphabetic
characters in the filename from the last "/" to the first following
"." and omitting any initial "lib".
The sqlite3_load_extension() interface returns SQLITE_OK on
success and SQLITE_ERROR if something goes wrong.
If an error occurs and pzErrMsg is not 0, then the
.Fn sqlite3_load_extension
interface shall attempt to fill *pzErrMsg with error message text stored
in memory obtained from
.Fn sqlite3_malloc .
The calling function should free this memory by calling
.Fn sqlite3_free .
Extension loading must be enabled using
.Fn sqlite3_enable_load_extension
or sqlite3_db_config(db,SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION,1,NULL)
prior to calling this API, otherwise an error will be returned.
.Pp
\fBSecurity warning:\fP It is recommended that the SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION
method be used to enable only this interface.
The use of the
.Fn sqlite3_enable_load_extension
interface should be avoided.
This will keep the SQL function
.Fn load_extension
disabled and prevent SQL injections from giving attackers access to
extension loading capabilities.
.Pp
See also the load_extension() SQL function.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 7129.
.Bd -literal
SQLITE_API int sqlite3_load_extension(
  sqlite3 *db,          /* Load the extension into this database connection */
  const char *zFile,    /* Name of the shared library containing extension */
  const char *zProc,    /* Entry point.  Derived from zFile if 0 */
  char **pzErrMsg       /* Put error message here if not 0 */
);
.Ed
.Sh SEE ALSO
.Xr sqlite3_db_config 3 ,
.Xr sqlite3_enable_load_extension 3 ,
.Xr sqlite3_malloc 3 ,
.Xr SQLITE_DBCONFIG_MAINDBNAME 3 ,
.Xr SQLITE_OK 3