Documentation Source Text

Check-in [8182293dd8]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Clarify how the SQLITE_OK_LOAD_PERMANENTLY return value should be used.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 8182293dd874305f0c08b5ae1cdf89bb4efadcaae08c0af121f43014f05cdda8
User & Date: drh 2019-02-12 12:27:17.149
Context
2019-02-12
13:54
Fix a typo in loadext.html. (check-in: 4efb429d19 user: drh tags: trunk)
12:27
Clarify how the SQLITE_OK_LOAD_PERMANENTLY return value should be used. (check-in: 8182293dd8 user: drh tags: trunk)
2019-02-11
13:24
Fix "asterix" typo in fts5.in. (check-in: 569262e571 user: dan tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/loadext.in.
263
264
265
266
267
268
269
























270
271
272
273
274
275
276
[sqlite3_load_extension()] closes.  (In other words, the xDlUnload method 
of the [sqlite3_vfs] object is called for all extensions when a database
connection closes.)  However, if the initialization procedure returns
[SQLITE_OK_LOAD_PERMANENTLY] instead of SQLITE_OK, then the extension will
not be unloaded (xDlClose will not be invoked) and the extension will remain
in process memory indefinitely.  The SQLITE_OK_LOAD_PERMANENTLY return
value is useful for extensions that want to register new [VFSes].

























<h1>Statically Linking A Run-Time Loadable Extension</h1>

<p>The exact same source code can be used for both a run-time loadable
shared library or DLL and as a module that is statically linked with your
application.  This provides flexibility and allows you to reuse the same
code in different ways.</p>







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
[sqlite3_load_extension()] closes.  (In other words, the xDlUnload method 
of the [sqlite3_vfs] object is called for all extensions when a database
connection closes.)  However, if the initialization procedure returns
[SQLITE_OK_LOAD_PERMANENTLY] instead of SQLITE_OK, then the extension will
not be unloaded (xDlClose will not be invoked) and the extension will remain
in process memory indefinitely.  The SQLITE_OK_LOAD_PERMANENTLY return
value is useful for extensions that want to register new [VFSes].

<p>To clarify: an extension for which the initialization function returns
SQLITE_OK_LOAD_PERMANENTLY continues to exist in memory after the database
connection closes.  However, the extension is <em>not</em> automatically
registered with subsequent database connections.  This make it possible
to load extensions that implement new [VFSes].
To persistently load and register an extension that implements new SQL
functions, collating sequences, and/or virtual tables, such that those
added capabilities are available to all subsequent database connections,
then the initialization routine should also invoke [sqlite3_auto_extension()]
on a subfunction that will register those services.

<p>The [https://sqlite.org/src/file/ext/misc/vfsstat.c|vfsstat.c] extension
show an example of a loadable extension that persistently registers both
a new VFS and a new virtual table.  The
[https://sqlite.org/src/info/77b5b4235c9f7f11?ln=801-819|sqlite3_vfsstat_init()]
initialization routine in that extension is called only once, when the
extension is first loaded.  It registers the new "vfslog" VFS just that
one time, and it returns SQLITE_OK_LOAD_PERMANENTLY so that the code used
to implement the "vfslog" VFS will remain in memory. The initialization routine
also invokes [sqlite3_auto_extension()] on a pointer to the "vstatRegister()"
function so that all subsequent database connections will invoke the
"vstatRegister()" function as they start up, and hence register the
"vfsstat" virtual table.  

<h1>Statically Linking A Run-Time Loadable Extension</h1>

<p>The exact same source code can be used for both a run-time loadable
shared library or DLL and as a module that is statically linked with your
application.  This provides flexibility and allows you to reuse the same
code in different ways.</p>
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
connection separately, you might want to consider using the
[sqlite3_auto_extension()] interface to register your extensions and
to cause them to be automatically started as each database connection
is opened.  You only have to register each extension once, and you can
do so near the beginning of your main() routine.  Using the
[sqlite3_auto_extension()] interface to register your extensions makes
your extensions work as if they were built into the core SQLite - they
are automatically there whenever you open a new database connection
without needing to be initialized.  Just be sure to complete any
configuration you need to accomplish using [sqlite3_config()] before
registering your extensions, since the [sqlite3_auto_extension()]
interface implicitly calls [sqlite3_initialize()].</p>

<h1>Implementation Details</h1>








|







316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
connection separately, you might want to consider using the
[sqlite3_auto_extension()] interface to register your extensions and
to cause them to be automatically started as each database connection
is opened.  You only have to register each extension once, and you can
do so near the beginning of your main() routine.  Using the
[sqlite3_auto_extension()] interface to register your extensions makes
your extensions work as if they were built into the core SQLite - they
automatically exist whenever you open a new database connection
without needing to be initialized.  Just be sure to complete any
configuration you need to accomplish using [sqlite3_config()] before
registering your extensions, since the [sqlite3_auto_extension()]
interface implicitly calls [sqlite3_initialize()].</p>

<h1>Implementation Details</h1>