| 1 |
<!DOCTYPE html> |
| 2 |
<html><head> |
| 3 |
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| 4 |
<meta http-equiv="content-type" content="text/html; charset=UTF-8"> |
| 5 |
<link href="sqlite.css" rel="stylesheet"> |
| 6 |
<title>Run-Time Loadable Extensions</title> |
| 7 |
<!-- path= --> |
| 8 |
</head> |
| 9 |
<body> |
| 10 |
<div class=nosearch> |
| 11 |
<a href="index.html"> |
| 12 |
<img class="logo" src="images/sqlite370_banner.svg" alt="SQLite" border="0"> |
| 13 |
</a> |
| 14 |
<div><!-- IE hack to prevent disappearing logo --></div> |
| 15 |
<div class="tagline desktoponly"> |
| 16 |
Small. Fast. Reliable.<br>Choose any three. |
| 17 |
</div> |
| 18 |
<div class="menu mainmenu"> |
| 19 |
<ul> |
| 20 |
<li><a href="index.html">Home</a> |
| 21 |
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a> |
| 22 |
<li class='wideonly'><a href='about.html'>About</a> |
| 23 |
<li class='desktoponly'><a href="docs.html">Documentation</a> |
| 24 |
<li class='desktoponly'><a href="download.html">Download</a> |
| 25 |
<li class='wideonly'><a href='copyright.html'>License</a> |
| 26 |
<li class='desktoponly'><a href="support.html">Support</a> |
| 27 |
<li class='desktoponly'><a href="prosupport.html">Purchase</a> |
| 28 |
<li class='search' id='search_menubutton'> |
| 29 |
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a> |
| 30 |
</ul> |
| 31 |
</div> |
| 32 |
<div class="menu submenu" id="submenu"> |
| 33 |
<ul> |
| 34 |
<li><a href='about.html'>About</a> |
| 35 |
<li><a href='docs.html'>Documentation</a> |
| 36 |
<li><a href='download.html'>Download</a> |
| 37 |
<li><a href='support.html'>Support</a> |
| 38 |
<li><a href='prosupport.html'>Purchase</a> |
| 39 |
</ul> |
| 40 |
</div> |
| 41 |
<div class="searchmenu" id="searchmenu"> |
| 42 |
<form method="GET" action="search"> |
| 43 |
<select name="s" id="searchtype"> |
| 44 |
<option value="d">Search Documentation</option> |
| 45 |
<option value="c">Search Changelog</option> |
| 46 |
</select> |
| 47 |
<input type="text" name="q" id="searchbox" value=""> |
| 48 |
<input type="submit" value="Go"> |
| 49 |
</form> |
| 50 |
</div> |
| 51 |
</div> |
| 52 |
<script> |
| 53 |
function toggle_div(nm) { |
| 54 |
var w = document.getElementById(nm); |
| 55 |
if( w.style.display=="block" ){ |
| 56 |
w.style.display = "none"; |
| 57 |
}else{ |
| 58 |
w.style.display = "block"; |
| 59 |
} |
| 60 |
} |
| 61 |
function toggle_search() { |
| 62 |
var w = document.getElementById("searchmenu"); |
| 63 |
if( w.style.display=="block" ){ |
| 64 |
w.style.display = "none"; |
| 65 |
} else { |
| 66 |
w.style.display = "block"; |
| 67 |
setTimeout(function(){ |
| 68 |
document.getElementById("searchbox").focus() |
| 69 |
}, 30); |
| 70 |
} |
| 71 |
} |
| 72 |
function div_off(nm){document.getElementById(nm).style.display="none";} |
| 73 |
window.onbeforeunload = function(e){div_off("submenu");} |
| 74 |
/* Disable the Search feature if we are not operating from CGI, since */ |
| 75 |
/* Search is accomplished using CGI and will not work without it. */ |
| 76 |
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){ |
| 77 |
document.getElementById("search_menubutton").style.display = "none"; |
| 78 |
} |
| 79 |
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */ |
| 80 |
function hideorshow(btn,obj){ |
| 81 |
var x = document.getElementById(obj); |
| 82 |
var b = document.getElementById(btn); |
| 83 |
if( x.style.display!='none' ){ |
| 84 |
x.style.display = 'none'; |
| 85 |
b.innerHTML='show'; |
| 86 |
}else{ |
| 87 |
x.style.display = ''; |
| 88 |
b.innerHTML='hide'; |
| 89 |
} |
| 90 |
return false; |
| 91 |
} |
| 92 |
var antiRobot = 0; |
| 93 |
function antiRobotGo(){ |
| 94 |
if( antiRobot!=3 ) return; |
| 95 |
antiRobot = 7; |
| 96 |
var j = document.getElementById("mtimelink"); |
| 97 |
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href"); |
| 98 |
} |
| 99 |
function antiRobotDefense(){ |
| 100 |
document.body.onmousedown=function(){ |
| 101 |
antiRobot |= 2; |
| 102 |
antiRobotGo(); |
| 103 |
document.body.onmousedown=null; |
| 104 |
} |
| 105 |
document.body.onmousemove=function(){ |
| 106 |
antiRobot |= 2; |
| 107 |
antiRobotGo(); |
| 108 |
document.body.onmousemove=null; |
| 109 |
} |
| 110 |
setTimeout(function(){ |
| 111 |
antiRobot |= 1; |
| 112 |
antiRobotGo(); |
| 113 |
}, 100) |
| 114 |
antiRobotGo(); |
| 115 |
} |
| 116 |
antiRobotDefense(); |
| 117 |
</script> |
| 118 |
<div class=fancy> |
| 119 |
<div class=nosearch> |
| 120 |
<div class="fancy_title"> |
| 121 |
Run-Time Loadable Extensions |
| 122 |
</div> |
| 123 |
<details class="fancy_toc"> |
| 124 |
<summary>Table Of Contents</summary> |
| 125 |
<div id="toc_sub"><div class="fancy-toc1"><a href="#overview">1. Overview</a></div> |
| 126 |
<div class="fancy-toc1"><a href="#loading_an_extension">2. Loading An Extension</a></div> |
| 127 |
<div class="fancy-toc1"><a href="#compiling_a_loadable_extension">3. Compiling A Loadable Extension</a></div> |
| 128 |
<div class="fancy-toc1"><a href="#programming_loadable_extensions">4. Programming Loadable Extensions</a></div> |
| 129 |
<div class="fancy-toc2"><a href="#example_extensions">4.1. Example Extensions</a></div> |
| 130 |
<div class="fancy-toc1"><a href="#persistent_loadable_extensions">5. Persistent Loadable Extensions</a></div> |
| 131 |
<div class="fancy-toc1"><a href="#statically_linking_a_run_time_loadable_extension">6. Statically Linking A Run-Time Loadable Extension</a></div> |
| 132 |
<div class="fancy-toc1"><a href="#implementation_details">7. Implementation Details</a></div> |
| 133 |
</div> |
| 134 |
</details> |
| 135 |
</div> |
| 136 |
|
| 137 |
|
| 138 |
|
| 139 |
|
| 140 |
|
| 141 |
<h1 id="overview"><span>1. </span>Overview</h1> |
| 142 |
|
| 143 |
<p>SQLite has the ability to load extensions (including new |
| 144 |
<a href="appfunc.html">application-defined SQL functions</a>, |
| 145 |
<a href="datatype3.html#collation">collating sequences</a>, <a href="vtab.html">virtual tables</a>, and <a href="vfs.html">VFSes</a>) at run-time. |
| 146 |
This feature allows the code for extensions to be developed and |
| 147 |
tested separately from the application and then loaded |
| 148 |
on an as-needed basis.</p> |
| 149 |
|
| 150 |
<p>Extensions can also be statically linked with the application. |
| 151 |
The code template shown below will work just as well as a statically |
| 152 |
linked extension as it does as a run-time loadable extension except that |
| 153 |
you should give the entry point function ("sqlite3_extension_init") |
| 154 |
a different name to avoid name collisions if your application contains |
| 155 |
two or more extensions.</p> |
| 156 |
|
| 157 |
<h1 id="loading_an_extension"><span>2. </span>Loading An Extension</h1> |
| 158 |
|
| 159 |
<p>An SQLite extension is a shared library or DLL. To load it, you |
| 160 |
need to supply SQLite with the name of the file containing the |
| 161 |
shared library or DLL and an entry point to initialize the extension. |
| 162 |
In C code, this information is supplied using the |
| 163 |
<a href="c3ref/load_extension.html">sqlite3_load_extension()</a> API. See the documentation on that |
| 164 |
routine for additional information.</p> |
| 165 |
|
| 166 |
<p>Note that different operating systems use different filename |
| 167 |
suffixes for their shared libraries. Windows uses ".dll", Mac uses |
| 168 |
".dylib", and most unixes other than mac use ".so". If you want to |
| 169 |
make your code portable, you can omit the suffix from the shared |
| 170 |
library filename and the appropriate suffix will be added automatically |
| 171 |
by the <a href="c3ref/load_extension.html">sqlite3_load_extension()</a> interface.</p> |
| 172 |
|
| 173 |
<p>There is also an SQL function that can be used to load extensions: |
| 174 |
<a href="lang_corefunc.html#load_extension">load_extension(X,Y)</a>. It works just like the <a href="c3ref/load_extension.html">sqlite3_load_extension()</a> |
| 175 |
C interface.</p> |
| 176 |
|
| 177 |
<p>Both methods for loading an extension allow you to specify |
| 178 |
the name of an entry point for the extension. |
| 179 |
You can leave this argument blank - passing in |
| 180 |
a NULL pointer for the <a href="c3ref/load_extension.html">sqlite3_load_extension()</a> C-language interface |
| 181 |
or omitting the second argument for the <a href="lang_corefunc.html#load_extension">load_extension()</a> SQL interface - |
| 182 |
and the extension loader logic will attempt to figure out the entry point |
| 183 |
on its own. It will first try the generic extension name |
| 184 |
"sqlite3_extension_init". If that does not work, it constructs an |
| 185 |
entry point using the template "sqlite3_X_init" where the X is replaced |
| 186 |
by the lowercase equivalent of every ASCII character in the filename |
| 187 |
after the last "/" and before the first following "." omitting the |
| 188 |
first three characters if they happen to be "lib". So, for example, |
| 189 |
if the filename is "/usr/lib/libmathfunc-4.8.so" the entry point name |
| 190 |
would be "sqlite3_mathfunc_init". Or if the filename is |
| 191 |
"./SpellFixExt.dll" then the entry point would be called |
| 192 |
"sqlite3_spellfixext_init". |
| 193 |
|
| 194 |
</p><p>For security reasons, extension loading is turned off by default. |
| 195 |
In order to use either the C-language or SQL extension loading functions, |
| 196 |
one must first enable extension loading using the |
| 197 |
<a href="c3ref/db_config.html">sqlite3_db_config</a>(db,<a href="c3ref/c_dbconfig_defensive.html#sqlitedbconfigenableloadextension">SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</a>,1,NULL) |
| 198 |
C-language API in your application.</p> |
| 199 |
|
| 200 |
<p>From the <a href="cli.html">command-line shell</a>, extensions can be loaded using the |
| 201 |
".load" dot-command. For example: |
| 202 |
|
| 203 |
</p><blockquote><pre> |
| 204 |
.load ./YourCode |
| 205 |
</pre></blockquote> |
| 206 |
|
| 207 |
<p>Note that the command-line shell program has already enabled |
| 208 |
extension loading for you (by calling the <a href="c3ref/enable_load_extension.html">sqlite3_enable_load_extension()</a> |
| 209 |
interface as part of its setup) so the command above works without |
| 210 |
any special switches, setup, or other complications.</p> |
| 211 |
|
| 212 |
<p>The ".load" command with one argument invokes sqlite3_load_extension() |
| 213 |
with the zProc parameter set to NULL, causing SQLite to first look for |
| 214 |
an entry point named "sqlite3_extension_init" and then "sqlite3_X_init" |
| 215 |
where "X" is derived from the filename. If your extension has an entry |
| 216 |
point with a different name, simply supply that name as the second |
| 217 |
argument. For example:</p> |
| 218 |
|
| 219 |
<blockquote><pre> |
| 220 |
.load ./YourCode nonstandard_entry_point |
| 221 |
</pre></blockquote> |
| 222 |
|
| 223 |
<a name="build"></a> |
| 224 |
|
| 225 |
<h1 id="compiling_a_loadable_extension"><span>3. </span>Compiling A Loadable Extension</h1> |
| 226 |
|
| 227 |
<p>Loadable extensions are C-code. To compile them on |
| 228 |
most unix-like operating |
| 229 |
systems, the usual command is something like this:</p> |
| 230 |
|
| 231 |
<blockquote><pre> |
| 232 |
gcc -g -fPIC -shared YourCode.c -o YourCode.so |
| 233 |
</pre></blockquote> |
| 234 |
|
| 235 |
<p>Macs are unix-like, but they do not follow the usual shared library |
| 236 |
conventions. To compile a shared library on a Mac, use a command like |
| 237 |
this:</p> |
| 238 |
|
| 239 |
<blockquote><pre> |
| 240 |
gcc -g -fPIC -dynamiclib YourCode.c -o YourCode.dylib |
| 241 |
</pre></blockquote> |
| 242 |
|
| 243 |
<p>If when you try to load your library you get back an error message |
| 244 |
that says "mach-o, but wrong architecture" then you might need to add |
| 245 |
command-line options "-arch i386" or "arch x86_64" to gcc, depending |
| 246 |
on how your application is built.</p> |
| 247 |
|
| 248 |
<p>To compile on Windows using MSVC, a command similar to the following |
| 249 |
will usually work:</p> |
| 250 |
|
| 251 |
<blockquote><pre> |
| 252 |
cl YourCode.c -link -dll -out:YourCode.dll |
| 253 |
</pre></blockquote> |
| 254 |
|
| 255 |
<p>To compile for Windows using MinGW, the command line is just like it |
| 256 |
is for unix except that the output file suffix is changed to ".dll" and |
| 257 |
the -fPIC argument is omitted:</p> |
| 258 |
|
| 259 |
<blockquote><pre> |
| 260 |
gcc -g -shared YourCode.c -o YourCode.dll |
| 261 |
</pre></blockquote> |
| 262 |
|
| 263 |
<a name="write"></a> |
| 264 |
|
| 265 |
<h1 id="programming_loadable_extensions"><span>4. </span>Programming Loadable Extensions</h1> |
| 266 |
|
| 267 |
<p>A template loadable extension contains the following three elements:</p> |
| 268 |
|
| 269 |
<ol> |
| 270 |
<li><p> |
| 271 |
Use "<tt>#include <sqlite3ext.h></tt>" at the top of your source |
| 272 |
code files instead of "<tt>#include <sqlite3.h></tt>". |
| 273 |
</p> |
| 274 |
|
| 275 |
</li><li><p> |
| 276 |
Put the macro "<tt>SQLITE_EXTENSION_INIT1</tt>" on a line by itself |
| 277 |
right after the "<tt>#include <sqlite3ext.h></tt>" line. |
| 278 |
</p> |
| 279 |
|
| 280 |
</li><li><p> |
| 281 |
Add an extension loading entry point routine that looks something like |
| 282 |
the following: |
| 283 |
|
| 284 |
</p><div class="codeblock"><pre>#ifdef _WIN32 |
| 285 |
__declspec(dllexport) |
| 286 |
#endif |
| 287 |
int sqlite3_extension_init( /* <== Change this name, maybe */ |
| 288 |
sqlite3 *db, |
| 289 |
char **pzErrMsg, |
| 290 |
const sqlite3_api_routines *pApi |
| 291 |
){ |
| 292 |
int rc = SQLITE_OK; |
| 293 |
SQLITE_EXTENSION_INIT2(pApi); |
| 294 |
/* insert code to initialize your extension here */ |
| 295 |
return rc; |
| 296 |
} |
| 297 |
</pre></div> |
| 298 |
|
| 299 |
<p>You will do well to customize the name of your entry point to |
| 300 |
correspond to the name of the shared library you will be generating, |
| 301 |
rather than using the generic "sqlite3_extension_init" name. Giving |
| 302 |
your extension a custom entry point name will enable you to statically |
| 303 |
link two or more extensions into the same program without a linker |
| 304 |
conflict, if you later decide to use static linking rather than run-time |
| 305 |
linking. |
| 306 |
If your shared library ends up being named "YourCode.so" or |
| 307 |
"YourCode.dll" or "YourCode.dylib" as shown in the compiler examples |
| 308 |
above, then the correct entry point name would be |
| 309 |
"sqlite3_yourcode_init". |
| 310 |
</p></li></ol> |
| 311 |
|
| 312 |
<p>Here is a complete template extension that you can copy/paste |
| 313 |
to get started:</p> |
| 314 |
|
| 315 |
<div class="codeblock"><pre>/* Add your header comment here */ |
| 316 |
#include <sqlite3ext.h> /* Do not use <sqlite3.h>! */ |
| 317 |
SQLITE_EXTENSION_INIT1 |
| 318 |
|
| 319 |
/* Insert your extension code here */ |
| 320 |
|
| 321 |
#ifdef _WIN32 |
| 322 |
__declspec(dllexport) |
| 323 |
#endif |
| 324 |
/* TODO: Change the entry point name so that "extension" is replaced by |
| 325 |
** text derived from the shared library filename as follows: Copy every |
| 326 |
** ASCII alphabetic character from the filename after the last "/" through |
| 327 |
** the next following ".", converting each character to lowercase, and |
| 328 |
** discarding the first three characters if they are "lib". |
| 329 |
*/ |
| 330 |
int sqlite3_extension_init( |
| 331 |
sqlite3 *db, |
| 332 |
char **pzErrMsg, |
| 333 |
const sqlite3_api_routines *pApi |
| 334 |
){ |
| 335 |
int rc = SQLITE_OK; |
| 336 |
SQLITE_EXTENSION_INIT2(pApi); |
| 337 |
/* Insert here calls to |
| 338 |
** sqlite3_create_function_v2(), |
| 339 |
** sqlite3_create_collation_v2(), |
| 340 |
** sqlite3_create_module_v2(), and/or |
| 341 |
** sqlite3_vfs_register() |
| 342 |
** to register the new features that your extension adds. |
| 343 |
*/ |
| 344 |
return rc; |
| 345 |
} |
| 346 |
</pre></div> |
| 347 |
|
| 348 |
<h2 id="example_extensions"><span>4.1. </span>Example Extensions</h2> |
| 349 |
|
| 350 |
<p>Many examples of complete and working loadable extensions can be |
| 351 |
seen in the SQLite source tree in the |
| 352 |
<a href="https://sqlite.org/src/file/ext/misc">ext/misc</a> subdirectory. |
| 353 |
Each file in that directory is a separate extension. Documentation |
| 354 |
is provided by a header comment on the file. |
| 355 |
Here are brief notes on a few of the extensions in |
| 356 |
the <a href="https://sqlite.org/src/file/ext/misc">ext/misc</a> subdirectory: |
| 357 |
|
| 358 |
</p><ul> |
| 359 |
<li><p> |
| 360 |
<a href="https://sqlite.org/src/file/ext/misc/carray.c">carray.c</a> — |
| 361 |
Implementation of the <a href="carray.html">carray table-valued function</a>. |
| 362 |
</p></li><li><p> |
| 363 |
<a href="https://sqlite.org/src/file/ext/misc/compress.c">compress.c</a> — |
| 364 |
Implementation of <a href="appfunc.html">application-defined SQL functions</a> compress() and |
| 365 |
uncompress() that do zLib compression of text or blob content. |
| 366 |
</p></li><li><p> |
| 367 |
<a href="https://sqlite.org/src/file/ext/misc/rot13.c">rot13.c</a> — |
| 368 |
Implementation of a <a href="https://en.wikipedia.org/wiki/ROT13">rot13()</a> |
| 369 |
SQL function. This is a very simple example of an extension function |
| 370 |
and is useful as a template for creating new extensions. |
| 371 |
</p></li><li><p> |
| 372 |
<a href="https://sqlite.org/src/file/ext/misc/series.c">series.c</a> — |
| 373 |
Implementation of the generate_series <a href="vtab.html">virtual table</a> and |
| 374 |
<a href="vtab.html#tabfunc2">table-valued function</a>. This is a relatively simple example of a |
| 375 |
virtual table implementation which can serve as a template for writing |
| 376 |
new virtual tables. |
| 377 |
</p></li></ul> |
| 378 |
|
| 379 |
<p>Other and more complex extensions can be found in subfolders |
| 380 |
under <a href="https://sqlite.org/src/file/ext">ext/</a> other than ext/misc/. |
| 381 |
|
| 382 |
<a name="persist"></a> |
| 383 |
|
| 384 |
</p><h1 id="persistent_loadable_extensions"><span>5. </span>Persistent Loadable Extensions</h1> |
| 385 |
|
| 386 |
<p>The default behavior for a loadable extension is that it is unloaded |
| 387 |
from process memory when the database connection that originally invoked |
| 388 |
<a href="c3ref/load_extension.html">sqlite3_load_extension()</a> closes. (In other words, the xDlClose method |
| 389 |
of the <a href="c3ref/vfs.html">sqlite3_vfs</a> object is called for all extensions when a database |
| 390 |
connection closes.) However, if the initialization procedure returns |
| 391 |
<a href="rescode.html#ok_load_permanently">SQLITE_OK_LOAD_PERMANENTLY</a> instead of SQLITE_OK, then the extension will |
| 392 |
not be unloaded (xDlClose will not be invoked) and the extension will remain |
| 393 |
in process memory indefinitely. The SQLITE_OK_LOAD_PERMANENTLY return |
| 394 |
value is useful for extensions that want to register new <a href="vfs.html">VFSes</a>. |
| 395 |
|
| 396 |
</p><p>To clarify: an extension for which the initialization function returns |
| 397 |
SQLITE_OK_LOAD_PERMANENTLY continues to exist in memory after the database |
| 398 |
connection closes. However, the extension is <em>not</em> automatically |
| 399 |
registered with subsequent database connections. This makes it possible |
| 400 |
to load extensions that implement new <a href="vfs.html">VFSes</a>. |
| 401 |
To persistently load and register an extension that implements new SQL |
| 402 |
functions, collating sequences, and/or virtual tables, such that those |
| 403 |
added capabilities are available to all subsequent database connections, |
| 404 |
then the initialization routine should also invoke <a href="c3ref/auto_extension.html">sqlite3_auto_extension()</a> |
| 405 |
on a subfunction that will register those services. |
| 406 |
|
| 407 |
</p><p>The <a href="https://sqlite.org/src/file/ext/misc/vfsstat.c">vfsstat.c</a> extension |
| 408 |
show an example of a loadable extension that persistently registers both |
| 409 |
a new VFS and a new virtual table. The |
| 410 |
<a href="https://sqlite.org/src/info/77b5b4235c9f7f11?ln=801-819">sqlite3_vfsstat_init()</a> |
| 411 |
initialization routine in that extension is called only once, when the |
| 412 |
extension is first loaded. It registers the new "vfslog" VFS just that |
| 413 |
one time, and it returns SQLITE_OK_LOAD_PERMANENTLY so that the code used |
| 414 |
to implement the "vfslog" VFS will remain in memory. The initialization routine |
| 415 |
also invokes <a href="c3ref/auto_extension.html">sqlite3_auto_extension()</a> on a pointer to the "vstatRegister()" |
| 416 |
function so that all subsequent database connections will invoke the |
| 417 |
"vstatRegister()" function as they start up, and hence register the |
| 418 |
"vfsstat" virtual table. |
| 419 |
|
| 420 |
<a name="statext"></a> |
| 421 |
|
| 422 |
</p><h1 id="statically_linking_a_run_time_loadable_extension"><span>6. </span>Statically Linking A Run-Time Loadable Extension</h1> |
| 423 |
|
| 424 |
<p>The exact same source code can be used for both a run-time loadable |
| 425 |
shared library or DLL and as a module that is statically linked with your |
| 426 |
application. This provides flexibility and allows you to reuse the same |
| 427 |
code in different ways.</p> |
| 428 |
|
| 429 |
<p>To statically link your extension, simply add the -DSQLITE_CORE |
| 430 |
compile-time option. The SQLITE_CORE macro causes the SQLITE_EXTENSION_INIT1 |
| 431 |
and SQLITE_EXTENSION_INIT2 macros to become no-ops. Then modify your |
| 432 |
application to invoke the entry point directly, passing in a NULL pointer |
| 433 |
as the third "pApi" parameter.</p> |
| 434 |
|
| 435 |
<p>It is particularly important to use an entry point name that is |
| 436 |
based on the extension filename, rather than the generic |
| 437 |
"sqlite3_extension_init" entry point name, if you will be statically |
| 438 |
linking two or more extensions. If you use the generic name, there |
| 439 |
will be multiple definitions of the same symbol and the link will fail.</p> |
| 440 |
|
| 441 |
<p>If you will be opening multiple database connections in your application, |
| 442 |
rather than invoking the extension entry points for each database |
| 443 |
connection separately, you might want to consider using the |
| 444 |
<a href="c3ref/auto_extension.html">sqlite3_auto_extension()</a> interface to register your extensions and |
| 445 |
to cause them to be automatically started as each database connection |
| 446 |
is opened. You only have to register each extension once, and you can |
| 447 |
do so near the beginning of your main() routine. Using the |
| 448 |
<a href="c3ref/auto_extension.html">sqlite3_auto_extension()</a> interface to register your extensions makes |
| 449 |
your extensions work as if they were built into the core SQLite - they |
| 450 |
automatically exist whenever you open a new database connection |
| 451 |
without needing to be initialized. Just be sure to complete any |
| 452 |
configuration you need to accomplish using <a href="c3ref/config.html">sqlite3_config()</a> before |
| 453 |
registering your extensions, since the <a href="c3ref/auto_extension.html">sqlite3_auto_extension()</a> |
| 454 |
interface implicitly calls <a href="c3ref/initialize.html">sqlite3_initialize()</a>.</p> |
| 455 |
|
| 456 |
<h1 id="implementation_details"><span>7. </span>Implementation Details</h1> |
| 457 |
|
| 458 |
<p>SQLite implements run-time extension loading using the |
| 459 |
xDlOpen(), xDlError(), xDlSym(), and xDlClose() methods of the |
| 460 |
<a href="c3ref/vfs.html">sqlite3_vfs</a> object. These methods are implemented using |
| 461 |
the dlopen() library on unix (which explains why SQLite commonly |
| 462 |
needs to be linked against the "-ldl" library on unix systems) |
| 463 |
and using LoadLibrary() API on Windows. In a custom <a href="vfs.html">VFS</a> for |
| 464 |
unusual systems, these methods can all be omitted, in which case |
| 465 |
the run-time extension loading mechanism will not work (though |
| 466 |
you will still be able to statically link the extension code, assuming |
| 467 |
the entry pointers are uniquely named). |
| 468 |
SQLite can be compiled with |
| 469 |
<a href="compile.html#omit_load_extension">SQLITE_OMIT_LOAD_EXTENSION</a> to omit the extension loading code |
| 470 |
from the build. |
| 471 |
</p><p align="center"><small><i>This page was last updated on 2025-11-13 07:12:58Z </small></i></p> |
| 472 |
|