Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Convert the loadext.html page to the pretty-format. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
899d627a5adafb0565c128cb918c17f9 |
User & Date: | drh 2016-06-03 15:19:33.099 |
Context
2016-06-03
| ||
22:40 | Documentation on WITHOUT ROWID virtual tables and the LIKE OR EQUAL optimization for virtual tables. (check-in: 01b8f2aa54 user: drh tags: trunk) | |
15:19 | Convert the loadext.html page to the pretty-format. (check-in: 899d627a5a user: drh tags: trunk) | |
14:25 | Added a change log for 3.14.0. Updates for SQLITE_OK_LOAD_PERMANENTLY. (check-in: 2c9d634cc9 user: drh tags: trunk) | |
Changes
Changes to pages/loadext.in.
1 2 3 4 5 6 | <title>Run-Time Loadable Extensions</title> <tcl>hd_keywords {loadext} {loadable extensions} {extension loading} \ {SQLite extension} {SQLite extensions} \ {loadable extension} \ {Run-Time Loadable Extensions}</tcl> | > | > | | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 | <title>Run-Time Loadable Extensions</title> <tcl>hd_keywords {loadext} {loadable extensions} {extension loading} \ {SQLite extension} {SQLite extensions} \ {loadable extension} \ {Run-Time Loadable Extensions}</tcl> <table_of_contents> <h1>Overview</h1> <p>SQLite has the ability to load extensions (including new [application-defined SQL functions], [collating sequences], [virtual tables], and [VFSes]) at run-time. This feature allows the code for extensions to be developed and tested separately from the application and then loaded on an as-needed basis.</p> <p>Extensions can also be statically linked with the application. The code template shown below will work just as well as a statically linked extension as it does as a run-time loadable extension except that you should give the entry point function ("sqlite3_extension_init") a different name to avoid name collisions if your application contains two or more extensions.</p> <h1>Loading An Extension</h1> <p>An SQLite extension is a shared library or DLL. To load it, you need to supply SQLite with the name of the file containing the shared library or DLL and an entry point to initialize the extension. In C code, this information is supplied using the [sqlite3_load_extension()] API. See the documentation on that routine for additional information.</p> |
︙ | ︙ | |||
84 85 86 87 88 89 90 | <blockquote><pre> .load ./YourCode nonstandard_entry_point </pre></blockquote> <tcl>hd_fragment build {Compiling Loadable Extensions} \ {compile loadable extensions}</tcl> | | | 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 | <blockquote><pre> .load ./YourCode nonstandard_entry_point </pre></blockquote> <tcl>hd_fragment build {Compiling Loadable Extensions} \ {compile loadable extensions}</tcl> <h1>Compiling A Loadable Extension</h1> <p>Loadable extensions are C-code. To compile them on most unix-like operating systems, the usual command is something like this:</p> <blockquote><pre> gcc -g -fPIC -shared YourCode.c -o YourCode.so |
︙ | ︙ | |||
123 124 125 126 127 128 129 | the -fPIC argument is omitted:</p> <blockquote><pre> gcc -g -shared YourCode.c -o YourCode.dll </pre></blockquote> <tcl>hd_fragment write {Programming Loadable Extensions}</tcl> | | > | | | > > | < | 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 | the -fPIC argument is omitted:</p> <blockquote><pre> gcc -g -shared YourCode.c -o YourCode.dll </pre></blockquote> <tcl>hd_fragment write {Programming Loadable Extensions}</tcl> <h1>Programming Loadable Extensions</h1> <p>A template loadable extension contains the following three elements:</p> <ol> <li><p> Use "<tt>#include <sqlite3ext.h></tt>" at the top of your source code files instead of "<tt>#include <sqlite3.h></tt>". </p> <li><p> Put the macro "<tt>SQLITE_EXTENSION_INIT1</tt>" on a line by itself right after the "<tt>#include <sqlite3ext.h></tt>" line. </p> <li><p> Add an extension loading entry point routine that looks like something the following: <codeblock> #ifdef _WIN32 __declspec(dllexport) #endif int sqlite3_extension_init( /* <== Change this name, maybe */ sqlite3 *db, char **pzErrMsg, const sqlite3_api_routines *pApi ){ int rc = SQLITE_OK; SQLITE_EXTENSION_INIT2(pApi); /* insert code to initialize your extension here */ return rc; } </codeblock> <p>You will do well to customize the name of your entry point to correspond to the name of the shared library you will be generating, rather than using the generic "sqlite3_extension_init" name. Giving your extension a custom entry point name will enable you to statically link two or more extensions into the same program without a linker conflict, if you later decide to use static linking rather than run-time linking. If your shared library ends up being named "YourCode.so" or "YourCode.dll" or "YourCode.dylib" as shown in the compiler examples above, then the correct entry point name would be "sqlite3_yourcode_init". </ol> <p>Here is a complete template extension that you can copy/paste to get started:</p> <codeblock> /* Add your header comment here */ #include <sqlite3ext.h> /* Do not use <sqlite3.h>! */ SQLITE_EXTENSION_INIT1 /* Insert your extension code here */ #ifdef _WIN32 |
︙ | ︙ | |||
204 205 206 207 208 209 210 | ** sqlite3_create_collation_v2(), ** sqlite3_create_module_v2(), and/or ** sqlite3_vfs_register() ** to register the new features that your extension adds. */ return rc; } | | | | | 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 | ** sqlite3_create_collation_v2(), ** sqlite3_create_module_v2(), and/or ** sqlite3_vfs_register() ** to register the new features that your extension adds. */ return rc; } </codeblock> <p>Many examples of complete and working loadable extensions can be seen in the SQLite source tree in the <a href="http://www.sqlite.org/src/tree?name=ext/misc&ci=trunk">ext/misc</a> subdirectory.</p> <tcl>hd_fragment persist {persistent loadable extensions}</tcl> <h1>Persistent Loadable Extensions</h1> <p>The default behavior for a loadable extension is that it is unloaded from process memory when the database connection that orginally invoked [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> <p>To statically link your extension, simply add the -DSQLITE_CORE |
︙ | ︙ | |||
258 259 260 261 262 263 264 | 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> | | | 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 | 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> <p>SQLite implements run-time extension loading using the xDlOpen(), xDlError(), xDlSym(), and xDlClose() methods of the [sqlite3_vfs] object. These methods are implemented using the dlopen() library on unix (which explains why SQLite commonly need to be linked against the "-ldl" library on unix systems) and using LoadLibrary() API on Windows. In a custom [VFS] for |
︙ | ︙ |