Documentation Source Text

Check-in [3f0e846a97]
Login

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

Overview
Comment:Improvements to the carray() function documentation.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 3f0e846a9799a111086ddc2646a38ae0c209f831
User & Date: drh 2016-07-13 00:55:44.714
Context
2016-07-13
01:00
Fix formatting on the CVS virtual table documentation. (check-in: 60e2c7225d user: drh tags: trunk)
00:55
Improvements to the carray() function documentation. (check-in: 3f0e846a97 user: drh tags: trunk)
2016-07-12
23:52
Add the <fancy_format> markup which works like <table_of_contents> but omits the actual table of contents. Begin writing documentation for the carray() function. Fix typos and adjust wording in the CLI document. (check-in: e89a552dc3 user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/carray.in.
︙︙
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




<h1>Availability</h1>

<p>The carray() function is not compiled into SQLite by default.
It is available as a [loadable extension] in the
[https://www.sqlite.org/src/artifact?ci=trunk&filename=ext/misc/carray.c|ext/misc/carray.c]
source file.

<p>The carray() function is a little dangerous.  The first parameter is
a 64-bit integer which gets cast into a pointer to an array.  In an
application that runs user-generated or untrusted SQL, the carray()
function could be used to crash the appliation or to leak sensitive 
information that the user is not suppose to have access to.  For that
reason, the carray() function will never be a standard part of SQLite.
In that way, carray() will only be available in applications that 
deliberately request it, and which therefore presumably have protections

in place to prevent misuse.

<h1>Details</h1>

<p>The carray() function takes two or three arguments.
The first argument is a 64-bit integer that will be cast into a pointer
to the C-language array that is to be returned by the function.  The
second argument is the number of elements in the array.  The optional
third argument is a string that determines the datatype of the elements
in the C-language array.  Allowed values for the third argument are:

<ol>
<li> 'int32'
<li> 'int64'
<li> 'double'
<li> 'char*'
</ol>

<p>The default datatype is 'int32'.




<h1>Example Usage</h1>






<i>TBD...</i>











|



|

|
|
>
|



















>
>
>
|
>
>
>
>

>
|
>
>
>

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

<h1>Availability</h1>

<p>The carray() function is not compiled into SQLite by default.
It is available as a [loadable extension] in the
[https://www.sqlite.org/src/artifact?ci=trunk&filename=ext/misc/carray.c|ext/misc/carray.c]
source file.

<p>The carray() function is dangerous.  The first parameter is
a 64-bit integer which gets cast into a pointer to an array.  In an
application that runs user-generated or untrusted SQL, the carray()
function could be used to crash the appliation or to leak sensitive 
information.  For that
reason, the carray() function will never be a standard part of SQLite.
Carray() will only be available in applications that 
deliberately request it.  Presumably, applications that deliberately
link carray() will also have protections in place to prevent carray()
from being misused.

<h1>Details</h1>

<p>The carray() function takes two or three arguments.
The first argument is a 64-bit integer that will be cast into a pointer
to the C-language array that is to be returned by the function.  The
second argument is the number of elements in the array.  The optional
third argument is a string that determines the datatype of the elements
in the C-language array.  Allowed values for the third argument are:

<ol>
<li> 'int32'
<li> 'int64'
<li> 'double'
<li> 'char*'
</ol>

<p>The default datatype is 'int32'.

<p>The carray() function can be used in the FROM clause of a query.
For example, to query two entries from the OBJ table using rowids
taken from a C-language array at address 0x7b3830:

<codeblock>
SELECT obj.* FROM obj, carray(0x7b3830, 10) AS x
 WHERE obj.rowid=x.value;
</codeblock>

<p>This query gives the same result:

<codeblock>
SELECT * FROM obj WHERE rowid IN carray(0x7b3830, 10);
</codeblock>