Documentation Source Text

Check-in [6da9f893bc]
Login

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

Overview
Comment:Add a documentation page describing how to write run-time loadable extensions.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 6da9f893bca0f8fb4a6cf96b625520298645a6f4
User & Date: drh 2013-04-17 12:58:02.654
Context
2013-04-17
13:35
Fix a coordinate error in the RTree documentation. (check-in: 600d427573 user: drh tags: trunk)
12:58
Add a documentation page describing how to write run-time loadable extensions. (check-in: 6da9f893bc user: drh tags: trunk)
2013-04-16
13:57
Fix typos in new documents. (check-in: 224d684b8b user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/datatype3.in.
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491

<p>^The compound SELECT operators UNION,
INTERSECT and EXCEPT perform implicit comparisons between values.
^No affinity is applied to comparison operands for the implicit
comparisons associated with UNION, INTERSECT, or EXCEPT - the values
are compared as is.</p>

<tcl>hd_fragment collation {*collating sequence} \
                 {collating function} *collation *BINARY *NOCASE *RTRIM \
        {BINARY collating function} \
        {NOCASE collating function} \
        {RTRIM collating function}</tcl>
<h2>6.0 Collating Sequences</h2>

<p>^When SQLite compares two strings, it uses a collating sequence or







|







477
478
479
480
481
482
483
484
485
486
487
488
489
490
491

<p>^The compound SELECT operators UNION,
INTERSECT and EXCEPT perform implicit comparisons between values.
^No affinity is applied to comparison operands for the implicit
comparisons associated with UNION, INTERSECT, or EXCEPT - the values
are compared as is.</p>

<tcl>hd_fragment collation {*collating sequence} {*collating sequences}\
                 {collating function} *collation *BINARY *NOCASE *RTRIM \
        {BINARY collating function} \
        {NOCASE collating function} \
        {RTRIM collating function}</tcl>
<h2>6.0 Collating Sequences</h2>

<p>^When SQLite compares two strings, it uses a collating sequence or
Changes to pages/lang.in.
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
  to override both the two and three argument versions of the like() 
  function. Otherwise, different code may be called to implement the
  [LIKE] operator depending on whether or not an ESCAPE clause was 
  specified.
}

funcdef {load_extension(X) load_extension(X,Y)} {} {
  ^The load_extension(X,Y) function loads SQLite extensions out of the shared
  library file named X using the entry point Y.  ^The result of load_extension()
  is always a NULL.  ^If Y is omitted then the default entry point
  of <b>sqlite3_extension_init</b> is used.  ^The load_extension() function
  raises an exception if the extension fails to load or initialize correctly.

  <p>^The load_extension() function will fail if the extension attempts to 
  modify or delete an SQL function or collating sequence.  ^The







|







2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
  to override both the two and three argument versions of the like() 
  function. Otherwise, different code may be called to implement the
  [LIKE] operator depending on whether or not an ESCAPE clause was 
  specified.
}

funcdef {load_extension(X) load_extension(X,Y)} {} {
  ^The load_extension(X,Y) function loads [SQLite extensions] out of the shared
  library file named X using the entry point Y.  ^The result of load_extension()
  is always a NULL.  ^If Y is omitted then the default entry point
  of <b>sqlite3_extension_init</b> is used.  ^The load_extension() function
  raises an exception if the extension fails to load or initialize correctly.

  <p>^The load_extension() function will fail if the extension attempts to 
  modify or delete an SQL function or collating sequence.  ^The
Added pages/loadext.in.






































































































































































































































































>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
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
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
<title>Run-Time Loadable Extensions</title>
<tcl>hd_keywords {loadext} {loadable extensions} {extension loading} \
                 {SQLite extension} {SQLite 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 might want to 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.
At the lowest level, this information is supplied using the
[sqlite3_load_extension()] API.</p>

<p>There is also an SQL function that can be used to load extensions:
[load_extension(X,Y)].  The entry point name, Y, is optional and if
omitted defaults to "sqlite3_extension_init".</p>

<p>For security reasons, extension loading is turned off by default.
In order to use either the C-language or SQL extension loading functions,
one must first enable extension loading using the
[sqlite3_enable_load_extension()] C-language API.</p>

<p>From the [command-line shell], extensions can be loaded using the
".load" dot-command.  For example:

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

<p>As with the load_extension() SQL function, the entry point defaults
to "sqlite3_extension_init" unless an alternative name if given as
the second argument to ".load".</p>

<tcl>hd_fragment build {Compiling Loadable Extensions}</tcl>
<h2>Compiling A Loadable Extension</h2>

<p>Loadable extensions are C-code.  To compile them on unix-like operating
systems, the usual command is something like this:</p>

<blockquote><pre>
gcc -g -fPIC -shared YourCode.c -o YourCode.so
</pre></blockquote>

<p>To compile on Windows using MSVC, a command similar to the following
will usually work:</p>

<blockquote><pre>
cl YourCode.c -link -dll -out:YourCode.dll -export:sqlite3_extension_init
</blockquote></pre>

<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>".
</p>

<li><p>
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 the following:
<blockquote><pre>
#ifdef _WIN32
__declspec(dllexport)
#endif
int sqlite3_extension_init(
  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>
</ol>

<p>Here is a complete template extension that you can copy/paste 
to get started:</p>
<hr>
<pre>
/* Add your header comment here */
#include &lt;sqlite3ext.h&gt; /* Do not use &lt;sqlite3.h&gt;! */
SQLITE_EXTENSION_INIT1

/* Insert here code to implement your extension */

#ifdef _WIN32
__declspec(dllexport)
#endif
int sqlite3_extension_init(
  sqlite3 *db, 
  char **pzErrMsg, 
  const sqlite3_api_routines *pApi
){
  int rc = SQLITE_OK;
  SQLITE_EXTENSION_INIT2(pApi);
  /* Insert here calls to
  **     sqlite3_create_function_v2(),
  **     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>
<hr>
Changes to schema.tcl.
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
  );
  CREATE INDEX IF NOT EXISTS fragment_pageid ON fragment(pageid);
  
  /*
  ** Keywords used to identify link targets.
  */
  CREATE TABLE IF NOT EXISTS keyword(
    kwid INTEGER PRIMARY KEY,             -- ID  for internal use only
    kw TEXT UNIQUE NOT NULL,              -- The keyword or keyphrase
    indexKw BOOLEAN NOT NULL,             -- Show in the keyword doc index
    fragment TEXT                         -- Fragment keyword refers to
  );
  
  /*
  ** Each row in this table records a hyperlink to a keyword.  The
  ** source and destination of the hyperlink are recorded.
  */
  CREATE TABLE IF NOT EXISTS link(







|
|
|
|







32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
  );
  CREATE INDEX IF NOT EXISTS fragment_pageid ON fragment(pageid);
  
  /*
  ** Keywords used to identify link targets.
  */
  CREATE TABLE IF NOT EXISTS keyword(
    kwid INTEGER PRIMARY KEY,                -- ID  for internal use only
    kw TEXT UNIQUE NOT NULL COLLATE nocase,  -- The keyword or keyphrase
    indexKw BOOLEAN NOT NULL,                -- Show in the keyword doc index
    fragment TEXT                            -- Fragment keyword refers to
  );
  
  /*
  ** Each row in this table records a hyperlink to a keyword.  The
  ** source and destination of the hyperlink are recorded.
  */
  CREATE TABLE IF NOT EXISTS link(