Documentation Source Text

Check-in [2c9d634cc9]
Login

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

Overview
Comment:Added a change log for 3.14.0. Updates for SQLITE_OK_LOAD_PERMANENTLY.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 2c9d634cc9f123c38c7205325949b0e44658dadb
User & Date: drh 2016-06-03 14:25:57.710
Context
2016-06-03
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)
14:21
Remove the disused btreemodule.html document. (check-in: 4650ddb4f7 user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/changes.in.
16
17
18
19
20
21
22















23
24
25
26
27
28
29
set nChng 0
proc chng {date desc {options {}}} {
  global nChng aChng xrefChng
  set aChng($nChng) [list $date $desc $options]
  set xrefChng($date) $nChng
  incr nChng
}
















chng {2016-05-18 (3.13.0)} {
<li>Postpone I/O associated with TEMP files for as long as possible, with the hope
    that the I/O can ultimately be avoided completely.
<li>Merged the [session] extension into trunk.
<li>Added the ".auth ON|OFF" command to the [command-line shell].
<li>Added the "--indent" option to the ".schema" and ".fullschema" commands of







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







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
set nChng 0
proc chng {date desc {options {}}} {
  global nChng aChng xrefChng
  set aChng($nChng) [list $date $desc $options]
  set xrefChng($date) $nChng
  incr nChng
}

chng {2016-07-00 (3.14.0)} {
<li>Added the csv.c loadable extensions, for reading CSV files.
<li>Enabled [persistent loadable extensions] using the new
    [SQLITE_OK_LOAD_PERMANENTLY] return code from the extension
    entry point.
<li>Add the vfsstat.c loadable extension - a VFS shim that measures I/O
    together with an [eponymous virtual table] that provides access to the measurements.
<li>Improved algorithm for running queries with both an ORDER BY and a LIMIT where
    only the inner-most loop naturally generates rows in the correct order.
<li>Enhancements to Lemon parser generator, so that it generates a
    faster parser.
<li>The [PRAGMA compile_options] command now attempts to show the version number
    of the compiler that generated the library.
}

chng {2016-05-18 (3.13.0)} {
<li>Postpone I/O associated with TEMP files for as long as possible, with the hope
    that the I/O can ultimately be avoided completely.
<li>Merged the [session] extension into trunk.
<li>Added the ".auth ON|OFF" command to the [command-line shell].
<li>Added the "--indent" option to the ".schema" and ".fullschema" commands of
Changes to pages/index.in.
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

</td>
<td width="20"></td><td bgcolor="#044a64" width="1"></td><td width="20"></td>
<td valign="top">
<h3>Current Status</h3>

<p><ul>
<li><a href="releaselog/3_13_0.html">Version 3.13.0</a>
of SQLite is recommended for all new development.
</li>
</ul></p>

<h3>Common Links</h3>

<p><ul>







|







106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

</td>
<td width="20"></td><td bgcolor="#044a64" width="1"></td><td width="20"></td>
<td valign="top">
<h3>Current Status</h3>

<p><ul>
<li><a href="releaselog/3_14_0.html">Version 3.14.0</a>
of SQLite is recommended for all new development.
</li>
</ul></p>

<h3>Common Links</h3>

<p><ul>
Changes to pages/loadext.in.
56
57
58
59
60
61
62

63
64
65
66
67
68
69
70
would be "sqlite3_mathfunc_init".  Or if the filename is 
"./SpellFixExt.dll" then the entry point would be called
"sqlite3_spellfixext_init".

<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 in your application.</p>

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

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







>
|







56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
would be "sqlite3_mathfunc_init".  Or if the filename is 
"./SpellFixExt.dll" then the entry point would be called
"sqlite3_spellfixext_init".

<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_db_config](db,[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION],1,NULL)
C-language API in your application.</p>

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

<blockquote><pre>
.load ./YourCode
</pre></blockquote>
210
211
212
213
214
215
216













217
218
219
220
221
222
223
</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>














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








>
>
>
>
>
>
>
>
>
>
>
>
>







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

Changes to pages/rescode.in.
352
353
354
355
356
357
358














359
360
361
362
363
364
365
RESCODE SQLITE_DONE        101  {
  The SQLITE_DONE result code indicates that an operation has completed.
  The SQLITE_DONE result code is most commonly seen as a return value
  from [sqlite3_step()] indicating that the SQL statement has run to
  completion.  But SQLITE_DONE can also be returned by other multi-step
  interfaces such as [sqlite3_backup_step()].
}














RESCODE SQLITE_IOERR_READ              {SQLITE_IOERR | (1<<8)} {
  The SQLITE_IOERR_READ error code is an [ext-v-prim|extended error code]
  for [SQLITE_IOERR] indicating an I/O error in the [VFS] layer
  while trying to read from a file on disk.  This error might result
  from a hardware malfunction or because a filesystem came unmounted
  while the file was open.
}







>
>
>
>
>
>
>
>
>
>
>
>
>
>







352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
RESCODE SQLITE_DONE        101  {
  The SQLITE_DONE result code indicates that an operation has completed.
  The SQLITE_DONE result code is most commonly seen as a return value
  from [sqlite3_step()] indicating that the SQL statement has run to
  completion.  But SQLITE_DONE can also be returned by other multi-step
  interfaces such as [sqlite3_backup_step()].
}
RESCODE SQLITE_OK_LOAD_PERMANENTLY     {SQLITE_OK | (1<<8)} {
  The [sqlite3_load_extension()] interface loads an 
  [loadable extension|extension] into a single
  database connection.  The default behavior is for that extension to be
  automatically unloaded when the database connection closes.  However,
  if the extension entry point returns SQLITE_OK_LOAD_PERMANENTLY instead
  of SQLITE_OK, then the extension remains loaded into the process address
  space after the database connection closes.  In other words, the
  xDlClose methods of the [sqlite3_vfs] object is not called for the
  extension when the database connection closes.
  <p>
  The SQLITE_OK_LOAD_PERMANENTLY return code is useful to 
  [loadable extensions] that register new [VFSes], for example.
}
RESCODE SQLITE_IOERR_READ              {SQLITE_IOERR | (1<<8)} {
  The SQLITE_IOERR_READ error code is an [ext-v-prim|extended error code]
  for [SQLITE_IOERR] indicating an I/O error in the [VFS] layer
  while trying to read from a file on disk.  This error might result
  from a hardware malfunction or because a filesystem came unmounted
  while the file was open.
}