/ Check-in [ca96e0df]
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

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

Overview
Comment:Clarifications to the sqlite3_auto_extension() documentation.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: ca96e0df29cad4a9c7395a0acf623d8a19cb4725
User & Date: drh 2010-09-17 22:39:07
Context
2010-09-18
15:03
Add tests to e_select.test. check-in: 0ee9e755 user: dan tags: trunk
2010-09-17
22:39
Clarifications to the sqlite3_auto_extension() documentation. check-in: ca96e0df user: drh tags: trunk
19:45
Updates to the documentation for sqlite3_create_collation(). check-in: 3df7715a user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

  4354   4354   ** ^Call the sqlite3_enable_load_extension() routine with onoff==1
  4355   4355   ** to turn extension loading on and call it with onoff==0 to turn
  4356   4356   ** it back off again.
  4357   4357   */
  4358   4358   int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
  4359   4359   
  4360   4360   /*
  4361         -** CAPI3REF: Automatically Load An Extensions
  4362         -**
  4363         -** ^This API can be invoked at program startup in order to register
  4364         -** one or more statically linked extensions that will be available
  4365         -** to all new [database connections].
  4366         -**
  4367         -** ^(This routine stores a pointer to the extension entry point
  4368         -** in an array that is obtained from [sqlite3_malloc()].  That memory
  4369         -** is deallocated by [sqlite3_reset_auto_extension()].)^
  4370         -**
  4371         -** ^This function registers an extension entry point that is
  4372         -** automatically invoked whenever a new [database connection]
  4373         -** is opened using [sqlite3_open()], [sqlite3_open16()],
  4374         -** or [sqlite3_open_v2()].
  4375         -** ^Duplicate extensions are detected so calling this routine
  4376         -** multiple times with the same extension is harmless.
  4377         -** ^Automatic extensions apply across all threads.
         4361  +** CAPI3REF: Automatically Load Statically Linked Extensions
         4362  +**
         4363  +** ^This interface causes the xEntryPoint() function to be invoked for
         4364  +** each new [database connection] that is created.  The idea here is that
         4365  +** xEntryPoint() is the entry point for a statically linked SQLite extension
         4366  +** that is to be automatically loaded into all new database connections.
         4367  +**
         4368  +** ^(Even though the function prototype shows that xEntryPoint() takes
         4369  +** no arguments and returns void, SQLite invokes xEntryPoint() with three
         4370  +** arguments and expects and integer result as if the signature of the
         4371  +** entry point where as follows:
         4372  +**
         4373  +** <blockquote><pre>
         4374  +** &nbsp;  int xEntryPoint(
         4375  +** &nbsp;    sqlite3 *db,
         4376  +** &nbsp;    const char **pzErrMsg,
         4377  +** &nbsp;    const struct sqlite3_api_routines *pThunk
         4378  +** &nbsp;  );
         4379  +** </pre></blockquote>)^
         4380  +**
         4381  +** If the xEntryPoint routine encounters an error, it should make *pzErrMsg
         4382  +** point to an appropriate error message (obtained from [sqlite3_mprintf()])
         4383  +** and return an appropriate [error code].  ^SQLite ensures that *pzErrMsg
         4384  +** is NULL before calling the xEntryPoint().  ^SQLite will invoke
         4385  +** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns.  ^If any
         4386  +** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()],
         4387  +** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail.
         4388  +**
         4389  +** ^Calling sqlite3_auto_extension(X) with an entry point X that is already
         4390  +** on the list of automatic extensions is a harmless no-op. ^No entry point
         4391  +** will be called more than once for each database connection that is opened.
         4392  +**
         4393  +** See also: [sqlite3_reset_auto_extension()].
  4378   4394   */
  4379   4395   int sqlite3_auto_extension(void (*xEntryPoint)(void));
  4380   4396   
  4381   4397   /*
  4382   4398   ** CAPI3REF: Reset Automatic Extension Loading
  4383   4399   **
  4384         -** ^(This function disables all previously registered automatic
  4385         -** extensions. It undoes the effect of all prior
  4386         -** [sqlite3_auto_extension()] calls.)^
  4387         -**
  4388         -** ^This function disables automatic extensions in all threads.
         4400  +** ^This interface disables all automatic extensions previously
         4401  +** registered using [sqlite3_auto_extension()].
  4389   4402   */
  4390   4403   void sqlite3_reset_auto_extension(void);
  4391   4404   
  4392   4405   /*
  4393   4406   ** The interface to the virtual-table mechanism is currently considered
  4394   4407   ** to be experimental.  The interface might change in incompatible ways.
  4395   4408   ** If this is a problem for you, do not use the interface at this time.