Debian Codegraph @

www/c3ref/c_deterministic.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="../sqlite.css" rel="stylesheet">
6 <title>Function Flags</title>
7 <!-- path=../ -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="../index.html">
12 <img class="logo" src="../images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="../index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='../about.html'>About</a>
23 <li class='desktoponly'><a href="../docs.html">Documentation</a>
24 <li class='desktoponly'><a href="../download.html">Download</a>
25 <li class='wideonly'><a href='../copyright.html'>License</a>
26 <li class='desktoponly'><a href="../support.html">Support</a>
27 <li class='desktoponly'><a href="../prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='../about.html'>About</a>
35 <li><a href='../docs.html'>Documentation</a>
36 <li><a href='../download.html'>Download</a>
37 <li><a href='../support.html'>Support</a>
38 <li><a href='../prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="../search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <!-- keywords: SQLITE_DETERMINISTIC SQLITE_DIRECTONLY SQLITE_INNOCUOUS SQLITE_RESULT_SUBTYPE SQLITE_SELFORDER1 SQLITE_SUBTYPE -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Function Flags</h2>
122 </div>
123 <blockquote><pre>
124 #define SQLITE_DETERMINISTIC 0x000000800
125 #define SQLITE_DIRECTONLY 0x000080000
126 #define SQLITE_SUBTYPE 0x000100000
127 #define SQLITE_INNOCUOUS 0x000200000
128 #define SQLITE_RESULT_SUBTYPE 0x001000000
129 #define SQLITE_SELFORDER1 0x002000000
130 </pre></blockquote>
131 <p>
132 These constants may be ORed together with the
133 <a href="../c3ref/c_any.html#sqliteutf8">preferred text encoding</a> as the fourth argument
134 to <a href="../c3ref/create_function.html">sqlite3_create_function()</a>, <a href="../c3ref/create_function.html">sqlite3_create_function16()</a>, or
135 <a href="../c3ref/create_function.html">sqlite3_create_function_v2()</a>.</p>
136
137 <p><dl>
138 <a name="sqlitedeterministic"></a>
139 <dt>SQLITE_DETERMINISTIC</dt><dd>
140 The SQLITE_DETERMINISTIC flag means that the new function always gives
141 the same output when the input parameters are the same.
142 The <a href="../lang_corefunc.html#abs">abs() function</a> is deterministic, for example, but
143 <a href="../lang_corefunc.html#randomblob">randomblob()</a> is not. Functions must
144 be deterministic in order to be used in certain contexts such as
145 with the WHERE clause of <a href="../partialindex.html">partial indexes</a> or in <a href="../gencol.html">generated columns</a>.
146 SQLite might also optimize deterministic functions by factoring them
147 out of inner loops.
148 </dd></p>
149
150 <p><a name="sqlitedirectonly"></a>
151 <dt>SQLITE_DIRECTONLY</dt><dd>
152 The SQLITE_DIRECTONLY flag means that the function may only be invoked
153 from top-level SQL, and cannot be used in VIEWs or TRIGGERs nor in
154 schema structures such as <a href="../lang_createtable.html#ckconst">CHECK constraints</a>, <a href="../lang_createtable.html#dfltval">DEFAULT clauses</a>,
155 <a href="../expridx.html">expression indexes</a>, <a href="../partialindex.html">partial indexes</a>, or <a href="../gencol.html">generated columns</a>.
156 <p>
157 The SQLITE_DIRECTONLY flag is recommended for any
158 <a href="../appfunc.html">application-defined SQL function</a>
159 that has side-effects or that could potentially leak sensitive information.
160 This will prevent attacks in which an application is tricked
161 into using a database file that has had its schema surreptitiously
162 modified to invoke the application-defined function in ways that are
163 harmful.
164 <p>
165 Some people say it is good practice to set SQLITE_DIRECTONLY on all
166 <a href="../appfunc.html">application-defined SQL functions</a>, regardless of whether or not they
167 are security sensitive, as doing so prevents those functions from being used
168 inside of the database schema, and thus ensures that the database
169 can be inspected and modified using generic tools (such as the <a href="../cli.html">CLI</a>)
170 that do not have access to the application-defined functions.
171 </dd></p>
172
173 <p><a name="sqliteinnocuous"></a>
174 <dt>SQLITE_INNOCUOUS</dt><dd>
175 The SQLITE_INNOCUOUS flag means that the function is unlikely
176 to cause problems even if misused. An innocuous function should have
177 no side effects and should not depend on any values other than its
178 input parameters. The <a href="../lang_corefunc.html#abs">abs() function</a> is an example of an
179 innocuous function.
180 The <a href="../lang_corefunc.html#load_extension">load_extension() SQL function</a> is not innocuous because of its
181 side effects.
182 <p> SQLITE_INNOCUOUS is similar to SQLITE_DETERMINISTIC, but is not
183 exactly the same. The <a href="../lang_corefunc.html#random">random() function</a> is an example of a
184 function that is innocuous but not deterministic.
185 <p>Some heightened security settings
186 (<a href="../c3ref/c_dbconfig_defensive.html#sqlitedbconfigtrustedschema">SQLITE_DBCONFIG_TRUSTED_SCHEMA</a> and <a href="../pragma.html#pragma_trusted_schema">PRAGMA trusted_schema=OFF</a>)
187 disable the use of SQL functions inside views and triggers and in
188 schema structures such as <a href="../lang_createtable.html#ckconst">CHECK constraints</a>, <a href="../lang_createtable.html#dfltval">DEFAULT clauses</a>,
189 <a href="../expridx.html">expression indexes</a>, <a href="../partialindex.html">partial indexes</a>, and <a href="../gencol.html">generated columns</a> unless
190 the function is tagged with SQLITE_INNOCUOUS. Most built-in functions
191 are innocuous. Developers are advised to avoid using the
192 SQLITE_INNOCUOUS flag for application-defined functions unless the
193 function has been carefully audited and found to be free of potentially
194 security-adverse side-effects and information-leaks.
195 </dd></p>
196
197 <p><a name="sqlitesubtype"></a>
198 <dt>SQLITE_SUBTYPE</dt><dd>
199 The SQLITE_SUBTYPE flag indicates to SQLite that a function might call
200 <a href="../c3ref/value_subtype.html">sqlite3_value_subtype()</a> to inspect the sub-types of its arguments.
201 This flag instructs SQLite to omit some corner-case optimizations that
202 might disrupt the operation of the <a href="../c3ref/value_subtype.html">sqlite3_value_subtype()</a> function,
203 causing it to return zero rather than the correct subtype().
204 All SQL functions that invoke <a href="../c3ref/value_subtype.html">sqlite3_value_subtype()</a> should have this
205 property. If the SQLITE_SUBTYPE property is omitted, then the return
206 value from <a href="../c3ref/value_subtype.html">sqlite3_value_subtype()</a> might sometimes be zero even though
207 a non-zero subtype was specified by the function argument expression.</p>
208
209 <p><a name="sqliteresultsubtype"></a>
210 <dt>SQLITE_RESULT_SUBTYPE</dt><dd>
211 The SQLITE_RESULT_SUBTYPE flag indicates to SQLite that a function might call
212 <a href="../c3ref/result_subtype.html">sqlite3_result_subtype()</a> to cause a sub-type to be associated with its
213 result.
214 Every function that invokes <a href="../c3ref/result_subtype.html">sqlite3_result_subtype()</a> should have this
215 property. If it does not, then the call to <a href="../c3ref/result_subtype.html">sqlite3_result_subtype()</a>
216 might become a no-op if the function is used as a term in an
217 <a href="../expridx.html">expression index</a>. On the other hand, SQL functions that never invoke
218 <a href="../c3ref/result_subtype.html">sqlite3_result_subtype()</a> should avoid setting this property, as the
219 purpose of this property is to disable certain optimizations that are
220 incompatible with subtypes.</p>
221
222 <p><a name="sqliteselforder1"></a>
223 <dt>SQLITE_SELFORDER1</dt><dd>
224 The SQLITE_SELFORDER1 flag indicates that the function is an aggregate
225 that internally orders the values provided to the first argument. The
226 ordered-set aggregate SQL notation with a single ORDER BY term can be
227 used to invoke this function. If the ordered-set aggregate notation is
228 used on a function that lacks this flag, then an error is raised. Note
229 that the ordered-set aggregate syntax is only available if SQLite is
230 built using the -DSQLITE_ENABLE_ORDERED_SET_AGGREGATES compile-time option.
231 </dd>
232 </dl>
233 </p><p>See also lists of
234 <a href="../c3ref/objlist.html">Objects</a>,
235 <a href="../c3ref/constlist.html">Constants</a>, and
236 <a href="../c3ref/funclist.html">Functions</a>.</p>
237