Documentation Source Text

Check-in [899d627a5a]
Login

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

Overview
Comment:Convert the loadext.html page to the pretty-format.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 899d627a5adafb0565c128cb918c17f920990b01
User & Date: drh 2016-06-03 15:19:33
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
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/loadext.in.

1
2
3
4
5
6
7


8
9
10
11
12
13
14
..
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
..
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
...
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
...
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
...
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
...
204
205
206
207
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
...
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
<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>

<h1 align="center">Run-Time Loadable Extensions</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>

<h2>Loading An Extension</h2>

<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>
................................................................................

<blockquote><pre>
.load ./YourCode nonstandard_entry_point
</pre></blockquote>

<tcl>hd_fragment build {Compiling Loadable Extensions} \
                 {compile loadable extensions}</tcl>
<h2>Compiling A Loadable Extension</h2>

<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
................................................................................
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>
<h2>Programming Loadable Extensions</h2>

<p>A template loadable extension contains the following three elements:</p>

<ol>
<li><p>
Use "<tt>#include &lt;sqlite3ext.h&gt;</tt>" at the top of your source
code files instead of "<tt>#include &lt;sqlite3.h&gt;</tt>".
................................................................................
Put the macro "<tt>SQLITE_EXTENSION_INIT1</tt>" on a line by itself 
right after the "<tt>#include &lt;sqlite3ext.h&gt;</tt>" line.
</p>

<li><p>
Add an extension loading entry point routine that looks like 
something the following:
<blockquote><pre>

#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;
}
</pre></blockquote>

<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.
................................................................................
"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>
<blockquote>
<pre style="background-color:#f3f3f3;border:1px #000 dashed;padding:0.5em">
/* Add your header comment here */
#include &lt;sqlite3ext.h&gt; /* Do not use &lt;sqlite3.h&gt;! */
SQLITE_EXTENSION_INIT1

/* Insert your extension code here */

#ifdef _WIN32
................................................................................
  **     sqlite3_create_collation_v2(),
  **     sqlite3_create_module_v2(), and/or
  **     sqlite3_vfs_register()
  ** to register the new features that your extension adds.
  */
  return rc;
}
</pre></blockquote>

<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>
<h2>Persistent Loadable Extensions</h2>

<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].

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

<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
................................................................................
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>

<h2>Implementation Details</h2>

<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






|
>
>







 







|







 







|







 







|







 







|
>



|









|
>







 







|
|







 







|







|











|







 







|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
..
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
..
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
...
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
...
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
...
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
...
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
...
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
<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>
................................................................................

<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
................................................................................
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 &lt;sqlite3ext.h&gt;</tt>" at the top of your source
code files instead of "<tt>#include &lt;sqlite3.h&gt;</tt>".
................................................................................
Put the macro "<tt>SQLITE_EXTENSION_INIT1</tt>" on a line by itself 
right after the "<tt>#include &lt;sqlite3ext.h&gt;</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( /* &lt;== 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.
................................................................................
"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 &lt;sqlite3ext.h&gt; /* Do not use &lt;sqlite3.h&gt;! */
SQLITE_EXTENSION_INIT1

/* Insert your extension code here */

#ifdef _WIN32
................................................................................
  **     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
................................................................................
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