Documentation Source Text

Check-in [8182293dd8]

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

Comment:Clarify how the SQLITE_OK_LOAD_PERMANENTLY return value should be used.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
User & Date: drh 2019-02-12 12:27:17
Fix a typo in loadext.html. check-in: 4efb429d19 user: drh tags: trunk
Clarify how the SQLITE_OK_LOAD_PERMANENTLY return value should be used. check-in: 8182293dd8 user: drh tags: trunk
Fix "asterix" typo in check-in: 569262e571 user: dan tags: trunk
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/

   263    263   [sqlite3_load_extension()] closes.  (In other words, the xDlUnload method 
   264    264   of the [sqlite3_vfs] object is called for all extensions when a database
   265    265   connection closes.)  However, if the initialization procedure returns
   266    266   [SQLITE_OK_LOAD_PERMANENTLY] instead of SQLITE_OK, then the extension will
   267    267   not be unloaded (xDlClose will not be invoked) and the extension will remain
   268    268   in process memory indefinitely.  The SQLITE_OK_LOAD_PERMANENTLY return
   269    269   value is useful for extensions that want to register new [VFSes].
          270  +
          271  +<p>To clarify: an extension for which the initialization function returns
          272  +SQLITE_OK_LOAD_PERMANENTLY continues to exist in memory after the database
          273  +connection closes.  However, the extension is <em>not</em> automatically
          274  +registered with subsequent database connections.  This make it possible
          275  +to load extensions that implement new [VFSes].
          276  +To persistently load and register an extension that implements new SQL
          277  +functions, collating sequences, and/or virtual tables, such that those
          278  +added capabilities are available to all subsequent database connections,
          279  +then the initialization routine should also invoke [sqlite3_auto_extension()]
          280  +on a subfunction that will register those services.
          281  +
          282  +<p>The [|vfsstat.c] extension
          283  +show an example of a loadable extension that persistently registers both
          284  +a new VFS and a new virtual table.  The
          285  +[|sqlite3_vfsstat_init()]
          286  +initialization routine in that extension is called only once, when the
          287  +extension is first loaded.  It registers the new "vfslog" VFS just that
          288  +one time, and it returns SQLITE_OK_LOAD_PERMANENTLY so that the code used
          289  +to implement the "vfslog" VFS will remain in memory. The initialization routine
          290  +also invokes [sqlite3_auto_extension()] on a pointer to the "vstatRegister()"
          291  +function so that all subsequent database connections will invoke the
          292  +"vstatRegister()" function as they start up, and hence register the
          293  +"vfsstat" virtual table.  
   270    294   
   271    295   <h1>Statically Linking A Run-Time Loadable Extension</h1>
   272    296   
   273    297   <p>The exact same source code can be used for both a run-time loadable
   274    298   shared library or DLL and as a module that is statically linked with your
   275    299   application.  This provides flexibility and allows you to reuse the same
   276    300   code in different ways.</p>
   292    316   connection separately, you might want to consider using the
   293    317   [sqlite3_auto_extension()] interface to register your extensions and
   294    318   to cause them to be automatically started as each database connection
   295    319   is opened.  You only have to register each extension once, and you can
   296    320   do so near the beginning of your main() routine.  Using the
   297    321   [sqlite3_auto_extension()] interface to register your extensions makes
   298    322   your extensions work as if they were built into the core SQLite - they
   299         -are automatically there whenever you open a new database connection
          323  +automatically exist whenever you open a new database connection
   300    324   without needing to be initialized.  Just be sure to complete any
   301    325   configuration you need to accomplish using [sqlite3_config()] before
   302    326   registering your extensions, since the [sqlite3_auto_extension()]
   303    327   interface implicitly calls [sqlite3_initialize()].</p>
   304    328   
   305    329   <h1>Implementation Details</h1>
   306    330