Clarifications to the sqlite3_auto_extension() documentation.

FossilOrigin-Name: ca96e0df29cad4a9c7395a0acf623d8a19cb4725

manifest

@@ -1,8 +1,8 @@
 -----BEGIN PGP SIGNED MESSAGE-----
 Hash: SHA1
 
-C Updates\sto\sthe\sdocumentation\sfor\ssqlite3_create_collation().
+C Clarifications\sto\sthe\ssqlite3_auto_extension()\sdocumentation.
-D 2010-09-17T19:45:21
+D 2010-09-17T22:39:07
 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f
 F Makefile.in c599a15d268b1db2aeadea19df2adc3bf2eb6bee
 F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23
@@ -177,7 +177,7 @@ F src/resolve.c 1c0f32b64f8e3f555fe1f732f9d6f501a7f05706
 F src/rowset.c 69afa95a97c524ba6faf3805e717b5b7ae85a697
 F src/select.c b0b124781474e4e0c8f64022875e5e2009e13443
 F src/shell.c 8517fc1f9c59ae4007e6cc8b9af91ab231ea2056
-F src/sqlite.h.in 2f2eaf294f6ee8a4af855124478d4f9e6d5aa24e
+F src/sqlite.h.in dae3f74d7b2b516967ede39b8e503718b571d9da
 F src/sqlite3ext.h 69dfb8116af51b84a029cddb3b35062354270c89
 F src/sqliteInt.h ef7ed8746759c09edd87e5550de973a4da3e4ca7
 F src/sqliteLimit.h a17dcd3fb775d63b64a43a55c54cb282f9726f44
@@ -861,14 +861,14 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
 F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224
 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
 F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f
-P 2254e93bd5f70af5d3b2021983e4b826e601ee8f
+P 3df7715a7736867db34195aa8d98ba2e6f2f0b19
-R 68b354da71b9d657f6ac68c58c74ceab
+R c2a38a325f9b0b4d2db640cdead9cebc
 U drh
-Z 6e7a6eda418f1d79951195cf015cfb56
+Z 9267ea40a1ea692fd8921d30d881132a
 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.6 (GNU/Linux)
 
-iD8DBQFMk8VWoxKgR168RlERAg7eAJoCg5OlQpLAVvd2mAGXIMxyKruurgCfdbHR
+iD8DBQFMk+4OoxKgR168RlERAquRAKCGR23yodTYYljDy6W2xlqrC8Lo7wCfbrdi
-DOUZfuTIL/auG1NIwilR3cg=
+p+YicF7C2ROe1o9YtP1DHw4=
-=lDa/
+=hkFm
 -----END PGP SIGNATURE-----

manifest.uuid

@@ -1 +1 @@
-3df7715a7736867db34195aa8d98ba2e6f2f0b19
+ca96e0df29cad4a9c7395a0acf623d8a19cb4725

src/sqlite.h.in

@@ -4358,34 +4358,47 @@ int sqlite3_load_extension(
 int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
 
 /*
-** CAPI3REF: Automatically Load An Extensions
+** CAPI3REF: Automatically Load Statically Linked Extensions
 **
-** ^This API can be invoked at program startup in order to register
+** ^This interface causes the xEntryPoint() function to be invoked for
-** one or more statically linked extensions that will be available
+** each new [database connection] that is created.  The idea here is that
-** to all new [database connections].
+** xEntryPoint() is the entry point for a statically linked SQLite extension
+** that is to be automatically loaded into all new database connections.
 **
-** ^(This routine stores a pointer to the extension entry point
+** ^(Even though the function prototype shows that xEntryPoint() takes
-** in an array that is obtained from [sqlite3_malloc()].  That memory
+** no arguments and returns void, SQLite invokes xEntryPoint() with three
-** is deallocated by [sqlite3_reset_auto_extension()].)^
+** arguments and expects and integer result as if the signature of the
+** entry point where as follows:
 **
-** ^This function registers an extension entry point that is
+** <blockquote><pre>
-** automatically invoked whenever a new [database connection]
+** &nbsp;  int xEntryPoint(
-** is opened using [sqlite3_open()], [sqlite3_open16()],
+** &nbsp;    sqlite3 *db,
-** or [sqlite3_open_v2()].
+** &nbsp;    const char **pzErrMsg,
-** ^Duplicate extensions are detected so calling this routine
+** &nbsp;    const struct sqlite3_api_routines *pThunk
-** multiple times with the same extension is harmless.
+** &nbsp;  );
-** ^Automatic extensions apply across all threads.
+** </pre></blockquote>)^
+**
+** If the xEntryPoint routine encounters an error, it should make *pzErrMsg
+** point to an appropriate error message (obtained from [sqlite3_mprintf()])
+** and return an appropriate [error code].  ^SQLite ensures that *pzErrMsg
+** is NULL before calling the xEntryPoint().  ^SQLite will invoke
+** [sqlite3_free()] on *pzErrMsg after xEntryPoint() returns.  ^If any
+** xEntryPoint() returns an error, the [sqlite3_open()], [sqlite3_open16()],
+** or [sqlite3_open_v2()] call that provoked the xEntryPoint() will fail.
+**
+** ^Calling sqlite3_auto_extension(X) with an entry point X that is already
+** on the list of automatic extensions is a harmless no-op. ^No entry point
+** will be called more than once for each database connection that is opened.
+**
+** See also: [sqlite3_reset_auto_extension()].
 */
 int sqlite3_auto_extension(void (*xEntryPoint)(void));
 
 /*
 ** CAPI3REF: Reset Automatic Extension Loading
 **
-** ^(This function disables all previously registered automatic
+** ^This interface disables all automatic extensions previously
-** extensions. It undoes the effect of all prior
+** registered using [sqlite3_auto_extension()].
-** [sqlite3_auto_extension()] calls.)^
-**
-** ^This function disables automatic extensions in all threads.
 */
 void sqlite3_reset_auto_extension(void);