PageRenderTime 68ms CodeModel.GetById 30ms RepoModel.GetById 1ms app.codeStats 2ms

/doc/html/sqlite-3_87_81_2sqlite3_8h_source.html

https://bitbucket.org/iesahin/otapexplorer
HTML | 4536 lines | 4534 code | 0 blank | 2 comment | 0 complexity | 0183545ee161c07d48aeb41a8cb948b8 MD5 | raw file
Possible License(s): BSD-3-Clause 
    

  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    2. 

  2. <html xmlns="http://www.w3.org/1999/xhtml">
    3. 

  3. <head>
    4. 

  4. <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
    5. 

  5. <title>OTAP: cli/sqlite-3.7.1/sqlite3.h Source File</title>
    6. 

  6. <link href="tabs.css" rel="stylesheet" type="text/css"/>
    7. 

  7. <link href="search/search.css" rel="stylesheet" type="text/css"/>
    8. 

  8. <script type="text/javaScript" src="search/search.js"></script>
    9. 

  9. <link href="doxygen.css" rel="stylesheet" type="text/css"/>
    10. 

  10. </head>
    11. 

  11. <body onload='searchBox.OnSelectItem(0);'>
    12. 

  12. <!-- Generated by Doxygen 1.7.1 -->
    13. 

  13. <script type="text/javascript"><!--
    14. 

  14. var searchBox = new SearchBox("searchBox", "search",false,'Search');
    15. 

  15. --></script>
    16. 

  16. <div class="navigation" id="top">
    17. 

  17.   <div class="tabs">
    18. 

  18.     <ul class="tablist">
    19. 

  19.       <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
    20. 

  20.       <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
    21. 

  21.       <li><a href="modules.html"><span>Modules</span></a></li>
    22. 

  22.       <li><a href="namespaces.html"><span>Namespaces</span></a></li>
    23. 

  23.       <li><a href="annotated.html"><span>Classes</span></a></li>
    24. 

  24.       <li class="current"><a href="files.html"><span>Files</span></a></li>
    25. 

  25.       <li id="searchli">
    26. 

  26.         <div id="MSearchBox" class="MSearchBoxInactive">
    27. 

  27.         <span class="left">
    28. 

  28.           <img id="MSearchSelect" src="search/mag_sel.png"
    29. 

  29.                onmouseover="return searchBox.OnSearchSelectShow()"
    30. 

  30.                onmouseout="return searchBox.OnSearchSelectHide()"
    31. 

  31.                alt=""/>
    32. 

  32.           <input type="text" id="MSearchField" value="Search" accesskey="S"
    33. 

  33.                onfocus="searchBox.OnSearchFieldFocus(true)" 
    34. 

  34.                onblur="searchBox.OnSearchFieldFocus(false)" 
    35. 

  35.                onkeyup="searchBox.OnSearchFieldChange(event)"/>
    36. 

  36.           </span><span class="right">
    37. 

  37.             <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
    38. 

  38.           </span>
    39. 

  39.         </div>
    40. 

  40.       </li>
    41. 

  41.     </ul>
    42. 

  42.   </div>
    43. 

  43.   <div class="tabs2">
    44. 

  44.     <ul class="tablist">
    45. 

  45.       <li><a href="files.html"><span>File&nbsp;List</span></a></li>
    46. 

  46.       <li><a href="globals.html"><span>File&nbsp;Members</span></a></li>
    47. 

  47.     </ul>
    48. 

  48.   </div>
    49. 

  49. <div class="header">
    50. 

  50.   <div class="headertitle">
    51. 

  51. <h1>cli/sqlite-3.7.1/sqlite3.h</h1>  </div>
    52. 

  52. </div>
    53. 

  53. <div class="contents">
    54. 

  54. <div class="fragment"><pre class="fragment"><a name="l00001"></a>00001 <span class="comment">/*</span>
    55. 

  55. <a name="l00002"></a>00002 <span class="comment">** 2001 September 15</span>
    56. 

  56. <a name="l00003"></a>00003 <span class="comment">**</span>
    57. 

  57. <a name="l00004"></a>00004 <span class="comment">** The author disclaims copyright to this source code.  In place of</span>
    58. 

  58. <a name="l00005"></a>00005 <span class="comment">** a legal notice, here is a blessing:</span>
    59. 

  59. <a name="l00006"></a>00006 <span class="comment">**</span>
    60. 

  60. <a name="l00007"></a>00007 <span class="comment">**    May you do good and not evil.</span>
    61. 

  61. <a name="l00008"></a>00008 <span class="comment">**    May you find forgiveness for yourself and forgive others.</span>
    62. 

  62. <a name="l00009"></a>00009 <span class="comment">**    May you share freely, never taking more than you give.</span>
    63. 

  63. <a name="l00010"></a>00010 <span class="comment">**</span>
    64. 

  64. <a name="l00011"></a>00011 <span class="comment">*************************************************************************</span>
    65. 

  65. <a name="l00012"></a>00012 <span class="comment">** This header file defines the interface that the SQLite library</span>
    66. 

  66. <a name="l00013"></a>00013 <span class="comment">** presents to client programs.  If a C-function, structure, datatype,</span>
    67. 

  67. <a name="l00014"></a>00014 <span class="comment">** or constant definition does not appear in this file, then it is</span>
    68. 

  68. <a name="l00015"></a>00015 <span class="comment">** not a published API of SQLite, is subject to change without</span>
    69. 

  69. <a name="l00016"></a>00016 <span class="comment">** notice, and should not be referenced by programs that use SQLite.</span>
    70. 

  70. <a name="l00017"></a>00017 <span class="comment">**</span>
    71. 

  71. <a name="l00018"></a>00018 <span class="comment">** Some of the definitions that are in this file are marked as</span>
    72. 

  72. <a name="l00019"></a>00019 <span class="comment">** &quot;experimental&quot;.  Experimental interfaces are normally new</span>
    73. 

  73. <a name="l00020"></a>00020 <span class="comment">** features recently added to SQLite.  We do not anticipate changes</span>
    74. 

  74. <a name="l00021"></a>00021 <span class="comment">** to experimental interfaces but reserve the right to make minor changes</span>
    75. 

  75. <a name="l00022"></a>00022 <span class="comment">** if experience from use &quot;in the wild&quot; suggest such changes are prudent.</span>
    76. 

  76. <a name="l00023"></a>00023 <span class="comment">**</span>
    77. 

  77. <a name="l00024"></a>00024 <span class="comment">** The official C-language API documentation for SQLite is derived</span>
    78. 

  78. <a name="l00025"></a>00025 <span class="comment">** from comments in this file.  This file is the authoritative source</span>
    79. 

  79. <a name="l00026"></a>00026 <span class="comment">** on how SQLite interfaces are suppose to operate.</span>
    80. 

  80. <a name="l00027"></a>00027 <span class="comment">**</span>
    81. 

  81. <a name="l00028"></a>00028 <span class="comment">** The name of this file under configuration management is &quot;sqlite.h.in&quot;.</span>
    82. 

  82. <a name="l00029"></a>00029 <span class="comment">** The makefile makes some minor changes to this file (such as inserting</span>
    83. 

  83. <a name="l00030"></a>00030 <span class="comment">** the version number) and changes its name to &quot;sqlite3.h&quot; as</span>
    84. 

  84. <a name="l00031"></a>00031 <span class="comment">** part of the build process.</span>
    85. 

  85. <a name="l00032"></a>00032 <span class="comment">*/</span>
    86. 

  86. <a name="l00033"></a>00033 <span class="preprocessor">#ifndef _SQLITE3_H_</span>
    87. 

  87. <a name="l00034"></a>00034 <span class="preprocessor"></span><span class="preprocessor">#define _SQLITE3_H_</span>
    88. 

  88. <a name="l00035"></a>00035 <span class="preprocessor"></span><span class="preprocessor">#include &lt;stdarg.h&gt;</span>     <span class="comment">/* Needed for the definition of va_list */</span>
    89. 

  89. <a name="l00036"></a>00036 
    90. 

  90. <a name="l00037"></a>00037 <span class="comment">/*</span>
    91. 

  91. <a name="l00038"></a>00038 <span class="comment">** Make sure we can call this stuff from C++.</span>
    92. 

  92. <a name="l00039"></a>00039 <span class="comment">*/</span>
    93. 

  93. <a name="l00040"></a>00040 <span class="preprocessor">#ifdef __cplusplus</span>
    94. 

  94. <a name="l00041"></a>00041 <span class="preprocessor"></span><span class="keyword">extern</span> <span class="stringliteral">&quot;C&quot;</span> {
    95. 

  95. <a name="l00042"></a>00042 <span class="preprocessor">#endif</span>
    96. 

  96. <a name="l00043"></a>00043 <span class="preprocessor"></span>
    97. 

  97. <a name="l00044"></a>00044 
    98. 

  98. <a name="l00045"></a>00045 <span class="comment">/*</span>
    99. 

  99. <a name="l00046"></a>00046 <span class="comment">** Add the ability to override &#39;extern&#39;</span>
    100. 

  100. <a name="l00047"></a>00047 <span class="comment">*/</span>
    101. 

  101. <a name="l00048"></a>00048 <span class="preprocessor">#ifndef SQLITE_EXTERN</span>
    102. 

  102. <a name="l00049"></a>00049 <span class="preprocessor"></span><span class="preprocessor"># define SQLITE_EXTERN extern</span>
    103. 

  103. <a name="l00050"></a>00050 <span class="preprocessor"></span><span class="preprocessor">#endif</span>
    104. 

  104. <a name="l00051"></a>00051 <span class="preprocessor"></span>
    105. 

  105. <a name="l00052"></a>00052 <span class="preprocessor">#ifndef SQLITE_API</span>
    106. 

  106. <a name="l00053"></a>00053 <span class="preprocessor"></span><span class="preprocessor"># define SQLITE_API</span>
    107. 

  107. <a name="l00054"></a>00054 <span class="preprocessor"></span><span class="preprocessor">#endif</span>
    108. 

  108. <a name="l00055"></a>00055 <span class="preprocessor"></span>
    109. 

  109. <a name="l00056"></a>00056 
    110. 

  110. <a name="l00057"></a>00057 <span class="comment">/*</span>
    111. 

  111. <a name="l00058"></a>00058 <span class="comment">** These no-op macros are used in front of interfaces to mark those</span>
    112. 

  112. <a name="l00059"></a>00059 <span class="comment">** interfaces as either deprecated or experimental.  New applications</span>
    113. 

  113. <a name="l00060"></a>00060 <span class="comment">** should not use deprecated interfaces - they are support for backwards</span>
    114. 

  114. <a name="l00061"></a>00061 <span class="comment">** compatibility only.  Application writers should be aware that</span>
    115. 

  115. <a name="l00062"></a>00062 <span class="comment">** experimental interfaces are subject to change in point releases.</span>
    116. 

  116. <a name="l00063"></a>00063 <span class="comment">**</span>
    117. 

  117. <a name="l00064"></a>00064 <span class="comment">** These macros used to resolve to various kinds of compiler magic that</span>
    118. 

  118. <a name="l00065"></a>00065 <span class="comment">** would generate warning messages when they were used.  But that</span>
    119. 

  119. <a name="l00066"></a>00066 <span class="comment">** compiler magic ended up generating such a flurry of bug reports</span>
    120. 

  120. <a name="l00067"></a>00067 <span class="comment">** that we have taken it all out and gone back to using simple</span>
    121. 

  121. <a name="l00068"></a>00068 <span class="comment">** noop macros.</span>
    122. 

  122. <a name="l00069"></a>00069 <span class="comment">*/</span>
    123. 

  123. <a name="l00070"></a>00070 <span class="preprocessor">#define SQLITE_DEPRECATED</span>
    124. 

  124. <a name="l00071"></a>00071 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_EXPERIMENTAL</span>
    125. 

  125. <a name="l00072"></a>00072 <span class="preprocessor"></span>
    126. 

  126. <a name="l00073"></a>00073 <span class="comment">/*</span>
    127. 

  127. <a name="l00074"></a>00074 <span class="comment">** Ensure these symbols were not defined by some previous header file.</span>
    128. 

  128. <a name="l00075"></a>00075 <span class="comment">*/</span>
    129. 

  129. <a name="l00076"></a>00076 <span class="preprocessor">#ifdef SQLITE_VERSION</span>
    130. 

  130. <a name="l00077"></a>00077 <span class="preprocessor"></span><span class="preprocessor"># undef SQLITE_VERSION</span>
    131. 

  131. <a name="l00078"></a>00078 <span class="preprocessor"></span><span class="preprocessor">#endif</span>
    132. 

  132. <a name="l00079"></a>00079 <span class="preprocessor"></span><span class="preprocessor">#ifdef SQLITE_VERSION_NUMBER</span>
    133. 

  133. <a name="l00080"></a>00080 <span class="preprocessor"></span><span class="preprocessor"># undef SQLITE_VERSION_NUMBER</span>
    134. 

  134. <a name="l00081"></a>00081 <span class="preprocessor"></span><span class="preprocessor">#endif</span>
    135. 

  135. <a name="l00082"></a>00082 <span class="preprocessor"></span>
    136. 

  136. <a name="l00083"></a>00083 <span class="comment">/*</span>
    137. 

  137. <a name="l00084"></a>00084 <span class="comment">** CAPI3REF: Compile-Time Library Version Numbers</span>
    138. 

  138. <a name="l00085"></a>00085 <span class="comment">**</span>
    139. 

  139. <a name="l00086"></a>00086 <span class="comment">** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header</span>
    140. 

  140. <a name="l00087"></a>00087 <span class="comment">** evaluates to a string literal that is the SQLite version in the</span>
    141. 

  141. <a name="l00088"></a>00088 <span class="comment">** format &quot;X.Y.Z&quot; where X is the major version number (always 3 for</span>
    142. 

  142. <a name="l00089"></a>00089 <span class="comment">** SQLite3) and Y is the minor version number and Z is the release number.)^</span>
    143. 

  143. <a name="l00090"></a>00090 <span class="comment">** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer</span>
    144. 

  144. <a name="l00091"></a>00091 <span class="comment">** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same</span>
    145. 

  145. <a name="l00092"></a>00092 <span class="comment">** numbers used in [SQLITE_VERSION].)^</span>
    146. 

  146. <a name="l00093"></a>00093 <span class="comment">** The SQLITE_VERSION_NUMBER for any given release of SQLite will also</span>
    147. 

  147. <a name="l00094"></a>00094 <span class="comment">** be larger than the release from which it is derived.  Either Y will</span>
    148. 

  148. <a name="l00095"></a>00095 <span class="comment">** be held constant and Z will be incremented or else Y will be incremented</span>
    149. 

  149. <a name="l00096"></a>00096 <span class="comment">** and Z will be reset to zero.</span>
    150. 

  150. <a name="l00097"></a>00097 <span class="comment">**</span>
    151. 

  151. <a name="l00098"></a>00098 <span class="comment">** Since version 3.6.18, SQLite source code has been stored in the</span>
    152. 

  152. <a name="l00099"></a>00099 <span class="comment">** &lt;a href=&quot;http://www.fossil-scm.org/&quot;&gt;Fossil configuration management</span>
    153. 

  153. <a name="l00100"></a>00100 <span class="comment">** system&lt;/a&gt;.  ^The SQLITE_SOURCE_ID macro evaluates to</span>
    154. 

  154. <a name="l00101"></a>00101 <span class="comment">** a string which identifies a particular check-in of SQLite</span>
    155. 

  155. <a name="l00102"></a>00102 <span class="comment">** within its configuration management system.  ^The SQLITE_SOURCE_ID</span>
    156. 

  156. <a name="l00103"></a>00103 <span class="comment">** string contains the date and time of the check-in (UTC) and an SHA1</span>
    157. 

  157. <a name="l00104"></a>00104 <span class="comment">** hash of the entire source tree.</span>
    158. 

  158. <a name="l00105"></a>00105 <span class="comment">**</span>
    159. 

  159. <a name="l00106"></a>00106 <span class="comment">** See also: [sqlite3_libversion()],</span>
    160. 

  160. <a name="l00107"></a>00107 <span class="comment">** [sqlite3_libversion_number()], [sqlite3_sourceid()],</span>
    161. 

  161. <a name="l00108"></a>00108 <span class="comment">** [sqlite_version()] and [sqlite_source_id()].</span>
    162. 

  162. <a name="l00109"></a>00109 <span class="comment">*/</span>
    163. 

  163. <a name="l00110"></a>00110 <span class="preprocessor">#define SQLITE_VERSION        &quot;3.7.10&quot;</span>
    164. 

  164. <a name="l00111"></a>00111 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_VERSION_NUMBER 3007010</span>
    165. 

  165. <a name="l00112"></a>00112 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_SOURCE_ID      &quot;2012-01-16 13:28:40 ebd01a8deffb5024a5d7494eef800d2366d97204&quot;</span>
    166. 

  166. <a name="l00113"></a>00113 <span class="preprocessor"></span>
    167. 

  167. <a name="l00114"></a>00114 <span class="comment">/*</span>
    168. 

  168. <a name="l00115"></a>00115 <span class="comment">** CAPI3REF: Run-Time Library Version Numbers</span>
    169. 

  169. <a name="l00116"></a>00116 <span class="comment">** KEYWORDS: sqlite3_version, sqlite3_sourceid</span>
    170. 

  170. <a name="l00117"></a>00117 <span class="comment">**</span>
    171. 

  171. <a name="l00118"></a>00118 <span class="comment">** These interfaces provide the same information as the [SQLITE_VERSION],</span>
    172. 

  172. <a name="l00119"></a>00119 <span class="comment">** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros</span>
    173. 

  173. <a name="l00120"></a>00120 <span class="comment">** but are associated with the library instead of the header file.  ^(Cautious</span>
    174. 

  174. <a name="l00121"></a>00121 <span class="comment">** programmers might include assert() statements in their application to</span>
    175. 

  175. <a name="l00122"></a>00122 <span class="comment">** verify that values returned by these interfaces match the macros in</span>
    176. 

  176. <a name="l00123"></a>00123 <span class="comment">** the header, and thus insure that the application is</span>
    177. 

  177. <a name="l00124"></a>00124 <span class="comment">** compiled with matching library and header files.</span>
    178. 

  178. <a name="l00125"></a>00125 <span class="comment">**</span>
    179. 

  179. <a name="l00126"></a>00126 <span class="comment">** &lt;blockquote&gt;&lt;pre&gt;</span>
    180. 

  180. <a name="l00127"></a>00127 <span class="comment">** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );</span>
    181. 

  181. <a name="l00128"></a>00128 <span class="comment">** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );</span>
    182. 

  182. <a name="l00129"></a>00129 <span class="comment">** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );</span>
    183. 

  183. <a name="l00130"></a>00130 <span class="comment">** &lt;/pre&gt;&lt;/blockquote&gt;)^</span>
    184. 

  184. <a name="l00131"></a>00131 <span class="comment">**</span>
    185. 

  185. <a name="l00132"></a>00132 <span class="comment">** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]</span>
    186. 

  186. <a name="l00133"></a>00133 <span class="comment">** macro.  ^The sqlite3_libversion() function returns a pointer to the</span>
    187. 

  187. <a name="l00134"></a>00134 <span class="comment">** to the sqlite3_version[] string constant.  The sqlite3_libversion()</span>
    188. 

  188. <a name="l00135"></a>00135 <span class="comment">** function is provided for use in DLLs since DLL users usually do not have</span>
    189. 

  189. <a name="l00136"></a>00136 <span class="comment">** direct access to string constants within the DLL.  ^The</span>
    190. 

  190. <a name="l00137"></a>00137 <span class="comment">** sqlite3_libversion_number() function returns an integer equal to</span>
    191. 

  191. <a name="l00138"></a>00138 <span class="comment">** [SQLITE_VERSION_NUMBER].  ^The sqlite3_sourceid() function returns </span>
    192. 

  192. <a name="l00139"></a>00139 <span class="comment">** a pointer to a string constant whose value is the same as the </span>
    193. 

  193. <a name="l00140"></a>00140 <span class="comment">** [SQLITE_SOURCE_ID] C preprocessor macro.</span>
    194. 

  194. <a name="l00141"></a>00141 <span class="comment">**</span>
    195. 

  195. <a name="l00142"></a>00142 <span class="comment">** See also: [sqlite_version()] and [sqlite_source_id()].</span>
    196. 

  196. <a name="l00143"></a>00143 <span class="comment">*/</span>
    197. 

  197. <a name="l00144"></a>00144 SQLITE_API SQLITE_EXTERN <span class="keyword">const</span> <span class="keywordtype">char</span> sqlite3_version[];
    198. 

  198. <a name="l00145"></a>00145 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">char</span> *sqlite3_libversion(<span class="keywordtype">void</span>);
    199. 

  199. <a name="l00146"></a>00146 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">char</span> *sqlite3_sourceid(<span class="keywordtype">void</span>);
    200. 

  200. <a name="l00147"></a>00147 SQLITE_API <span class="keywordtype">int</span> sqlite3_libversion_number(<span class="keywordtype">void</span>);
    201. 

  201. <a name="l00148"></a>00148 
    202. 

  202. <a name="l00149"></a>00149 <span class="comment">/*</span>
    203. 

  203. <a name="l00150"></a>00150 <span class="comment">** CAPI3REF: Run-Time Library Compilation Options Diagnostics</span>
    204. 

  204. <a name="l00151"></a>00151 <span class="comment">**</span>
    205. 

  205. <a name="l00152"></a>00152 <span class="comment">** ^The sqlite3_compileoption_used() function returns 0 or 1 </span>
    206. 

  206. <a name="l00153"></a>00153 <span class="comment">** indicating whether the specified option was defined at </span>
    207. 

  207. <a name="l00154"></a>00154 <span class="comment">** compile time.  ^The SQLITE_ prefix may be omitted from the </span>
    208. 

  208. <a name="l00155"></a>00155 <span class="comment">** option name passed to sqlite3_compileoption_used().  </span>
    209. 

  209. <a name="l00156"></a>00156 <span class="comment">**</span>
    210. 

  210. <a name="l00157"></a>00157 <span class="comment">** ^The sqlite3_compileoption_get() function allows iterating</span>
    211. 

  211. <a name="l00158"></a>00158 <span class="comment">** over the list of options that were defined at compile time by</span>
    212. 

  212. <a name="l00159"></a>00159 <span class="comment">** returning the N-th compile time option string.  ^If N is out of range,</span>
    213. 

  213. <a name="l00160"></a>00160 <span class="comment">** sqlite3_compileoption_get() returns a NULL pointer.  ^The SQLITE_ </span>
    214. 

  214. <a name="l00161"></a>00161 <span class="comment">** prefix is omitted from any strings returned by </span>
    215. 

  215. <a name="l00162"></a>00162 <span class="comment">** sqlite3_compileoption_get().</span>
    216. 

  216. <a name="l00163"></a>00163 <span class="comment">**</span>
    217. 

  217. <a name="l00164"></a>00164 <span class="comment">** ^Support for the diagnostic functions sqlite3_compileoption_used()</span>
    218. 

  218. <a name="l00165"></a>00165 <span class="comment">** and sqlite3_compileoption_get() may be omitted by specifying the </span>
    219. 

  219. <a name="l00166"></a>00166 <span class="comment">** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.</span>
    220. 

  220. <a name="l00167"></a>00167 <span class="comment">**</span>
    221. 

  221. <a name="l00168"></a>00168 <span class="comment">** See also: SQL functions [sqlite_compileoption_used()] and</span>
    222. 

  222. <a name="l00169"></a>00169 <span class="comment">** [sqlite_compileoption_get()] and the [compile_options pragma].</span>
    223. 

  223. <a name="l00170"></a>00170 <span class="comment">*/</span>
    224. 

  224. <a name="l00171"></a>00171 <span class="preprocessor">#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS</span>
    225. 

  225. <a name="l00172"></a>00172 <span class="preprocessor"></span>SQLITE_API <span class="keywordtype">int</span> sqlite3_compileoption_used(<span class="keyword">const</span> <span class="keywordtype">char</span> *zOptName);
    226. 

  226. <a name="l00173"></a>00173 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">char</span> *sqlite3_compileoption_get(<span class="keywordtype">int</span> N);
    227. 

  227. <a name="l00174"></a>00174 <span class="preprocessor">#endif</span>
    228. 

  228. <a name="l00175"></a>00175 <span class="preprocessor"></span>
    229. 

  229. <a name="l00176"></a>00176 <span class="comment">/*</span>
    230. 

  230. <a name="l00177"></a>00177 <span class="comment">** CAPI3REF: Test To See If The Library Is Threadsafe</span>
    231. 

  231. <a name="l00178"></a>00178 <span class="comment">**</span>
    232. 

  232. <a name="l00179"></a>00179 <span class="comment">** ^The sqlite3_threadsafe() function returns zero if and only if</span>
    233. 

  233. <a name="l00180"></a>00180 <span class="comment">** SQLite was compiled with mutexing code omitted due to the</span>
    234. 

  234. <a name="l00181"></a>00181 <span class="comment">** [SQLITE_THREADSAFE] compile-time option being set to 0.</span>
    235. 

  235. <a name="l00182"></a>00182 <span class="comment">**</span>
    236. 

  236. <a name="l00183"></a>00183 <span class="comment">** SQLite can be compiled with or without mutexes.  When</span>
    237. 

  237. <a name="l00184"></a>00184 <span class="comment">** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes</span>
    238. 

  238. <a name="l00185"></a>00185 <span class="comment">** are enabled and SQLite is threadsafe.  When the</span>
    239. 

  239. <a name="l00186"></a>00186 <span class="comment">** [SQLITE_THREADSAFE] macro is 0, </span>
    240. 

  240. <a name="l00187"></a>00187 <span class="comment">** the mutexes are omitted.  Without the mutexes, it is not safe</span>
    241. 

  241. <a name="l00188"></a>00188 <span class="comment">** to use SQLite concurrently from more than one thread.</span>
    242. 

  242. <a name="l00189"></a>00189 <span class="comment">**</span>
    243. 

  243. <a name="l00190"></a>00190 <span class="comment">** Enabling mutexes incurs a measurable performance penalty.</span>
    244. 

  244. <a name="l00191"></a>00191 <span class="comment">** So if speed is of utmost importance, it makes sense to disable</span>
    245. 

  245. <a name="l00192"></a>00192 <span class="comment">** the mutexes.  But for maximum safety, mutexes should be enabled.</span>
    246. 

  246. <a name="l00193"></a>00193 <span class="comment">** ^The default behavior is for mutexes to be enabled.</span>
    247. 

  247. <a name="l00194"></a>00194 <span class="comment">**</span>
    248. 

  248. <a name="l00195"></a>00195 <span class="comment">** This interface can be used by an application to make sure that the</span>
    249. 

  249. <a name="l00196"></a>00196 <span class="comment">** version of SQLite that it is linking against was compiled with</span>
    250. 

  250. <a name="l00197"></a>00197 <span class="comment">** the desired setting of the [SQLITE_THREADSAFE] macro.</span>
    251. 

  251. <a name="l00198"></a>00198 <span class="comment">**</span>
    252. 

  252. <a name="l00199"></a>00199 <span class="comment">** This interface only reports on the compile-time mutex setting</span>
    253. 

  253. <a name="l00200"></a>00200 <span class="comment">** of the [SQLITE_THREADSAFE] flag.  If SQLite is compiled with</span>
    254. 

  254. <a name="l00201"></a>00201 <span class="comment">** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but</span>
    255. 

  255. <a name="l00202"></a>00202 <span class="comment">** can be fully or partially disabled using a call to [sqlite3_config()]</span>
    256. 

  256. <a name="l00203"></a>00203 <span class="comment">** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],</span>
    257. 

  257. <a name="l00204"></a>00204 <span class="comment">** or [SQLITE_CONFIG_MUTEX].  ^(The return value of the</span>
    258. 

  258. <a name="l00205"></a>00205 <span class="comment">** sqlite3_threadsafe() function shows only the compile-time setting of</span>
    259. 

  259. <a name="l00206"></a>00206 <span class="comment">** thread safety, not any run-time changes to that setting made by</span>
    260. 

  260. <a name="l00207"></a>00207 <span class="comment">** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()</span>
    261. 

  261. <a name="l00208"></a>00208 <span class="comment">** is unchanged by calls to sqlite3_config().)^</span>
    262. 

  262. <a name="l00209"></a>00209 <span class="comment">**</span>
    263. 

  263. <a name="l00210"></a>00210 <span class="comment">** See the [threading mode] documentation for additional information.</span>
    264. 

  264. <a name="l00211"></a>00211 <span class="comment">*/</span>
    265. 

  265. <a name="l00212"></a>00212 SQLITE_API <span class="keywordtype">int</span> sqlite3_threadsafe(<span class="keywordtype">void</span>);
    266. 

  266. <a name="l00213"></a>00213 
    267. 

  267. <a name="l00214"></a>00214 <span class="comment">/*</span>
    268. 

  268. <a name="l00215"></a>00215 <span class="comment">** CAPI3REF: Database Connection Handle</span>
    269. 

  269. <a name="l00216"></a>00216 <span class="comment">** KEYWORDS: {database connection} {database connections}</span>
    270. 

  270. <a name="l00217"></a>00217 <span class="comment">**</span>
    271. 

  271. <a name="l00218"></a>00218 <span class="comment">** Each open SQLite database is represented by a pointer to an instance of</span>
    272. 

  272. <a name="l00219"></a>00219 <span class="comment">** the opaque structure named &quot;sqlite3&quot;.  It is useful to think of an sqlite3</span>
    273. 

  273. <a name="l00220"></a>00220 <span class="comment">** pointer as an object.  The [sqlite3_open()], [sqlite3_open16()], and</span>
    274. 

  274. <a name="l00221"></a>00221 <span class="comment">** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]</span>
    275. 

  275. <a name="l00222"></a>00222 <span class="comment">** is its destructor.  There are many other interfaces (such as</span>
    276. 

  276. <a name="l00223"></a>00223 <span class="comment">** [sqlite3_prepare_v2()], [sqlite3_create_function()], and</span>
    277. 

  277. <a name="l00224"></a>00224 <span class="comment">** [sqlite3_busy_timeout()] to name but three) that are methods on an</span>
    278. 

  278. <a name="l00225"></a>00225 <span class="comment">** sqlite3 object.</span>
    279. 

  279. <a name="l00226"></a>00226 <span class="comment">*/</span>
    280. 

  280. <a name="l00227"></a>00227 <span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="structsqlite3.html">sqlite3</a> <a class="code" href="structsqlite3.html">sqlite3</a>;
    281. 

  281. <a name="l00228"></a>00228 
    282. 

  282. <a name="l00229"></a>00229 <span class="comment">/*</span>
    283. 

  283. <a name="l00230"></a>00230 <span class="comment">** CAPI3REF: 64-Bit Integer Types</span>
    284. 

  284. <a name="l00231"></a>00231 <span class="comment">** KEYWORDS: sqlite_int64 sqlite_uint64</span>
    285. 

  285. <a name="l00232"></a>00232 <span class="comment">**</span>
    286. 

  286. <a name="l00233"></a>00233 <span class="comment">** Because there is no cross-platform way to specify 64-bit integer types</span>
    287. 

  287. <a name="l00234"></a>00234 <span class="comment">** SQLite includes typedefs for 64-bit signed and unsigned integers.</span>
    288. 

  288. <a name="l00235"></a>00235 <span class="comment">**</span>
    289. 

  289. <a name="l00236"></a>00236 <span class="comment">** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.</span>
    290. 

  290. <a name="l00237"></a>00237 <span class="comment">** The sqlite_int64 and sqlite_uint64 types are supported for backwards</span>
    291. 

  291. <a name="l00238"></a>00238 <span class="comment">** compatibility only.</span>
    292. 

  292. <a name="l00239"></a>00239 <span class="comment">**</span>
    293. 

  293. <a name="l00240"></a>00240 <span class="comment">** ^The sqlite3_int64 and sqlite_int64 types can store integer values</span>
    294. 

  294. <a name="l00241"></a>00241 <span class="comment">** between -9223372036854775808 and +9223372036854775807 inclusive.  ^The</span>
    295. 

  295. <a name="l00242"></a>00242 <span class="comment">** sqlite3_uint64 and sqlite_uint64 types can store integer values </span>
    296. 

  296. <a name="l00243"></a>00243 <span class="comment">** between 0 and +18446744073709551615 inclusive.</span>
    297. 

  297. <a name="l00244"></a>00244 <span class="comment">*/</span>
    298. 

  298. <a name="l00245"></a>00245 <span class="preprocessor">#ifdef SQLITE_INT64_TYPE</span>
    299. 

  299. <a name="l00246"></a>00246 <span class="preprocessor"></span>  <span class="keyword">typedef</span> SQLITE_INT64_TYPE sqlite_int64;
    300. 

  300. <a name="l00247"></a>00247   <span class="keyword">typedef</span> <span class="keywordtype">unsigned</span> SQLITE_INT64_TYPE sqlite_uint64;
    301. 

  301. <a name="l00248"></a>00248 <span class="preprocessor">#elif defined(_MSC_VER) || defined(__BORLANDC__)</span>
    302. 

  302. <a name="l00249"></a>00249 <span class="preprocessor"></span>  <span class="keyword">typedef</span> __int64 sqlite_int64;
    303. 

  303. <a name="l00250"></a>00250   <span class="keyword">typedef</span> <span class="keywordtype">unsigned</span> __int64 sqlite_uint64;
    304. 

  304. <a name="l00251"></a>00251 <span class="preprocessor">#else</span>
    305. 

  305. <a name="l00252"></a>00252 <span class="preprocessor"></span>  <span class="keyword">typedef</span> <span class="keywordtype">long</span> <span class="keywordtype">long</span> <span class="keywordtype">int</span> sqlite_int64;
    306. 

  306. <a name="l00253"></a>00253   <span class="keyword">typedef</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> <span class="keywordtype">long</span> <span class="keywordtype">int</span> sqlite_uint64;
    307. 

  307. <a name="l00254"></a>00254 <span class="preprocessor">#endif</span>
    308. 

  308. <a name="l00255"></a>00255 <span class="preprocessor"></span><span class="keyword">typedef</span> sqlite_int64 sqlite3_int64;
    309. 

  309. <a name="l00256"></a>00256 <span class="keyword">typedef</span> sqlite_uint64 sqlite3_uint64;
    310. 

  310. <a name="l00257"></a>00257 
    311. 

  311. <a name="l00258"></a>00258 <span class="comment">/*</span>
    312. 

  312. <a name="l00259"></a>00259 <span class="comment">** If compiling for a processor that lacks floating point support,</span>
    313. 

  313. <a name="l00260"></a>00260 <span class="comment">** substitute integer for floating-point.</span>
    314. 

  314. <a name="l00261"></a>00261 <span class="comment">*/</span>
    315. 

  315. <a name="l00262"></a>00262 <span class="preprocessor">#ifdef SQLITE_OMIT_FLOATING_POINT</span>
    316. 

  316. <a name="l00263"></a>00263 <span class="preprocessor"></span><span class="preprocessor"># define double sqlite3_int64</span>
    317. 

  317. <a name="l00264"></a>00264 <span class="preprocessor"></span><span class="preprocessor">#endif</span>
    318. 

  318. <a name="l00265"></a>00265 <span class="preprocessor"></span>
    319. 

  319. <a name="l00266"></a>00266 <span class="comment">/*</span>
    320. 

  320. <a name="l00267"></a>00267 <span class="comment">** CAPI3REF: Closing A Database Connection</span>
    321. 

  321. <a name="l00268"></a>00268 <span class="comment">**</span>
    322. 

  322. <a name="l00269"></a>00269 <span class="comment">** ^The sqlite3_close() routine is the destructor for the [sqlite3] object.</span>
    323. 

  323. <a name="l00270"></a>00270 <span class="comment">** ^Calls to sqlite3_close() return SQLITE_OK if the [sqlite3] object is</span>
    324. 

  324. <a name="l00271"></a>00271 <span class="comment">** successfully destroyed and all associated resources are deallocated.</span>
    325. 

  325. <a name="l00272"></a>00272 <span class="comment">**</span>
    326. 

  326. <a name="l00273"></a>00273 <span class="comment">** Applications must [sqlite3_finalize | finalize] all [prepared statements]</span>
    327. 

  327. <a name="l00274"></a>00274 <span class="comment">** and [sqlite3_blob_close | close] all [BLOB handles] associated with</span>
    328. 

  328. <a name="l00275"></a>00275 <span class="comment">** the [sqlite3] object prior to attempting to close the object.  ^If</span>
    329. 

  329. <a name="l00276"></a>00276 <span class="comment">** sqlite3_close() is called on a [database connection] that still has</span>
    330. 

  330. <a name="l00277"></a>00277 <span class="comment">** outstanding [prepared statements] or [BLOB handles], then it returns</span>
    331. 

  331. <a name="l00278"></a>00278 <span class="comment">** SQLITE_BUSY.</span>
    332. 

  332. <a name="l00279"></a>00279 <span class="comment">**</span>
    333. 

  333. <a name="l00280"></a>00280 <span class="comment">** ^If [sqlite3_close()] is invoked while a transaction is open,</span>
    334. 

  334. <a name="l00281"></a>00281 <span class="comment">** the transaction is automatically rolled back.</span>
    335. 

  335. <a name="l00282"></a>00282 <span class="comment">**</span>
    336. 

  336. <a name="l00283"></a>00283 <span class="comment">** The C parameter to [sqlite3_close(C)] must be either a NULL</span>
    337. 

  337. <a name="l00284"></a>00284 <span class="comment">** pointer or an [sqlite3] object pointer obtained</span>
    338. 

  338. <a name="l00285"></a>00285 <span class="comment">** from [sqlite3_open()], [sqlite3_open16()], or</span>
    339. 

  339. <a name="l00286"></a>00286 <span class="comment">** [sqlite3_open_v2()], and not previously closed.</span>
    340. 

  340. <a name="l00287"></a>00287 <span class="comment">** ^Calling sqlite3_close() with a NULL pointer argument is a </span>
    341. 

  341. <a name="l00288"></a>00288 <span class="comment">** harmless no-op.</span>
    342. 

  342. <a name="l00289"></a>00289 <span class="comment">*/</span>
    343. 

  343. <a name="l00290"></a>00290 SQLITE_API <span class="keywordtype">int</span> sqlite3_close(<a class="code" href="structsqlite3.html">sqlite3</a> *);
    344. 

  344. <a name="l00291"></a>00291 
    345. 

  345. <a name="l00292"></a>00292 <span class="comment">/*</span>
    346. 

  346. <a name="l00293"></a>00293 <span class="comment">** The type for a callback function.</span>
    347. 

  347. <a name="l00294"></a>00294 <span class="comment">** This is legacy and deprecated.  It is included for historical</span>
    348. 

  348. <a name="l00295"></a>00295 <span class="comment">** compatibility and is not documented.</span>
    349. 

  349. <a name="l00296"></a>00296 <span class="comment">*/</span>
    350. 

  350. <a name="l00297"></a>00297 <span class="keyword">typedef</span> int (*sqlite3_callback)(<span class="keywordtype">void</span>*,int,<span class="keywordtype">char</span>**, <span class="keywordtype">char</span>**);
    351. 

  351. <a name="l00298"></a>00298 
    352. 

  352. <a name="l00299"></a>00299 <span class="comment">/*</span>
    353. 

  353. <a name="l00300"></a>00300 <span class="comment">** CAPI3REF: One-Step Query Execution Interface</span>
    354. 

  354. <a name="l00301"></a>00301 <span class="comment">**</span>
    355. 

  355. <a name="l00302"></a>00302 <span class="comment">** The sqlite3_exec() interface is a convenience wrapper around</span>
    356. 

  356. <a name="l00303"></a>00303 <span class="comment">** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],</span>
    357. 

  357. <a name="l00304"></a>00304 <span class="comment">** that allows an application to run multiple statements of SQL</span>
    358. 

  358. <a name="l00305"></a>00305 <span class="comment">** without having to use a lot of C code. </span>
    359. 

  359. <a name="l00306"></a>00306 <span class="comment">**</span>
    360. 

  360. <a name="l00307"></a>00307 <span class="comment">** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,</span>
    361. 

  361. <a name="l00308"></a>00308 <span class="comment">** semicolon-separate SQL statements passed into its 2nd argument,</span>
    362. 

  362. <a name="l00309"></a>00309 <span class="comment">** in the context of the [database connection] passed in as its 1st</span>
    363. 

  363. <a name="l00310"></a>00310 <span class="comment">** argument.  ^If the callback function of the 3rd argument to</span>
    364. 

  364. <a name="l00311"></a>00311 <span class="comment">** sqlite3_exec() is not NULL, then it is invoked for each result row</span>
    365. 

  365. <a name="l00312"></a>00312 <span class="comment">** coming out of the evaluated SQL statements.  ^The 4th argument to</span>
    366. 

  366. <a name="l00313"></a>00313 <span class="comment">** sqlite3_exec() is relayed through to the 1st argument of each</span>
    367. 

  367. <a name="l00314"></a>00314 <span class="comment">** callback invocation.  ^If the callback pointer to sqlite3_exec()</span>
    368. 

  368. <a name="l00315"></a>00315 <span class="comment">** is NULL, then no callback is ever invoked and result rows are</span>
    369. 

  369. <a name="l00316"></a>00316 <span class="comment">** ignored.</span>
    370. 

  370. <a name="l00317"></a>00317 <span class="comment">**</span>
    371. 

  371. <a name="l00318"></a>00318 <span class="comment">** ^If an error occurs while evaluating the SQL statements passed into</span>
    372. 

  372. <a name="l00319"></a>00319 <span class="comment">** sqlite3_exec(), then execution of the current statement stops and</span>
    373. 

  373. <a name="l00320"></a>00320 <span class="comment">** subsequent statements are skipped.  ^If the 5th parameter to sqlite3_exec()</span>
    374. 

  374. <a name="l00321"></a>00321 <span class="comment">** is not NULL then any error message is written into memory obtained</span>
    375. 

  375. <a name="l00322"></a>00322 <span class="comment">** from [sqlite3_malloc()] and passed back through the 5th parameter.</span>
    376. 

  376. <a name="l00323"></a>00323 <span class="comment">** To avoid memory leaks, the application should invoke [sqlite3_free()]</span>
    377. 

  377. <a name="l00324"></a>00324 <span class="comment">** on error message strings returned through the 5th parameter of</span>
    378. 

  378. <a name="l00325"></a>00325 <span class="comment">** of sqlite3_exec() after the error message string is no longer needed.</span>
    379. 

  379. <a name="l00326"></a>00326 <span class="comment">** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors</span>
    380. 

  380. <a name="l00327"></a>00327 <span class="comment">** occur, then sqlite3_exec() sets the pointer in its 5th parameter to</span>
    381. 

  381. <a name="l00328"></a>00328 <span class="comment">** NULL before returning.</span>
    382. 

  382. <a name="l00329"></a>00329 <span class="comment">**</span>
    383. 

  383. <a name="l00330"></a>00330 <span class="comment">** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()</span>
    384. 

  384. <a name="l00331"></a>00331 <span class="comment">** routine returns SQLITE_ABORT without invoking the callback again and</span>
    385. 

  385. <a name="l00332"></a>00332 <span class="comment">** without running any subsequent SQL statements.</span>
    386. 

  386. <a name="l00333"></a>00333 <span class="comment">**</span>
    387. 

  387. <a name="l00334"></a>00334 <span class="comment">** ^The 2nd argument to the sqlite3_exec() callback function is the</span>
    388. 

  388. <a name="l00335"></a>00335 <span class="comment">** number of columns in the result.  ^The 3rd argument to the sqlite3_exec()</span>
    389. 

  389. <a name="l00336"></a>00336 <span class="comment">** callback is an array of pointers to strings obtained as if from</span>
    390. 

  390. <a name="l00337"></a>00337 <span class="comment">** [sqlite3_column_text()], one for each column.  ^If an element of a</span>
    391. 

  391. <a name="l00338"></a>00338 <span class="comment">** result row is NULL then the corresponding string pointer for the</span>
    392. 

  392. <a name="l00339"></a>00339 <span class="comment">** sqlite3_exec() callback is a NULL pointer.  ^The 4th argument to the</span>
    393. 

  393. <a name="l00340"></a>00340 <span class="comment">** sqlite3_exec() callback is an array of pointers to strings where each</span>
    394. 

  394. <a name="l00341"></a>00341 <span class="comment">** entry represents the name of corresponding result column as obtained</span>
    395. 

  395. <a name="l00342"></a>00342 <span class="comment">** from [sqlite3_column_name()].</span>
    396. 

  396. <a name="l00343"></a>00343 <span class="comment">**</span>
    397. 

  397. <a name="l00344"></a>00344 <span class="comment">** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer</span>
    398. 

  398. <a name="l00345"></a>00345 <span class="comment">** to an empty string, or a pointer that contains only whitespace and/or </span>
    399. 

  399. <a name="l00346"></a>00346 <span class="comment">** SQL comments, then no SQL statements are evaluated and the database</span>
    400. 

  400. <a name="l00347"></a>00347 <span class="comment">** is not changed.</span>
    401. 

  401. <a name="l00348"></a>00348 <span class="comment">**</span>
    402. 

  402. <a name="l00349"></a>00349 <span class="comment">** Restrictions:</span>
    403. 

  403. <a name="l00350"></a>00350 <span class="comment">**</span>
    404. 

  404. <a name="l00351"></a>00351 <span class="comment">** &lt;ul&gt;</span>
    405. 

  405. <a name="l00352"></a>00352 <span class="comment">** &lt;li&gt; The application must insure that the 1st parameter to sqlite3_exec()</span>
    406. 

  406. <a name="l00353"></a>00353 <span class="comment">**      is a valid and open [database connection].</span>
    407. 

  407. <a name="l00354"></a>00354 <span class="comment">** &lt;li&gt; The application must not close [database connection] specified by</span>
    408. 

  408. <a name="l00355"></a>00355 <span class="comment">**      the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.</span>
    409. 

  409. <a name="l00356"></a>00356 <span class="comment">** &lt;li&gt; The application must not modify the SQL statement text passed into</span>
    410. 

  410. <a name="l00357"></a>00357 <span class="comment">**      the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.</span>
    411. 

  411. <a name="l00358"></a>00358 <span class="comment">** &lt;/ul&gt;</span>
    412. 

  412. <a name="l00359"></a>00359 <span class="comment">*/</span>
    413. 

  413. <a name="l00360"></a>00360 SQLITE_API <span class="keywordtype">int</span> sqlite3_exec(
    414. 

  414. <a name="l00361"></a>00361   <a class="code" href="structsqlite3.html">sqlite3</a>*,                                  <span class="comment">/* An open database */</span>
    415. 

  415. <a name="l00362"></a>00362   <span class="keyword">const</span> <span class="keywordtype">char</span> *sql,                           <span class="comment">/* SQL to be evaluated */</span>
    416. 

  416. <a name="l00363"></a>00363   <span class="keywordtype">int</span> (*callback)(<span class="keywordtype">void</span>*,<span class="keywordtype">int</span>,<span class="keywordtype">char</span>**,<span class="keywordtype">char</span>**),  <span class="comment">/* Callback function */</span>
    417. 

  417. <a name="l00364"></a>00364   <span class="keywordtype">void</span> *,                                    <span class="comment">/* 1st argument to callback */</span>
    418. 

  418. <a name="l00365"></a>00365   <span class="keywordtype">char</span> **errmsg                              <span class="comment">/* Error msg written here */</span>
    419. 

  419. <a name="l00366"></a>00366 );
    420. 

  420. <a name="l00367"></a>00367 
    421. 

  421. <a name="l00368"></a>00368 <span class="comment">/*</span>
    422. 

  422. <a name="l00369"></a>00369 <span class="comment">** CAPI3REF: Result Codes</span>
    423. 

  423. <a name="l00370"></a>00370 <span class="comment">** KEYWORDS: SQLITE_OK {error code} {error codes}</span>
    424. 

  424. <a name="l00371"></a>00371 <span class="comment">** KEYWORDS: {result code} {result codes}</span>
    425. 

  425. <a name="l00372"></a>00372 <span class="comment">**</span>
    426. 

  426. <a name="l00373"></a>00373 <span class="comment">** Many SQLite functions return an integer result code from the set shown</span>
    427. 

  427. <a name="l00374"></a>00374 <span class="comment">** here in order to indicate success or failure.</span>
    428. 

  428. <a name="l00375"></a>00375 <span class="comment">**</span>
    429. 

  429. <a name="l00376"></a>00376 <span class="comment">** New error codes may be added in future versions of SQLite.</span>
    430. 

  430. <a name="l00377"></a>00377 <span class="comment">**</span>
    431. 

  431. <a name="l00378"></a>00378 <span class="comment">** See also: [SQLITE_IOERR_READ | extended result codes],</span>
    432. 

  432. <a name="l00379"></a>00379 <span class="comment">** [sqlite3_vtab_on_conflict()] [SQLITE_ROLLBACK | result codes].</span>
    433. 

  433. <a name="l00380"></a>00380 <span class="comment">*/</span>
    434. 

  434. <a name="l00381"></a>00381 <span class="preprocessor">#define SQLITE_OK           0   </span><span class="comment">/* Successful result */</span>
    435. 

  435. <a name="l00382"></a>00382 <span class="comment">/* beginning-of-error-codes */</span>
    436. 

  436. <a name="l00383"></a>00383 <span class="preprocessor">#define SQLITE_ERROR        1   </span><span class="comment">/* SQL error or missing database */</span>
    437. 

  437. <a name="l00384"></a>00384 <span class="preprocessor">#define SQLITE_INTERNAL     2   </span><span class="comment">/* Internal logic error in SQLite */</span>
    438. 

  438. <a name="l00385"></a>00385 <span class="preprocessor">#define SQLITE_PERM         3   </span><span class="comment">/* Access permission denied */</span>
    439. 

  439. <a name="l00386"></a>00386 <span class="preprocessor">#define SQLITE_ABORT        4   </span><span class="comment">/* Callback routine requested an abort */</span>
    440. 

  440. <a name="l00387"></a>00387 <span class="preprocessor">#define SQLITE_BUSY         5   </span><span class="comment">/* The database file is locked */</span>
    441. 

  441. <a name="l00388"></a>00388 <span class="preprocessor">#define SQLITE_LOCKED       6   </span><span class="comment">/* A table in the database is locked */</span>
    442. 

  442. <a name="l00389"></a>00389 <span class="preprocessor">#define SQLITE_NOMEM        7   </span><span class="comment">/* A malloc() failed */</span>
    443. 

  443. <a name="l00390"></a>00390 <span class="preprocessor">#define SQLITE_READONLY     8   </span><span class="comment">/* Attempt to write a readonly database */</span>
    444. 

  444. <a name="l00391"></a>00391 <span class="preprocessor">#define SQLITE_INTERRUPT    9   </span><span class="comment">/* Operation terminated by sqlite3_interrupt()*/</span>
    445. 

  445. <a name="l00392"></a>00392 <span class="preprocessor">#define SQLITE_IOERR       10   </span><span class="comment">/* Some kind of disk I/O error occurred */</span>
    446. 

  446. <a name="l00393"></a>00393 <span class="preprocessor">#define SQLITE_CORRUPT     11   </span><span class="comment">/* The database disk image is malformed */</span>
    447. 

  447. <a name="l00394"></a>00394 <span class="preprocessor">#define SQLITE_NOTFOUND    12   </span><span class="comment">/* Unknown opcode in sqlite3_file_control() */</span>
    448. 

  448. <a name="l00395"></a>00395 <span class="preprocessor">#define SQLITE_FULL        13   </span><span class="comment">/* Insertion failed because database is full */</span>
    449. 

  449. <a name="l00396"></a>00396 <span class="preprocessor">#define SQLITE_CANTOPEN    14   </span><span class="comment">/* Unable to open the database file */</span>
    450. 

  450. <a name="l00397"></a>00397 <span class="preprocessor">#define SQLITE_PROTOCOL    15   </span><span class="comment">/* Database lock protocol error */</span>
    451. 

  451. <a name="l00398"></a>00398 <span class="preprocessor">#define SQLITE_EMPTY       16   </span><span class="comment">/* Database is empty */</span>
    452. 

  452. <a name="l00399"></a>00399 <span class="preprocessor">#define SQLITE_SCHEMA      17   </span><span class="comment">/* The database schema changed */</span>
    453. 

  453. <a name="l00400"></a>00400 <span class="preprocessor">#define SQLITE_TOOBIG      18   </span><span class="comment">/* String or BLOB exceeds size limit */</span>
    454. 

  454. <a name="l00401"></a>00401 <span class="preprocessor">#define SQLITE_CONSTRAINT  19   </span><span class="comment">/* Abort due to constraint violation */</span>
    455. 

  455. <a name="l00402"></a>00402 <span class="preprocessor">#define SQLITE_MISMATCH    20   </span><span class="comment">/* Data type mismatch */</span>
    456. 

  456. <a name="l00403"></a>00403 <span class="preprocessor">#define SQLITE_MISUSE      21   </span><span class="comment">/* Library used incorrectly */</span>
    457. 

  457. <a name="l00404"></a>00404 <span class="preprocessor">#define SQLITE_NOLFS       22   </span><span class="comment">/* Uses OS features not supported on host */</span>
    458. 

  458. <a name="l00405"></a>00405 <span class="preprocessor">#define SQLITE_AUTH        23   </span><span class="comment">/* Authorization denied */</span>
    459. 

  459. <a name="l00406"></a>00406 <span class="preprocessor">#define SQLITE_FORMAT      24   </span><span class="comment">/* Auxiliary database format error */</span>
    460. 

  460. <a name="l00407"></a>00407 <span class="preprocessor">#define SQLITE_RANGE       25   </span><span class="comment">/* 2nd parameter to sqlite3_bind out of range */</span>
    461. 

  461. <a name="l00408"></a>00408 <span class="preprocessor">#define SQLITE_NOTADB      26   </span><span class="comment">/* File opened that is not a database file */</span>
    462. 

  462. <a name="l00409"></a>00409 <span class="preprocessor">#define SQLITE_ROW         100  </span><span class="comment">/* sqlite3_step() has another row ready */</span>
    463. 

  463. <a name="l00410"></a>00410 <span class="preprocessor">#define SQLITE_DONE        101  </span><span class="comment">/* sqlite3_step() has finished executing */</span>
    464. 

  464. <a name="l00411"></a>00411 <span class="comment">/* end-of-error-codes */</span>
    465. 

  465. <a name="l00412"></a>00412 
    466. 

  466. <a name="l00413"></a>00413 <span class="comment">/*</span>
    467. 

  467. <a name="l00414"></a>00414 <span class="comment">** CAPI3REF: Extended Result Codes</span>
    468. 

  468. <a name="l00415"></a>00415 <span class="comment">** KEYWORDS: {extended error code} {extended error codes}</span>
    469. 

  469. <a name="l00416"></a>00416 <span class="comment">** KEYWORDS: {extended result code} {extended result codes}</span>
    470. 

  470. <a name="l00417"></a>00417 <span class="comment">**</span>
    471. 

  471. <a name="l00418"></a>00418 <span class="comment">** In its default configuration, SQLite API routines return one of 26 integer</span>
    472. 

  472. <a name="l00419"></a>00419 <span class="comment">** [SQLITE_OK | result codes].  However, experience has shown that many of</span>
    473. 

  473. <a name="l00420"></a>00420 <span class="comment">** these result codes are too coarse-grained.  They do not provide as</span>
    474. 

  474. <a name="l00421"></a>00421 <span class="comment">** much information about problems as programmers might like.  In an effort to</span>
    475. 

  475. <a name="l00422"></a>00422 <span class="comment">** address this, newer versions of SQLite (version 3.3.8 and later) include</span>
    476. 

  476. <a name="l00423"></a>00423 <span class="comment">** support for additional result codes that provide more detailed information</span>
    477. 

  477. <a name="l00424"></a>00424 <span class="comment">** about errors. The extended result codes are enabled or disabled</span>
    478. 

  478. <a name="l00425"></a>00425 <span class="comment">** on a per database connection basis using the</span>
    479. 

  479. <a name="l00426"></a>00426 <span class="comment">** [sqlite3_extended_result_codes()] API.</span>
    480. 

  480. <a name="l00427"></a>00427 <span class="comment">**</span>
    481. 

  481. <a name="l00428"></a>00428 <span class="comment">** Some of the available extended result codes are listed here.</span>
    482. 

  482. <a name="l00429"></a>00429 <span class="comment">** One may expect the number of extended result codes will be expand</span>
    483. 

  483. <a name="l00430"></a>00430 <span class="comment">** over time.  Software that uses extended result codes should expect</span>
    484. 

  484. <a name="l00431"></a>00431 <span class="comment">** to see new result codes in future releases of SQLite.</span>
    485. 

  485. <a name="l00432"></a>00432 <span class="comment">**</span>
    486. 

  486. <a name="l00433"></a>00433 <span class="comment">** The SQLITE_OK result code will never be extended.  It will always</span>
    487. 

  487. <a name="l00434"></a>00434 <span class="comment">** be exactly zero.</span>
    488. 

  488. <a name="l00435"></a>00435 <span class="comment">*/</span>
    489. 

  489. <a name="l00436"></a>00436 <span class="preprocessor">#define SQLITE_IOERR_READ              (SQLITE_IOERR | (1&lt;&lt;8))</span>
    490. 

  490. <a name="l00437"></a>00437 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_SHORT_READ        (SQLITE_IOERR | (2&lt;&lt;8))</span>
    491. 

  491. <a name="l00438"></a>00438 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_WRITE             (SQLITE_IOERR | (3&lt;&lt;8))</span>
    492. 

  492. <a name="l00439"></a>00439 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_FSYNC             (SQLITE_IOERR | (4&lt;&lt;8))</span>
    493. 

  493. <a name="l00440"></a>00440 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_DIR_FSYNC         (SQLITE_IOERR | (5&lt;&lt;8))</span>
    494. 

  494. <a name="l00441"></a>00441 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_TRUNCATE          (SQLITE_IOERR | (6&lt;&lt;8))</span>
    495. 

  495. <a name="l00442"></a>00442 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_FSTAT             (SQLITE_IOERR | (7&lt;&lt;8))</span>
    496. 

  496. <a name="l00443"></a>00443 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_UNLOCK            (SQLITE_IOERR | (8&lt;&lt;8))</span>
    497. 

  497. <a name="l00444"></a>00444 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_RDLOCK            (SQLITE_IOERR | (9&lt;&lt;8))</span>
    498. 

  498. <a name="l00445"></a>00445 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_DELETE            (SQLITE_IOERR | (10&lt;&lt;8))</span>
    499. 

  499. <a name="l00446"></a>00446 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_BLOCKED           (SQLITE_IOERR | (11&lt;&lt;8))</span>
    500. 

  500. <a name="l00447"></a>00447 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_NOMEM             (SQLITE_IOERR | (12&lt;&lt;8))</span>
    501. 

  501. <a name="l00448"></a>00448 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_ACCESS            (SQLITE_IOERR | (13&lt;&lt;8))</span>
    502. 

  502. <a name="l00449"></a>00449 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14&lt;&lt;8))</span>
    503. 

  503. <a name="l00450"></a>00450 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_LOCK              (SQLITE_IOERR | (15&lt;&lt;8))</span>
    504. 

  504. <a name="l00451"></a>00451 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_CLOSE             (SQLITE_IOERR | (16&lt;&lt;8))</span>
    505. 

  505. <a name="l00452"></a>00452 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_DIR_CLOSE         (SQLITE_IOERR | (17&lt;&lt;8))</span>
    506. 

  506. <a name="l00453"></a>00453 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_SHMOPEN           (SQLITE_IOERR | (18&lt;&lt;8))</span>
    507. 

  507. <a name="l00454"></a>00454 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_SHMSIZE           (SQLITE_IOERR | (19&lt;&lt;8))</span>
    508. 

  508. <a name="l00455"></a>00455 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_SHMLOCK           (SQLITE_IOERR | (20&lt;&lt;8))</span>
    509. 

  509. <a name="l00456"></a>00456 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_SHMMAP            (SQLITE_IOERR | (21&lt;&lt;8))</span>
    510. 

  510. <a name="l00457"></a>00457 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOERR_SEEK              (SQLITE_IOERR | (22&lt;&lt;8))</span>
    511. 

  511. <a name="l00458"></a>00458 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LOCKED_SHAREDCACHE      (SQLITE_LOCKED |  (1&lt;&lt;8))</span>
    512. 

  512. <a name="l00459"></a>00459 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_BUSY_RECOVERY           (SQLITE_BUSY   |  (1&lt;&lt;8))</span>
    513. 

  513. <a name="l00460"></a>00460 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_CANTOPEN_NOTEMPDIR      (SQLITE_CANTOPEN | (1&lt;&lt;8))</span>
    514. 

  514. <a name="l00461"></a>00461 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_CORRUPT_VTAB            (SQLITE_CORRUPT | (1&lt;&lt;8))</span>
    515. 

  515. <a name="l00462"></a>00462 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_READONLY_RECOVERY       (SQLITE_READONLY | (1&lt;&lt;8))</span>
    516. 

  516. <a name="l00463"></a>00463 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_READONLY_CANTLOCK       (SQLITE_READONLY | (2&lt;&lt;8))</span>
    517. 

  517. <a name="l00464"></a>00464 <span class="preprocessor"></span>
    518. 

  518. <a name="l00465"></a>00465 <span class="comment">/*</span>
    519. 

  519. <a name="l00466"></a>00466 <span class="comment">** CAPI3REF: Flags For File Open Operations</span>
    520. 

  520. <a name="l00467"></a>00467 <span class="comment">**</span>
    521. 

  521. <a name="l00468"></a>00468 <span class="comment">** These bit values are intended for use in the</span>
    522. 

  522. <a name="l00469"></a>00469 <span class="comment">** 3rd parameter to the [sqlite3_open_v2()] interface and</span>
    523. 

  523. <a name="l00470"></a>00470 <span class="comment">** in the 4th parameter to the [sqlite3_vfs.xOpen] method.</span>
    524. 

  524. <a name="l00471"></a>00471 <span class="comment">*/</span>
    525. 

  525. <a name="l00472"></a>00472 <span class="preprocessor">#define SQLITE_OPEN_READONLY         0x00000001  </span><span class="comment">/* Ok for sqlite3_open_v2() */</span>
    526. 

  526. <a name="l00473"></a>00473 <span class="preprocessor">#define SQLITE_OPEN_READWRITE        0x00000002  </span><span class="comment">/* Ok for sqlite3_open_v2() */</span>
    527. 

  527. <a name="l00474"></a>00474 <span class="preprocessor">#define SQLITE_OPEN_CREATE           0x00000004  </span><span class="comment">/* Ok for sqlite3_open_v2() */</span>
    528. 

  528. <a name="l00475"></a>00475 <span class="preprocessor">#define SQLITE_OPEN_DELETEONCLOSE    0x00000008  </span><span class="comment">/* VFS only */</span>
    529. 

  529. <a name="l00476"></a>00476 <span class="preprocessor">#define SQLITE_OPEN_EXCLUSIVE        0x00000010  </span><span class="comment">/* VFS only */</span>
    530. 

  530. <a name="l00477"></a>00477 <span class="preprocessor">#define SQLITE_OPEN_AUTOPROXY        0x00000020  </span><span class="comment">/* VFS only */</span>
    531. 

  531. <a name="l00478"></a>00478 <span class="preprocessor">#define SQLITE_OPEN_URI              0x00000040  </span><span class="comment">/* Ok for sqlite3_open_v2() */</span>
    532. 

  532. <a name="l00479"></a>00479 <span class="preprocessor">#define SQLITE_OPEN_MAIN_DB          0x00000100  </span><span class="comment">/* VFS only */</span>
    533. 

  533. <a name="l00480"></a>00480 <span class="preprocessor">#define SQLITE_OPEN_TEMP_DB          0x00000200  </span><span class="comment">/* VFS only */</span>
    534. 

  534. <a name="l00481"></a>00481 <span class="preprocessor">#define SQLITE_OPEN_TRANSIENT_DB     0x00000400  </span><span class="comment">/* VFS only */</span>
    535. 

  535. <a name="l00482"></a>00482 <span class="preprocessor">#define SQLITE_OPEN_MAIN_JOURNAL     0x00000800  </span><span class="comment">/* VFS only */</span>
    536. 

  536. <a name="l00483"></a>00483 <span class="preprocessor">#define SQLITE_OPEN_TEMP_JOURNAL     0x00001000  </span><span class="comment">/* VFS only */</span>
    537. 

  537. <a name="l00484"></a>00484 <span class="preprocessor">#define SQLITE_OPEN_SUBJOURNAL       0x00002000  </span><span class="comment">/* VFS only */</span>
    538. 

  538. <a name="l00485"></a>00485 <span class="preprocessor">#define SQLITE_OPEN_MASTER_JOURNAL   0x00004000  </span><span class="comment">/* VFS only */</span>
    539. 

  539. <a name="l00486"></a>00486 <span class="preprocessor">#define SQLITE_OPEN_NOMUTEX          0x00008000  </span><span class="comment">/* Ok for sqlite3_open_v2() */</span>
    540. 

  540. <a name="l00487"></a>00487 <span class="preprocessor">#define SQLITE_OPEN_FULLMUTEX        0x00010000  </span><span class="comment">/* Ok for sqlite3_open_v2() */</span>
    541. 

  541. <a name="l00488"></a>00488 <span class="preprocessor">#define SQLITE_OPEN_SHAREDCACHE      0x00020000  </span><span class="comment">/* Ok for sqlite3_open_v2() */</span>
    542. 

  542. <a name="l00489"></a>00489 <span class="preprocessor">#define SQLITE_OPEN_PRIVATECACHE     0x00040000  </span><span class="comment">/* Ok for sqlite3_open_v2() */</span>
    543. 

  543. <a name="l00490"></a>00490 <span class="preprocessor">#define SQLITE_OPEN_WAL              0x00080000  </span><span class="comment">/* VFS only */</span>
    544. 

  544. <a name="l00491"></a>00491 
    545. 

  545. <a name="l00492"></a>00492 <span class="comment">/* Reserved:                         0x00F00000 */</span>
    546. 

  546. <a name="l00493"></a>00493 
    547. 

  547. <a name="l00494"></a>00494 <span class="comment">/*</span>
    548. 

  548. <a name="l00495"></a>00495 <span class="comment">** CAPI3REF: Device Characteristics</span>
    549. 

  549. <a name="l00496"></a>00496 <span class="comment">**</span>
    550. 

  550. <a name="l00497"></a>00497 <span class="comment">** The xDeviceCharacteristics method of the [sqlite3_io_methods]</span>
    551. 

  551. <a name="l00498"></a>00498 <span class="comment">** object returns an integer which is a vector of the these</span>
    552. 

  552. <a name="l00499"></a>00499 <span class="comment">** bit values expressing I/O characteristics of the mass storage</span>
    553. 

  553. <a name="l00500"></a>00500 <span class="comment">** device that holds the file that the [sqlite3_io_methods]</span>
    554. 

  554. <a name="l00501"></a>00501 <span class="comment">** refers to.</span>
    555. 

  555. <a name="l00502"></a>00502 <span class="comment">**</span>
    556. 

  556. <a name="l00503"></a>00503 <span class="comment">** The SQLITE_IOCAP_ATOMIC property means that all writes of</span>
    557. 

  557. <a name="l00504"></a>00504 <span class="comment">** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values</span>
    558. 

  558. <a name="l00505"></a>00505 <span class="comment">** mean that writes of blocks that are nnn bytes in size and</span>
    559. 

  559. <a name="l00506"></a>00506 <span class="comment">** are aligned to an address which is an integer multiple of</span>
    560. 

  560. <a name="l00507"></a>00507 <span class="comment">** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means</span>
    561. 

  561. <a name="l00508"></a>00508 <span class="comment">** that when data is appended to a file, the data is appended</span>
    562. 

  562. <a name="l00509"></a>00509 <span class="comment">** first then the size of the file is extended, never the other</span>
    563. 

  563. <a name="l00510"></a>00510 <span class="comment">** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that</span>
    564. 

  564. <a name="l00511"></a>00511 <span class="comment">** information is written to disk in the same order as calls</span>
    565. 

  565. <a name="l00512"></a>00512 <span class="comment">** to xWrite().  The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that</span>
    566. 

  566. <a name="l00513"></a>00513 <span class="comment">** after reboot following a crash or power loss, the only bytes in a</span>
    567. 

  567. <a name="l00514"></a>00514 <span class="comment">** file that were written at the application level might have changed</span>
    568. 

  568. <a name="l00515"></a>00515 <span class="comment">** and that adjacent bytes, even bytes within the same sector are</span>
    569. 

  569. <a name="l00516"></a>00516 <span class="comment">** guaranteed to be unchanged.</span>
    570. 

  570. <a name="l00517"></a>00517 <span class="comment">*/</span>
    571. 

  571. <a name="l00518"></a>00518 <span class="preprocessor">#define SQLITE_IOCAP_ATOMIC                 0x00000001</span>
    572. 

  572. <a name="l00519"></a>00519 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOCAP_ATOMIC512              0x00000002</span>
    573. 

  573. <a name="l00520"></a>00520 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOCAP_ATOMIC1K               0x00000004</span>
    574. 

  574. <a name="l00521"></a>00521 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOCAP_ATOMIC2K               0x00000008</span>
    575. 

  575. <a name="l00522"></a>00522 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOCAP_ATOMIC4K               0x00000010</span>
    576. 

  576. <a name="l00523"></a>00523 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOCAP_ATOMIC8K               0x00000020</span>
    577. 

  577. <a name="l00524"></a>00524 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOCAP_ATOMIC16K              0x00000040</span>
    578. 

  578. <a name="l00525"></a>00525 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOCAP_ATOMIC32K              0x00000080</span>
    579. 

  579. <a name="l00526"></a>00526 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOCAP_ATOMIC64K              0x00000100</span>
    580. 

  580. <a name="l00527"></a>00527 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOCAP_SAFE_APPEND            0x00000200</span>
    581. 

  581. <a name="l00528"></a>00528 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOCAP_SEQUENTIAL             0x00000400</span>
    582. 

  582. <a name="l00529"></a>00529 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN  0x00000800</span>
    583. 

  583. <a name="l00530"></a>00530 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_IOCAP_POWERSAFE_OVERWRITE    0x00001000</span>
    584. 

  584. <a name="l00531"></a>00531 <span class="preprocessor"></span>
    585. 

  585. <a name="l00532"></a>00532 <span class="comment">/*</span>
    586. 

  586. <a name="l00533"></a>00533 <span class="comment">** CAPI3REF: File Locking Levels</span>
    587. 

  587. <a name="l00534"></a>00534 <span class="comment">**</span>
    588. 

  588. <a name="l00535"></a>00535 <span class="comment">** SQLite uses one of these integer values as the second</span>
    589. 

  589. <a name="l00536"></a>00536 <span class="comment">** argument to calls it makes to the xLock() and xUnlock() methods</span>
    590. 

  590. <a name="l00537"></a>00537 <span class="comment">** of an [sqlite3_io_methods] object.</span>
    591. 

  591. <a name="l00538"></a>00538 <span class="comment">*/</span>
    592. 

  592. <a name="l00539"></a>00539 <span class="preprocessor">#define SQLITE_LOCK_NONE          0</span>
    593. 

  593. <a name="l00540"></a>00540 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LOCK_SHARED        1</span>
    594. 

  594. <a name="l00541"></a>00541 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LOCK_RESERVED      2</span>
    595. 

  595. <a name="l00542"></a>00542 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LOCK_PENDING       3</span>
    596. 

  596. <a name="l00543"></a>00543 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LOCK_EXCLUSIVE     4</span>
    597. 

  597. <a name="l00544"></a>00544 <span class="preprocessor"></span>
    598. 

  598. <a name="l00545"></a>00545 <span class="comment">/*</span>
    599. 

  599. <a name="l00546"></a>00546 <span class="comment">** CAPI3REF: Synchronization Type Flags</span>
    600. 

  600. <a name="l00547"></a>00547 <span class="comment">**</span>
    601. 

  601. <a name="l00548"></a>00548 <span class="comment">** When SQLite invokes the xSync() method of an</span>
    602. 

  602. <a name="l00549"></a>00549 <span class="comment">** [sqlite3_io_methods] object it uses a combination of</span>
    603. 

  603. <a name="l00550"></a>00550 <span class="comment">** these integer values as the second argument.</span>
    604. 

  604. <a name="l00551"></a>00551 <span class="comment">**</span>
    605. 

  605. <a name="l00552"></a>00552 <span class="comment">** When the SQLITE_SYNC_DATAONLY flag is used, it means that the</span>
    606. 

  606. <a name="l00553"></a>00553 <span class="comment">** sync operation only needs to flush data to mass storage.  Inode</span>
    607. 

  607. <a name="l00554"></a>00554 <span class="comment">** information need not be flushed. If the lower four bits of the flag</span>
    608. 

  608. <a name="l00555"></a>00555 <span class="comment">** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.</span>
    609. 

  609. <a name="l00556"></a>00556 <span class="comment">** If the lower four bits equal SQLITE_SYNC_FULL, that means</span>
    610. 

  610. <a name="l00557"></a>00557 <span class="comment">** to use Mac OS X style fullsync instead of fsync().</span>
    611. 

  611. <a name="l00558"></a>00558 <span class="comment">**</span>
    612. 

  612. <a name="l00559"></a>00559 <span class="comment">** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags</span>
    613. 

  613. <a name="l00560"></a>00560 <span class="comment">** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL</span>
    614. 

  614. <a name="l00561"></a>00561 <span class="comment">** settings.  The [synchronous pragma] determines when calls to the</span>
    615. 

  615. <a name="l00562"></a>00562 <span class="comment">** xSync VFS method occur and applies uniformly across all platforms.</span>
    616. 

  616. <a name="l00563"></a>00563 <span class="comment">** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how</span>
    617. 

  617. <a name="l00564"></a>00564 <span class="comment">** energetic or rigorous or forceful the sync operations are and</span>
    618. 

  618. <a name="l00565"></a>00565 <span class="comment">** only make a difference on Mac OSX for the default SQLite code.</span>
    619. 

  619. <a name="l00566"></a>00566 <span class="comment">** (Third-party VFS implementations might also make the distinction</span>
    620. 

  620. <a name="l00567"></a>00567 <span class="comment">** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the</span>
    621. 

  621. <a name="l00568"></a>00568 <span class="comment">** operating systems natively supported by SQLite, only Mac OSX</span>
    622. 

  622. <a name="l00569"></a>00569 <span class="comment">** cares about the difference.)</span>
    623. 

  623. <a name="l00570"></a>00570 <span class="comment">*/</span>
    624. 

  624. <a name="l00571"></a>00571 <span class="preprocessor">#define SQLITE_SYNC_NORMAL        0x00002</span>
    625. 

  625. <a name="l00572"></a>00572 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_SYNC_FULL          0x00003</span>
    626. 

  626. <a name="l00573"></a>00573 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_SYNC_DATAONLY      0x00010</span>
    627. 

  627. <a name="l00574"></a>00574 <span class="preprocessor"></span>
    628. 

  628. <a name="l00575"></a>00575 <span class="comment">/*</span>
    629. 

  629. <a name="l00576"></a>00576 <span class="comment">** CAPI3REF: OS Interface Open File Handle</span>
    630. 

  630. <a name="l00577"></a>00577 <span class="comment">**</span>
    631. 

  631. <a name="l00578"></a>00578 <span class="comment">** An [sqlite3_file] object represents an open file in the </span>
    632. 

  632. <a name="l00579"></a>00579 <span class="comment">** [sqlite3_vfs | OS interface layer].  Individual OS interface</span>
    633. 

  633. <a name="l00580"></a>00580 <span class="comment">** implementations will</span>
    634. 

  634. <a name="l00581"></a>00581 <span class="comment">** want to subclass this object by appending additional fields</span>
    635. 

  635. <a name="l00582"></a>00582 <span class="comment">** for their own use.  The pMethods entry is a pointer to an</span>
    636. 

  636. <a name="l00583"></a>00583 <span class="comment">** [sqlite3_io_methods] object that defines methods for performing</span>
    637. 

  637. <a name="l00584"></a>00584 <span class="comment">** I/O operations on the open file.</span>
    638. 

  638. <a name="l00585"></a>00585 <span class="comment">*/</span>
    639. 

  639. <a name="l00586"></a>00586 <span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="structsqlite3__file.html">sqlite3_file</a> <a class="code" href="structsqlite3__file.html">sqlite3_file</a>;
    640. 

  640. <a name="l00587"></a>00587 <span class="keyword">struct </span><a class="code" href="structsqlite3__file.html">sqlite3_file</a> {
    641. 

  641. <a name="l00588"></a>00588   <span class="keyword">const</span> <span class="keyword">struct </span><a class="code" href="structsqlite3__io__methods.html">sqlite3_io_methods</a> *pMethods;  <span class="comment">/* Methods for an open file */</span>
    642. 

  642. <a name="l00589"></a>00589 };
    643. 

  643. <a name="l00590"></a>00590 
    644. 

  644. <a name="l00591"></a>00591 <span class="comment">/*</span>
    645. 

  645. <a name="l00592"></a>00592 <span class="comment">** CAPI3REF: OS Interface File Virtual Methods Object</span>
    646. 

  646. <a name="l00593"></a>00593 <span class="comment">**</span>
    647. 

  647. <a name="l00594"></a>00594 <span class="comment">** Every file opened by the [sqlite3_vfs.xOpen] method populates an</span>
    648. 

  648. <a name="l00595"></a>00595 <span class="comment">** [sqlite3_file] object (or, more commonly, a subclass of the</span>
    649. 

  649. <a name="l00596"></a>00596 <span class="comment">** [sqlite3_file] object) with a pointer to an instance of this object.</span>
    650. 

  650. <a name="l00597"></a>00597 <span class="comment">** This object defines the methods used to perform various operations</span>
    651. 

  651. <a name="l00598"></a>00598 <span class="comment">** against the open file represented by the [sqlite3_file] object.</span>
    652. 

  652. <a name="l00599"></a>00599 <span class="comment">**</span>
    653. 

  653. <a name="l00600"></a>00600 <span class="comment">** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element </span>
    654. 

  654. <a name="l00601"></a>00601 <span class="comment">** to a non-NULL pointer, then the sqlite3_io_methods.xClose method</span>
    655. 

  655. <a name="l00602"></a>00602 <span class="comment">** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed.  The</span>
    656. 

  656. <a name="l00603"></a>00603 <span class="comment">** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]</span>
    657. 

  657. <a name="l00604"></a>00604 <span class="comment">** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element</span>
    658. 

  658. <a name="l00605"></a>00605 <span class="comment">** to NULL.</span>
    659. 

  659. <a name="l00606"></a>00606 <span class="comment">**</span>
    660. 

  660. <a name="l00607"></a>00607 <span class="comment">** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or</span>
    661. 

  661. <a name="l00608"></a>00608 <span class="comment">** [SQLITE_SYNC_FULL].  The first choice is the normal fsync().</span>
    662. 

  662. <a name="l00609"></a>00609 <span class="comment">** The second choice is a Mac OS X style fullsync.  The [SQLITE_SYNC_DATAONLY]</span>
    663. 

  663. <a name="l00610"></a>00610 <span class="comment">** flag may be ORed in to indicate that only the data of the file</span>
    664. 

  664. <a name="l00611"></a>00611 <span class="comment">** and not its inode needs to be synced.</span>
    665. 

  665. <a name="l00612"></a>00612 <span class="comment">**</span>
    666. 

  666. <a name="l00613"></a>00613 <span class="comment">** The integer values to xLock() and xUnlock() are one of</span>
    667. 

  667. <a name="l00614"></a>00614 <span class="comment">** &lt;ul&gt;</span>
    668. 

  668. <a name="l00615"></a>00615 <span class="comment">** &lt;li&gt; [SQLITE_LOCK_NONE],</span>
    669. 

  669. <a name="l00616"></a>00616 <span class="comment">** &lt;li&gt; [SQLITE_LOCK_SHARED],</span>
    670. 

  670. <a name="l00617"></a>00617 <span class="comment">** &lt;li&gt; [SQLITE_LOCK_RESERVED],</span>
    671. 

  671. <a name="l00618"></a>00618 <span class="comment">** &lt;li&gt; [SQLITE_LOCK_PENDING], or</span>
    672. 

  672. <a name="l00619"></a>00619 <span class="comment">** &lt;li&gt; [SQLITE_LOCK_EXCLUSIVE].</span>
    673. 

  673. <a name="l00620"></a>00620 <span class="comment">** &lt;/ul&gt;</span>
    674. 

  674. <a name="l00621"></a>00621 <span class="comment">** xLock() increases the lock. xUnlock() decreases the lock.</span>
    675. 

  675. <a name="l00622"></a>00622 <span class="comment">** The xCheckReservedLock() method checks whether any database connection,</span>
    676. 

  676. <a name="l00623"></a>00623 <span class="comment">** either in this process or in some other process, is holding a RESERVED,</span>
    677. 

  677. <a name="l00624"></a>00624 <span class="comment">** PENDING, or EXCLUSIVE lock on the file.  It returns true</span>
    678. 

  678. <a name="l00625"></a>00625 <span class="comment">** if such a lock exists and false otherwise.</span>
    679. 

  679. <a name="l00626"></a>00626 <span class="comment">**</span>
    680. 

  680. <a name="l00627"></a>00627 <span class="comment">** The xFileControl() method is a generic interface that allows custom</span>
    681. 

  681. <a name="l00628"></a>00628 <span class="comment">** VFS implementations to directly control an open file using the</span>
    682. 

  682. <a name="l00629"></a>00629 <span class="comment">** [sqlite3_file_control()] interface.  The second &quot;op&quot; argument is an</span>
    683. 

  683. <a name="l00630"></a>00630 <span class="comment">** integer opcode.  The third argument is a generic pointer intended to</span>
    684. 

  684. <a name="l00631"></a>00631 <span class="comment">** point to a structure that may contain arguments or space in which to</span>
    685. 

  685. <a name="l00632"></a>00632 <span class="comment">** write return values.  Potential uses for xFileControl() might be</span>
    686. 

  686. <a name="l00633"></a>00633 <span class="comment">** functions to enable blocking locks with timeouts, to change the</span>
    687. 

  687. <a name="l00634"></a>00634 <span class="comment">** locking strategy (for example to use dot-file locks), to inquire</span>
    688. 

  688. <a name="l00635"></a>00635 <span class="comment">** about the status of a lock, or to break stale locks.  The SQLite</span>
    689. 

  689. <a name="l00636"></a>00636 <span class="comment">** core reserves all opcodes less than 100 for its own use.</span>
    690. 

  690. <a name="l00637"></a>00637 <span class="comment">** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.</span>
    691. 

  691. <a name="l00638"></a>00638 <span class="comment">** Applications that define a custom xFileControl method should use opcodes</span>
    692. 

  692. <a name="l00639"></a>00639 <span class="comment">** greater than 100 to avoid conflicts.  VFS implementations should</span>
    693. 

  693. <a name="l00640"></a>00640 <span class="comment">** return [SQLITE_NOTFOUND] for file control opcodes that they do not</span>
    694. 

  694. <a name="l00641"></a>00641 <span class="comment">** recognize.</span>
    695. 

  695. <a name="l00642"></a>00642 <span class="comment">**</span>
    696. 

  696. <a name="l00643"></a>00643 <span class="comment">** The xSectorSize() method returns the sector size of the</span>
    697. 

  697. <a name="l00644"></a>00644 <span class="comment">** device that underlies the file.  The sector size is the</span>
    698. 

  698. <a name="l00645"></a>00645 <span class="comment">** minimum write that can be performed without disturbing</span>
    699. 

  699. <a name="l00646"></a>00646 <span class="comment">** other bytes in the file.  The xDeviceCharacteristics()</span>
    700. 

  700. <a name="l00647"></a>00647 <span class="comment">** method returns a bit vector describing behaviors of the</span>
    701. 

  701. <a name="l00648"></a>00648 <span class="comment">** underlying device:</span>
    702. 

  702. <a name="l00649"></a>00649 <span class="comment">**</span>
    703. 

  703. <a name="l00650"></a>00650 <span class="comment">** &lt;ul&gt;</span>
    704. 

  704. <a name="l00651"></a>00651 <span class="comment">** &lt;li&gt; [SQLITE_IOCAP_ATOMIC]</span>
    705. 

  705. <a name="l00652"></a>00652 <span class="comment">** &lt;li&gt; [SQLITE_IOCAP_ATOMIC512]</span>
    706. 

  706. <a name="l00653"></a>00653 <span class="comment">** &lt;li&gt; [SQLITE_IOCAP_ATOMIC1K]</span>
    707. 

  707. <a name="l00654"></a>00654 <span class="comment">** &lt;li&gt; [SQLITE_IOCAP_ATOMIC2K]</span>
    708. 

  708. <a name="l00655"></a>00655 <span class="comment">** &lt;li&gt; [SQLITE_IOCAP_ATOMIC4K]</span>
    709. 

  709. <a name="l00656"></a>00656 <span class="comment">** &lt;li&gt; [SQLITE_IOCAP_ATOMIC8K]</span>
    710. 

  710. <a name="l00657"></a>00657 <span class="comment">** &lt;li&gt; [SQLITE_IOCAP_ATOMIC16K]</span>
    711. 

  711. <a name="l00658"></a>00658 <span class="comment">** &lt;li&gt; [SQLITE_IOCAP_ATOMIC32K]</span>
    712. 

  712. <a name="l00659"></a>00659 <span class="comment">** &lt;li&gt; [SQLITE_IOCAP_ATOMIC64K]</span>
    713. 

  713. <a name="l00660"></a>00660 <span class="comment">** &lt;li&gt; [SQLITE_IOCAP_SAFE_APPEND]</span>
    714. 

  714. <a name="l00661"></a>00661 <span class="comment">** &lt;li&gt; [SQLITE_IOCAP_SEQUENTIAL]</span>
    715. 

  715. <a name="l00662"></a>00662 <span class="comment">** &lt;/ul&gt;</span>
    716. 

  716. <a name="l00663"></a>00663 <span class="comment">**</span>
    717. 

  717. <a name="l00664"></a>00664 <span class="comment">** The SQLITE_IOCAP_ATOMIC property means that all writes of</span>
    718. 

  718. <a name="l00665"></a>00665 <span class="comment">** any size are atomic.  The SQLITE_IOCAP_ATOMICnnn values</span>
    719. 

  719. <a name="l00666"></a>00666 <span class="comment">** mean that writes of blocks that are nnn bytes in size and</span>
    720. 

  720. <a name="l00667"></a>00667 <span class="comment">** are aligned to an address which is an integer multiple of</span>
    721. 

  721. <a name="l00668"></a>00668 <span class="comment">** nnn are atomic.  The SQLITE_IOCAP_SAFE_APPEND value means</span>
    722. 

  722. <a name="l00669"></a>00669 <span class="comment">** that when data is appended to a file, the data is appended</span>
    723. 

  723. <a name="l00670"></a>00670 <span class="comment">** first then the size of the file is extended, never the other</span>
    724. 

  724. <a name="l00671"></a>00671 <span class="comment">** way around.  The SQLITE_IOCAP_SEQUENTIAL property means that</span>
    725. 

  725. <a name="l00672"></a>00672 <span class="comment">** information is written to disk in the same order as calls</span>
    726. 

  726. <a name="l00673"></a>00673 <span class="comment">** to xWrite().</span>
    727. 

  727. <a name="l00674"></a>00674 <span class="comment">**</span>
    728. 

  728. <a name="l00675"></a>00675 <span class="comment">** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill</span>
    729. 

  729. <a name="l00676"></a>00676 <span class="comment">** in the unread portions of the buffer with zeros.  A VFS that</span>
    730. 

  730. <a name="l00677"></a>00677 <span class="comment">** fails to zero-fill short reads might seem to work.  However,</span>
    731. 

  731. <a name="l00678"></a>00678 <span class="comment">** failure to zero-fill short reads will eventually lead to</span>
    732. 

  732. <a name="l00679"></a>00679 <span class="comment">** database corruption.</span>
    733. 

  733. <a name="l00680"></a>00680 <span class="comment">*/</span>
    734. 

  734. <a name="l00681"></a>00681 <span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="structsqlite3__io__methods.html">sqlite3_io_methods</a> <a class="code" href="structsqlite3__io__methods.html">sqlite3_io_methods</a>;
    735. 

  735. <a name="l00682"></a>00682 <span class="keyword">struct </span><a class="code" href="structsqlite3__io__methods.html">sqlite3_io_methods</a> {
    736. 

  736. <a name="l00683"></a>00683   <span class="keywordtype">int</span> iVersion;
    737. 

  737. <a name="l00684"></a>00684   int (*xClose)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*);
    738. 

  738. <a name="l00685"></a>00685   int (*xRead)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*, <span class="keywordtype">void</span>*, <span class="keywordtype">int</span> iAmt, sqlite3_int64 iOfst);
    739. 

  739. <a name="l00686"></a>00686   int (*xWrite)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*, <span class="keyword">const</span> <span class="keywordtype">void</span>*, <span class="keywordtype">int</span> iAmt, sqlite3_int64 iOfst);
    740. 

  740. <a name="l00687"></a>00687   int (*xTruncate)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*, sqlite3_int64 size);
    741. 

  741. <a name="l00688"></a>00688   int (*xSync)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*, <span class="keywordtype">int</span> flags);
    742. 

  742. <a name="l00689"></a>00689   int (*xFileSize)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*, sqlite3_int64 *pSize);
    743. 

  743. <a name="l00690"></a>00690   int (*xLock)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*, int);
    744. 

  744. <a name="l00691"></a>00691   int (*xUnlock)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*, int);
    745. 

  745. <a name="l00692"></a>00692   int (*xCheckReservedLock)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*, <span class="keywordtype">int</span> *pResOut);
    746. 

  746. <a name="l00693"></a>00693   int (*xFileControl)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*, <span class="keywordtype">int</span> op, <span class="keywordtype">void</span> *pArg);
    747. 

  747. <a name="l00694"></a>00694   int (*xSectorSize)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*);
    748. 

  748. <a name="l00695"></a>00695   int (*xDeviceCharacteristics)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*);
    749. 

  749. <a name="l00696"></a>00696   <span class="comment">/* Methods above are valid for version 1 */</span>
    750. 

  750. <a name="l00697"></a>00697   int (*xShmMap)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*, <span class="keywordtype">int</span> iPg, <span class="keywordtype">int</span> pgsz, int, <span class="keywordtype">void</span> <span class="keyword">volatile</span>**);
    751. 

  751. <a name="l00698"></a>00698   int (*xShmLock)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*, <span class="keywordtype">int</span> offset, <span class="keywordtype">int</span> n, <span class="keywordtype">int</span> flags);
    752. 

  752. <a name="l00699"></a>00699   void (*xShmBarrier)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*);
    753. 

  753. <a name="l00700"></a>00700   int (*xShmUnmap)(<a class="code" href="structsqlite3__file.html">sqlite3_file</a>*, <span class="keywordtype">int</span> deleteFlag);
    754. 

  754. <a name="l00701"></a>00701   <span class="comment">/* Methods above are valid for version 2 */</span>
    755. 

  755. <a name="l00702"></a>00702   <span class="comment">/* Additional methods may be added in future releases */</span>
    756. 

  756. <a name="l00703"></a>00703 };
    757. 

  757. <a name="l00704"></a>00704 
    758. 

  758. <a name="l00705"></a>00705 <span class="comment">/*</span>
    759. 

  759. <a name="l00706"></a>00706 <span class="comment">** CAPI3REF: Standard File Control Opcodes</span>
    760. 

  760. <a name="l00707"></a>00707 <span class="comment">**</span>
    761. 

  761. <a name="l00708"></a>00708 <span class="comment">** These integer constants are opcodes for the xFileControl method</span>
    762. 

  762. <a name="l00709"></a>00709 <span class="comment">** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]</span>
    763. 

  763. <a name="l00710"></a>00710 <span class="comment">** interface.</span>
    764. 

  764. <a name="l00711"></a>00711 <span class="comment">**</span>
    765. 

  765. <a name="l00712"></a>00712 <span class="comment">** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging.  This</span>
    766. 

  766. <a name="l00713"></a>00713 <span class="comment">** opcode causes the xFileControl method to write the current state of</span>
    767. 

  767. <a name="l00714"></a>00714 <span class="comment">** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],</span>
    768. 

  768. <a name="l00715"></a>00715 <span class="comment">** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])</span>
    769. 

  769. <a name="l00716"></a>00716 <span class="comment">** into an integer that the pArg argument points to. This capability</span>
    770. 

  770. <a name="l00717"></a>00717 <span class="comment">** is used during testing and only needs to be supported when SQLITE_TEST</span>
    771. 

  771. <a name="l00718"></a>00718 <span class="comment">** is defined.</span>
    772. 

  772. <a name="l00719"></a>00719 <span class="comment">**</span>
    773. 

  773. <a name="l00720"></a>00720 <span class="comment">** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS</span>
    774. 

  774. <a name="l00721"></a>00721 <span class="comment">** layer a hint of how large the database file will grow to be during the</span>
    775. 

  775. <a name="l00722"></a>00722 <span class="comment">** current transaction.  This hint is not guaranteed to be accurate but it</span>
    776. 

  776. <a name="l00723"></a>00723 <span class="comment">** is often close.  The underlying VFS might choose to preallocate database</span>
    777. 

  777. <a name="l00724"></a>00724 <span class="comment">** file space based on this hint in order to help writes to the database</span>
    778. 

  778. <a name="l00725"></a>00725 <span class="comment">** file run faster.</span>
    779. 

  779. <a name="l00726"></a>00726 <span class="comment">**</span>
    780. 

  780. <a name="l00727"></a>00727 <span class="comment">** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS</span>
    781. 

  781. <a name="l00728"></a>00728 <span class="comment">** extends and truncates the database file in chunks of a size specified</span>
    782. 

  782. <a name="l00729"></a>00729 <span class="comment">** by the user. The fourth argument to [sqlite3_file_control()] should </span>
    783. 

  783. <a name="l00730"></a>00730 <span class="comment">** point to an integer (type int) containing the new chunk-size to use</span>
    784. 

  784. <a name="l00731"></a>00731 <span class="comment">** for the nominated database. Allocating database file space in large</span>
    785. 

  785. <a name="l00732"></a>00732 <span class="comment">** chunks (say 1MB at a time), may reduce file-system fragmentation and</span>
    786. 

  786. <a name="l00733"></a>00733 <span class="comment">** improve performance on some systems.</span>
    787. 

  787. <a name="l00734"></a>00734 <span class="comment">**</span>
    788. 

  788. <a name="l00735"></a>00735 <span class="comment">** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer</span>
    789. 

  789. <a name="l00736"></a>00736 <span class="comment">** to the [sqlite3_file] object associated with a particular database</span>
    790. 

  790. <a name="l00737"></a>00737 <span class="comment">** connection.  See the [sqlite3_file_control()] documentation for</span>
    791. 

  791. <a name="l00738"></a>00738 <span class="comment">** additional information.</span>
    792. 

  792. <a name="l00739"></a>00739 <span class="comment">**</span>
    793. 

  793. <a name="l00740"></a>00740 <span class="comment">** ^(The [SQLITE_FCNTL_SYNC_OMITTED] opcode is generated internally by</span>
    794. 

  794. <a name="l00741"></a>00741 <span class="comment">** SQLite and sent to all VFSes in place of a call to the xSync method</span>
    795. 

  795. <a name="l00742"></a>00742 <span class="comment">** when the database connection has [PRAGMA synchronous] set to OFF.)^</span>
    796. 

  796. <a name="l00743"></a>00743 <span class="comment">** Some specialized VFSes need this signal in order to operate correctly</span>
    797. 

  797. <a name="l00744"></a>00744 <span class="comment">** when [PRAGMA synchronous | PRAGMA synchronous=OFF] is set, but most </span>
    798. 

  798. <a name="l00745"></a>00745 <span class="comment">** VFSes do not need this signal and should silently ignore this opcode.</span>
    799. 

  799. <a name="l00746"></a>00746 <span class="comment">** Applications should not call [sqlite3_file_control()] with this</span>
    800. 

  800. <a name="l00747"></a>00747 <span class="comment">** opcode as doing so may disrupt the operation of the specialized VFSes</span>
    801. 

  801. <a name="l00748"></a>00748 <span class="comment">** that do require it.  </span>
    802. 

  802. <a name="l00749"></a>00749 <span class="comment">**</span>
    803. 

  803. <a name="l00750"></a>00750 <span class="comment">** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic</span>
    804. 

  804. <a name="l00751"></a>00751 <span class="comment">** retry counts and intervals for certain disk I/O operations for the</span>
    805. 

  805. <a name="l00752"></a>00752 <span class="comment">** windows [VFS] in order to provide robustness in the presence of</span>
    806. 

  806. <a name="l00753"></a>00753 <span class="comment">** anti-virus programs.  By default, the windows VFS will retry file read,</span>
    807. 

  807. <a name="l00754"></a>00754 <span class="comment">** file write, and file delete operations up to 10 times, with a delay</span>
    808. 

  808. <a name="l00755"></a>00755 <span class="comment">** of 25 milliseconds before the first retry and with the delay increasing</span>
    809. 

  809. <a name="l00756"></a>00756 <span class="comment">** by an additional 25 milliseconds with each subsequent retry.  This</span>
    810. 

  810. <a name="l00757"></a>00757 <span class="comment">** opcode allows these two values (10 retries and 25 milliseconds of delay)</span>
    811. 

  811. <a name="l00758"></a>00758 <span class="comment">** to be adjusted.  The values are changed for all database connections</span>
    812. 

  812. <a name="l00759"></a>00759 <span class="comment">** within the same process.  The argument is a pointer to an array of two</span>
    813. 

  813. <a name="l00760"></a>00760 <span class="comment">** integers where the first integer i the new retry count and the second</span>
    814. 

  814. <a name="l00761"></a>00761 <span class="comment">** integer is the delay.  If either integer is negative, then the setting</span>
    815. 

  815. <a name="l00762"></a>00762 <span class="comment">** is not changed but instead the prior value of that setting is written</span>
    816. 

  816. <a name="l00763"></a>00763 <span class="comment">** into the array entry, allowing the current retry settings to be</span>
    817. 

  817. <a name="l00764"></a>00764 <span class="comment">** interrogated.  The zDbName parameter is ignored.</span>
    818. 

  818. <a name="l00765"></a>00765 <span class="comment">**</span>
    819. 

  819. <a name="l00766"></a>00766 <span class="comment">** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the</span>
    820. 

  820. <a name="l00767"></a>00767 <span class="comment">** persistent [WAL | Write AHead Log] setting.  By default, the auxiliary</span>
    821. 

  821. <a name="l00768"></a>00768 <span class="comment">** write ahead log and shared memory files used for transaction control</span>
    822. 

  822. <a name="l00769"></a>00769 <span class="comment">** are automatically deleted when the latest connection to the database</span>
    823. 

  823. <a name="l00770"></a>00770 <span class="comment">** closes.  Setting persistent WAL mode causes those files to persist after</span>
    824. 

  824. <a name="l00771"></a>00771 <span class="comment">** close.  Persisting the files is useful when other processes that do not</span>
    825. 

  825. <a name="l00772"></a>00772 <span class="comment">** have write permission on the directory containing the database file want</span>
    826. 

  826. <a name="l00773"></a>00773 <span class="comment">** to read the database file, as the WAL and shared memory files must exist</span>
    827. 

  827. <a name="l00774"></a>00774 <span class="comment">** in order for the database to be readable.  The fourth parameter to</span>
    828. 

  828. <a name="l00775"></a>00775 <span class="comment">** [sqlite3_file_control()] for this opcode should be a pointer to an integer.</span>
    829. 

  829. <a name="l00776"></a>00776 <span class="comment">** That integer is 0 to disable persistent WAL mode or 1 to enable persistent</span>
    830. 

  830. <a name="l00777"></a>00777 <span class="comment">** WAL mode.  If the integer is -1, then it is overwritten with the current</span>
    831. 

  831. <a name="l00778"></a>00778 <span class="comment">** WAL persistence setting.</span>
    832. 

  832. <a name="l00779"></a>00779 <span class="comment">**</span>
    833. 

  833. <a name="l00780"></a>00780 <span class="comment">** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the</span>
    834. 

  834. <a name="l00781"></a>00781 <span class="comment">** persistent &quot;powersafe-overwrite&quot; or &quot;PSOW&quot; setting.  The PSOW setting</span>
    835. 

  835. <a name="l00782"></a>00782 <span class="comment">** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the</span>
    836. 

  836. <a name="l00783"></a>00783 <span class="comment">** xDeviceCharacteristics methods. The fourth parameter to</span>
    837. 

  837. <a name="l00784"></a>00784 <span class="comment">** [sqlite3_file_control()] for this opcode should be a pointer to an integer.</span>
    838. 

  838. <a name="l00785"></a>00785 <span class="comment">** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage</span>
    839. 

  839. <a name="l00786"></a>00786 <span class="comment">** mode.  If the integer is -1, then it is overwritten with the current</span>
    840. 

  840. <a name="l00787"></a>00787 <span class="comment">** zero-damage mode setting.</span>
    841. 

  841. <a name="l00788"></a>00788 <span class="comment">**</span>
    842. 

  842. <a name="l00789"></a>00789 <span class="comment">** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening</span>
    843. 

  843. <a name="l00790"></a>00790 <span class="comment">** a write transaction to indicate that, unless it is rolled back for some</span>
    844. 

  844. <a name="l00791"></a>00791 <span class="comment">** reason, the entire database file will be overwritten by the current </span>
    845. 

  845. <a name="l00792"></a>00792 <span class="comment">** transaction. This is used by VACUUM operations.</span>
    846. 

  846. <a name="l00793"></a>00793 <span class="comment">**</span>
    847. 

  847. <a name="l00794"></a>00794 <span class="comment">** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of</span>
    848. 

  848. <a name="l00795"></a>00795 <span class="comment">** all [VFSes] in the VFS stack.  The names are of all VFS shims and the</span>
    849. 

  849. <a name="l00796"></a>00796 <span class="comment">** final bottom-level VFS are written into memory obtained from </span>
    850. 

  850. <a name="l00797"></a>00797 <span class="comment">** [sqlite3_malloc()] and the result is stored in the char* variable</span>
    851. 

  851. <a name="l00798"></a>00798 <span class="comment">** that the fourth parameter of [sqlite3_file_control()] points to.</span>
    852. 

  852. <a name="l00799"></a>00799 <span class="comment">** The caller is responsible for freeing the memory when done.  As with</span>
    853. 

  853. <a name="l00800"></a>00800 <span class="comment">** all file-control actions, there is no guarantee that this will actually</span>
    854. 

  854. <a name="l00801"></a>00801 <span class="comment">** do anything.  Callers should initialize the char* variable to a NULL</span>
    855. 

  855. <a name="l00802"></a>00802 <span class="comment">** pointer in case this file-control is not implemented.  This file-control</span>
    856. 

  856. <a name="l00803"></a>00803 <span class="comment">** is intended for diagnostic use only.</span>
    857. 

  857. <a name="l00804"></a>00804 <span class="comment">*/</span>
    858. 

  858. <a name="l00805"></a>00805 <span class="preprocessor">#define SQLITE_FCNTL_LOCKSTATE               1</span>
    859. 

  859. <a name="l00806"></a>00806 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_GET_LOCKPROXYFILE             2</span>
    860. 

  860. <a name="l00807"></a>00807 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_SET_LOCKPROXYFILE             3</span>
    861. 

  861. <a name="l00808"></a>00808 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LAST_ERRNO                    4</span>
    862. 

  862. <a name="l00809"></a>00809 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_FCNTL_SIZE_HINT               5</span>
    863. 

  863. <a name="l00810"></a>00810 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_FCNTL_CHUNK_SIZE              6</span>
    864. 

  864. <a name="l00811"></a>00811 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_FCNTL_FILE_POINTER            7</span>
    865. 

  865. <a name="l00812"></a>00812 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_FCNTL_SYNC_OMITTED            8</span>
    866. 

  866. <a name="l00813"></a>00813 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_FCNTL_WIN32_AV_RETRY          9</span>
    867. 

  867. <a name="l00814"></a>00814 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_FCNTL_PERSIST_WAL            10</span>
    868. 

  868. <a name="l00815"></a>00815 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_FCNTL_OVERWRITE              11</span>
    869. 

  869. <a name="l00816"></a>00816 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_FCNTL_VFSNAME                12</span>
    870. 

  870. <a name="l00817"></a>00817 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_FCNTL_POWERSAFE_OVERWRITE    13</span>
    871. 

  871. <a name="l00818"></a>00818 <span class="preprocessor"></span>
    872. 

  872. <a name="l00819"></a>00819 <span class="comment">/*</span>
    873. 

  873. <a name="l00820"></a>00820 <span class="comment">** CAPI3REF: Mutex Handle</span>
    874. 

  874. <a name="l00821"></a>00821 <span class="comment">**</span>
    875. 

  875. <a name="l00822"></a>00822 <span class="comment">** The mutex module within SQLite defines [sqlite3_mutex] to be an</span>
    876. 

  876. <a name="l00823"></a>00823 <span class="comment">** abstract type for a mutex object.  The SQLite core never looks</span>
    877. 

  877. <a name="l00824"></a>00824 <span class="comment">** at the internal representation of an [sqlite3_mutex].  It only</span>
    878. 

  878. <a name="l00825"></a>00825 <span class="comment">** deals with pointers to the [sqlite3_mutex] object.</span>
    879. 

  879. <a name="l00826"></a>00826 <span class="comment">**</span>
    880. 

  880. <a name="l00827"></a>00827 <span class="comment">** Mutexes are created using [sqlite3_mutex_alloc()].</span>
    881. 

  881. <a name="l00828"></a>00828 <span class="comment">*/</span>
    882. 

  882. <a name="l00829"></a>00829 <span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="structsqlite3__mutex.html">sqlite3_mutex</a> <a class="code" href="structsqlite3__mutex.html">sqlite3_mutex</a>;
    883. 

  883. <a name="l00830"></a>00830 
    884. 

  884. <a name="l00831"></a>00831 <span class="comment">/*</span>
    885. 

  885. <a name="l00832"></a>00832 <span class="comment">** CAPI3REF: OS Interface Object</span>
    886. 

  886. <a name="l00833"></a>00833 <span class="comment">**</span>
    887. 

  887. <a name="l00834"></a>00834 <span class="comment">** An instance of the sqlite3_vfs object defines the interface between</span>
    888. 

  888. <a name="l00835"></a>00835 <span class="comment">** the SQLite core and the underlying operating system.  The &quot;vfs&quot;</span>
    889. 

  889. <a name="l00836"></a>00836 <span class="comment">** in the name of the object stands for &quot;virtual file system&quot;.  See</span>
    890. 

  890. <a name="l00837"></a>00837 <span class="comment">** the [VFS | VFS documentation] for further information.</span>
    891. 

  891. <a name="l00838"></a>00838 <span class="comment">**</span>
    892. 

  892. <a name="l00839"></a>00839 <span class="comment">** The value of the iVersion field is initially 1 but may be larger in</span>
    893. 

  893. <a name="l00840"></a>00840 <span class="comment">** future versions of SQLite.  Additional fields may be appended to this</span>
    894. 

  894. <a name="l00841"></a>00841 <span class="comment">** object when the iVersion value is increased.  Note that the structure</span>
    895. 

  895. <a name="l00842"></a>00842 <span class="comment">** of the sqlite3_vfs object changes in the transaction between</span>
    896. 

  896. <a name="l00843"></a>00843 <span class="comment">** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not</span>
    897. 

  897. <a name="l00844"></a>00844 <span class="comment">** modified.</span>
    898. 

  898. <a name="l00845"></a>00845 <span class="comment">**</span>
    899. 

  899. <a name="l00846"></a>00846 <span class="comment">** The szOsFile field is the size of the subclassed [sqlite3_file]</span>
    900. 

  900. <a name="l00847"></a>00847 <span class="comment">** structure used by this VFS.  mxPathname is the maximum length of</span>
    901. 

  901. <a name="l00848"></a>00848 <span class="comment">** a pathname in this VFS.</span>
    902. 

  902. <a name="l00849"></a>00849 <span class="comment">**</span>
    903. 

  903. <a name="l00850"></a>00850 <span class="comment">** Registered sqlite3_vfs objects are kept on a linked list formed by</span>
    904. 

  904. <a name="l00851"></a>00851 <span class="comment">** the pNext pointer.  The [sqlite3_vfs_register()]</span>
    905. 

  905. <a name="l00852"></a>00852 <span class="comment">** and [sqlite3_vfs_unregister()] interfaces manage this list</span>
    906. 

  906. <a name="l00853"></a>00853 <span class="comment">** in a thread-safe way.  The [sqlite3_vfs_find()] interface</span>
    907. 

  907. <a name="l00854"></a>00854 <span class="comment">** searches the list.  Neither the application code nor the VFS</span>
    908. 

  908. <a name="l00855"></a>00855 <span class="comment">** implementation should use the pNext pointer.</span>
    909. 

  909. <a name="l00856"></a>00856 <span class="comment">**</span>
    910. 

  910. <a name="l00857"></a>00857 <span class="comment">** The pNext field is the only field in the sqlite3_vfs</span>
    911. 

  911. <a name="l00858"></a>00858 <span class="comment">** structure that SQLite will ever modify.  SQLite will only access</span>
    912. 

  912. <a name="l00859"></a>00859 <span class="comment">** or modify this field while holding a particular static mutex.</span>
    913. 

  913. <a name="l00860"></a>00860 <span class="comment">** The application should never modify anything within the sqlite3_vfs</span>
    914. 

  914. <a name="l00861"></a>00861 <span class="comment">** object once the object has been registered.</span>
    915. 

  915. <a name="l00862"></a>00862 <span class="comment">**</span>
    916. 

  916. <a name="l00863"></a>00863 <span class="comment">** The zName field holds the name of the VFS module.  The name must</span>
    917. 

  917. <a name="l00864"></a>00864 <span class="comment">** be unique across all VFS modules.</span>
    918. 

  918. <a name="l00865"></a>00865 <span class="comment">**</span>
    919. 

  919. <a name="l00866"></a>00866 <span class="comment">** [[sqlite3_vfs.xOpen]]</span>
    920. 

  920. <a name="l00867"></a>00867 <span class="comment">** ^SQLite guarantees that the zFilename parameter to xOpen</span>
    921. 

  921. <a name="l00868"></a>00868 <span class="comment">** is either a NULL pointer or string obtained</span>
    922. 

  922. <a name="l00869"></a>00869 <span class="comment">** from xFullPathname() with an optional suffix added.</span>
    923. 

  923. <a name="l00870"></a>00870 <span class="comment">** ^If a suffix is added to the zFilename parameter, it will</span>
    924. 

  924. <a name="l00871"></a>00871 <span class="comment">** consist of a single &quot;-&quot; character followed by no more than</span>
    925. 

  925. <a name="l00872"></a>00872 <span class="comment">** 11 alphanumeric and/or &quot;-&quot; characters.</span>
    926. 

  926. <a name="l00873"></a>00873 <span class="comment">** ^SQLite further guarantees that</span>
    927. 

  927. <a name="l00874"></a>00874 <span class="comment">** the string will be valid and unchanged until xClose() is</span>
    928. 

  928. <a name="l00875"></a>00875 <span class="comment">** called. Because of the previous sentence,</span>
    929. 

  929. <a name="l00876"></a>00876 <span class="comment">** the [sqlite3_file] can safely store a pointer to the</span>
    930. 

  930. <a name="l00877"></a>00877 <span class="comment">** filename if it needs to remember the filename for some reason.</span>
    931. 

  931. <a name="l00878"></a>00878 <span class="comment">** If the zFilename parameter to xOpen is a NULL pointer then xOpen</span>
    932. 

  932. <a name="l00879"></a>00879 <span class="comment">** must invent its own temporary name for the file.  ^Whenever the </span>
    933. 

  933. <a name="l00880"></a>00880 <span class="comment">** xFilename parameter is NULL it will also be the case that the</span>
    934. 

  934. <a name="l00881"></a>00881 <span class="comment">** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].</span>
    935. 

  935. <a name="l00882"></a>00882 <span class="comment">**</span>
    936. 

  936. <a name="l00883"></a>00883 <span class="comment">** The flags argument to xOpen() includes all bits set in</span>
    937. 

  937. <a name="l00884"></a>00884 <span class="comment">** the flags argument to [sqlite3_open_v2()].  Or if [sqlite3_open()]</span>
    938. 

  938. <a name="l00885"></a>00885 <span class="comment">** or [sqlite3_open16()] is used, then flags includes at least</span>
    939. 

  939. <a name="l00886"></a>00886 <span class="comment">** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]. </span>
    940. 

  940. <a name="l00887"></a>00887 <span class="comment">** If xOpen() opens a file read-only then it sets *pOutFlags to</span>
    941. 

  941. <a name="l00888"></a>00888 <span class="comment">** include [SQLITE_OPEN_READONLY].  Other bits in *pOutFlags may be set.</span>
    942. 

  942. <a name="l00889"></a>00889 <span class="comment">**</span>
    943. 

  943. <a name="l00890"></a>00890 <span class="comment">** ^(SQLite will also add one of the following flags to the xOpen()</span>
    944. 

  944. <a name="l00891"></a>00891 <span class="comment">** call, depending on the object being opened:</span>
    945. 

  945. <a name="l00892"></a>00892 <span class="comment">**</span>
    946. 

  946. <a name="l00893"></a>00893 <span class="comment">** &lt;ul&gt;</span>
    947. 

  947. <a name="l00894"></a>00894 <span class="comment">** &lt;li&gt;  [SQLITE_OPEN_MAIN_DB]</span>
    948. 

  948. <a name="l00895"></a>00895 <span class="comment">** &lt;li&gt;  [SQLITE_OPEN_MAIN_JOURNAL]</span>
    949. 

  949. <a name="l00896"></a>00896 <span class="comment">** &lt;li&gt;  [SQLITE_OPEN_TEMP_DB]</span>
    950. 

  950. <a name="l00897"></a>00897 <span class="comment">** &lt;li&gt;  [SQLITE_OPEN_TEMP_JOURNAL]</span>
    951. 

  951. <a name="l00898"></a>00898 <span class="comment">** &lt;li&gt;  [SQLITE_OPEN_TRANSIENT_DB]</span>
    952. 

  952. <a name="l00899"></a>00899 <span class="comment">** &lt;li&gt;  [SQLITE_OPEN_SUBJOURNAL]</span>
    953. 

  953. <a name="l00900"></a>00900 <span class="comment">** &lt;li&gt;  [SQLITE_OPEN_MASTER_JOURNAL]</span>
    954. 

  954. <a name="l00901"></a>00901 <span class="comment">** &lt;li&gt;  [SQLITE_OPEN_WAL]</span>
    955. 

  955. <a name="l00902"></a>00902 <span class="comment">** &lt;/ul&gt;)^</span>
    956. 

  956. <a name="l00903"></a>00903 <span class="comment">**</span>
    957. 

  957. <a name="l00904"></a>00904 <span class="comment">** The file I/O implementation can use the object type flags to</span>
    958. 

  958. <a name="l00905"></a>00905 <span class="comment">** change the way it deals with files.  For example, an application</span>
    959. 

  959. <a name="l00906"></a>00906 <span class="comment">** that does not care about crash recovery or rollback might make</span>
    960. 

  960. <a name="l00907"></a>00907 <span class="comment">** the open of a journal file a no-op.  Writes to this journal would</span>
    961. 

  961. <a name="l00908"></a>00908 <span class="comment">** also be no-ops, and any attempt to read the journal would return</span>
    962. 

  962. <a name="l00909"></a>00909 <span class="comment">** SQLITE_IOERR.  Or the implementation might recognize that a database</span>
    963. 

  963. <a name="l00910"></a>00910 <span class="comment">** file will be doing page-aligned sector reads and writes in a random</span>
    964. 

  964. <a name="l00911"></a>00911 <span class="comment">** order and set up its I/O subsystem accordingly.</span>
    965. 

  965. <a name="l00912"></a>00912 <span class="comment">**</span>
    966. 

  966. <a name="l00913"></a>00913 <span class="comment">** SQLite might also add one of the following flags to the xOpen method:</span>
    967. 

  967. <a name="l00914"></a>00914 <span class="comment">**</span>
    968. 

  968. <a name="l00915"></a>00915 <span class="comment">** &lt;ul&gt;</span>
    969. 

  969. <a name="l00916"></a>00916 <span class="comment">** &lt;li&gt; [SQLITE_OPEN_DELETEONCLOSE]</span>
    970. 

  970. <a name="l00917"></a>00917 <span class="comment">** &lt;li&gt; [SQLITE_OPEN_EXCLUSIVE]</span>
    971. 

  971. <a name="l00918"></a>00918 <span class="comment">** &lt;/ul&gt;</span>
    972. 

  972. <a name="l00919"></a>00919 <span class="comment">**</span>
    973. 

  973. <a name="l00920"></a>00920 <span class="comment">** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be</span>
    974. 

  974. <a name="l00921"></a>00921 <span class="comment">** deleted when it is closed.  ^The [SQLITE_OPEN_DELETEONCLOSE]</span>
    975. 

  975. <a name="l00922"></a>00922 <span class="comment">** will be set for TEMP databases and their journals, transient</span>
    976. 

  976. <a name="l00923"></a>00923 <span class="comment">** databases, and subjournals.</span>
    977. 

  977. <a name="l00924"></a>00924 <span class="comment">**</span>
    978. 

  978. <a name="l00925"></a>00925 <span class="comment">** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction</span>
    979. 

  979. <a name="l00926"></a>00926 <span class="comment">** with the [SQLITE_OPEN_CREATE] flag, which are both directly</span>
    980. 

  980. <a name="l00927"></a>00927 <span class="comment">** analogous to the O_EXCL and O_CREAT flags of the POSIX open()</span>
    981. 

  981. <a name="l00928"></a>00928 <span class="comment">** API.  The SQLITE_OPEN_EXCLUSIVE flag, when paired with the </span>
    982. 

  982. <a name="l00929"></a>00929 <span class="comment">** SQLITE_OPEN_CREATE, is used to indicate that file should always</span>
    983. 

  983. <a name="l00930"></a>00930 <span class="comment">** be created, and that it is an error if it already exists.</span>
    984. 

  984. <a name="l00931"></a>00931 <span class="comment">** It is &lt;i&gt;not&lt;/i&gt; used to indicate the file should be opened </span>
    985. 

  985. <a name="l00932"></a>00932 <span class="comment">** for exclusive access.</span>
    986. 

  986. <a name="l00933"></a>00933 <span class="comment">**</span>
    987. 

  987. <a name="l00934"></a>00934 <span class="comment">** ^At least szOsFile bytes of memory are allocated by SQLite</span>
    988. 

  988. <a name="l00935"></a>00935 <span class="comment">** to hold the  [sqlite3_file] structure passed as the third</span>
    989. 

  989. <a name="l00936"></a>00936 <span class="comment">** argument to xOpen.  The xOpen method does not have to</span>
    990. 

  990. <a name="l00937"></a>00937 <span class="comment">** allocate the structure; it should just fill it in.  Note that</span>
    991. 

  991. <a name="l00938"></a>00938 <span class="comment">** the xOpen method must set the sqlite3_file.pMethods to either</span>
    992. 

  992. <a name="l00939"></a>00939 <span class="comment">** a valid [sqlite3_io_methods] object or to NULL.  xOpen must do</span>
    993. 

  993. <a name="l00940"></a>00940 <span class="comment">** this even if the open fails.  SQLite expects that the sqlite3_file.pMethods</span>
    994. 

  994. <a name="l00941"></a>00941 <span class="comment">** element will be valid after xOpen returns regardless of the success</span>
    995. 

  995. <a name="l00942"></a>00942 <span class="comment">** or failure of the xOpen call.</span>
    996. 

  996. <a name="l00943"></a>00943 <span class="comment">**</span>
    997. 

  997. <a name="l00944"></a>00944 <span class="comment">** [[sqlite3_vfs.xAccess]]</span>
    998. 

  998. <a name="l00945"></a>00945 <span class="comment">** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]</span>
    999. 

  999. <a name="l00946"></a>00946 <span class="comment">** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to</span>
    1000. 

  1000. <a name="l00947"></a>00947 <span class="comment">** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]</span>
    1001. 

  1001. <a name="l00948"></a>00948 <span class="comment">** to test whether a file is at least readable.   The file can be a</span>
    1002. 

  1002. <a name="l00949"></a>00949 <span class="comment">** directory.</span>
    1003. 

  1003. <a name="l00950"></a>00950 <span class="comment">**</span>
    1004. 

  1004. <a name="l00951"></a>00951 <span class="comment">** ^SQLite will always allocate at least mxPathname+1 bytes for the</span>
    1005. 

  1005. <a name="l00952"></a>00952 <span class="comment">** output buffer xFullPathname.  The exact size of the output buffer</span>
    1006. 

  1006. <a name="l00953"></a>00953 <span class="comment">** is also passed as a parameter to both  methods. If the output buffer</span>
    1007. 

  1007. <a name="l00954"></a>00954 <span class="comment">** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is</span>
    1008. 

  1008. <a name="l00955"></a>00955 <span class="comment">** handled as a fatal error by SQLite, vfs implementations should endeavor</span>
    1009. 

  1009. <a name="l00956"></a>00956 <span class="comment">** to prevent this by setting mxPathname to a sufficiently large value.</span>
    1010. 

  1010. <a name="l00957"></a>00957 <span class="comment">**</span>
    1011. 

  1011. <a name="l00958"></a>00958 <span class="comment">** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()</span>
    1012. 

  1012. <a name="l00959"></a>00959 <span class="comment">** interfaces are not strictly a part of the filesystem, but they are</span>
    1013. 

  1013. <a name="l00960"></a>00960 <span class="comment">** included in the VFS structure for completeness.</span>
    1014. 

  1014. <a name="l00961"></a>00961 <span class="comment">** The xRandomness() function attempts to return nBytes bytes</span>
    1015. 

  1015. <a name="l00962"></a>00962 <span class="comment">** of good-quality randomness into zOut.  The return value is</span>
    1016. 

  1016. <a name="l00963"></a>00963 <span class="comment">** the actual number of bytes of randomness obtained.</span>
    1017. 

  1017. <a name="l00964"></a>00964 <span class="comment">** The xSleep() method causes the calling thread to sleep for at</span>
    1018. 

  1018. <a name="l00965"></a>00965 <span class="comment">** least the number of microseconds given.  ^The xCurrentTime()</span>
    1019. 

  1019. <a name="l00966"></a>00966 <span class="comment">** method returns a Julian Day Number for the current date and time as</span>
    1020. 

  1020. <a name="l00967"></a>00967 <span class="comment">** a floating point value.</span>
    1021. 

  1021. <a name="l00968"></a>00968 <span class="comment">** ^The xCurrentTimeInt64() method returns, as an integer, the Julian</span>
    1022. 

  1022. <a name="l00969"></a>00969 <span class="comment">** Day Number multiplied by 86400000 (the number of milliseconds in </span>
    1023. 

  1023. <a name="l00970"></a>00970 <span class="comment">** a 24-hour day).  </span>
    1024. 

  1024. <a name="l00971"></a>00971 <span class="comment">** ^SQLite will use the xCurrentTimeInt64() method to get the current</span>
    1025. 

  1025. <a name="l00972"></a>00972 <span class="comment">** date and time if that method is available (if iVersion is 2 or </span>
    1026. 

  1026. <a name="l00973"></a>00973 <span class="comment">** greater and the function pointer is not NULL) and will fall back</span>
    1027. 

  1027. <a name="l00974"></a>00974 <span class="comment">** to xCurrentTime() if xCurrentTimeInt64() is unavailable.</span>
    1028. 

  1028. <a name="l00975"></a>00975 <span class="comment">**</span>
    1029. 

  1029. <a name="l00976"></a>00976 <span class="comment">** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces</span>
    1030. 

  1030. <a name="l00977"></a>00977 <span class="comment">** are not used by the SQLite core.  These optional interfaces are provided</span>
    1031. 

  1031. <a name="l00978"></a>00978 <span class="comment">** by some VFSes to facilitate testing of the VFS code. By overriding </span>
    1032. 

  1032. <a name="l00979"></a>00979 <span class="comment">** system calls with functions under its control, a test program can</span>
    1033. 

  1033. <a name="l00980"></a>00980 <span class="comment">** simulate faults and error conditions that would otherwise be difficult</span>
    1034. 

  1034. <a name="l00981"></a>00981 <span class="comment">** or impossible to induce.  The set of system calls that can be overridden</span>
    1035. 

  1035. <a name="l00982"></a>00982 <span class="comment">** varies from one VFS to another, and from one version of the same VFS to the</span>
    1036. 

  1036. <a name="l00983"></a>00983 <span class="comment">** next.  Applications that use these interfaces must be prepared for any</span>
    1037. 

  1037. <a name="l00984"></a>00984 <span class="comment">** or all of these interfaces to be NULL or for their behavior to change</span>
    1038. 

  1038. <a name="l00985"></a>00985 <span class="comment">** from one release to the next.  Applications must not attempt to access</span>
    1039. 

  1039. <a name="l00986"></a>00986 <span class="comment">** any of these methods if the iVersion of the VFS is less than 3.</span>
    1040. 

  1040. <a name="l00987"></a>00987 <span class="comment">*/</span>
    1041. 

  1041. <a name="l00988"></a>00988 <span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a> <a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>;
    1042. 

  1042. <a name="l00989"></a>00989 <span class="keyword">typedef</span> void (*sqlite3_syscall_ptr)(void);
    1043. 

  1043. <a name="l00990"></a>00990 <span class="keyword">struct </span><a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a> {
    1044. 

  1044. <a name="l00991"></a>00991   <span class="keywordtype">int</span> iVersion;            <span class="comment">/* Structure version number (currently 3) */</span>
    1045. 

  1045. <a name="l00992"></a>00992   <span class="keywordtype">int</span> szOsFile;            <span class="comment">/* Size of subclassed sqlite3_file */</span>
    1046. 

  1046. <a name="l00993"></a>00993   <span class="keywordtype">int</span> mxPathname;          <span class="comment">/* Maximum file pathname length */</span>
    1047. 

  1047. <a name="l00994"></a>00994   <a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a> *pNext;      <span class="comment">/* Next registered VFS */</span>
    1048. 

  1048. <a name="l00995"></a>00995   <span class="keyword">const</span> <span class="keywordtype">char</span> *zName;       <span class="comment">/* Name of this virtual file system */</span>
    1049. 

  1049. <a name="l00996"></a>00996   <span class="keywordtype">void</span> *pAppData;          <span class="comment">/* Pointer to application-specific data */</span>
    1050. 

  1050. <a name="l00997"></a>00997   int (*xOpen)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, <span class="keyword">const</span> <span class="keywordtype">char</span> *zName, <a class="code" href="structsqlite3__file.html">sqlite3_file</a>*,
    1051. 

  1051. <a name="l00998"></a>00998                <span class="keywordtype">int</span> flags, <span class="keywordtype">int</span> *pOutFlags);
    1052. 

  1052. <a name="l00999"></a>00999   int (*xDelete)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, <span class="keyword">const</span> <span class="keywordtype">char</span> *zName, <span class="keywordtype">int</span> syncDir);
    1053. 

  1053. <a name="l01000"></a>01000   int (*xAccess)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, <span class="keyword">const</span> <span class="keywordtype">char</span> *zName, <span class="keywordtype">int</span> flags, <span class="keywordtype">int</span> *pResOut);
    1054. 

  1054. <a name="l01001"></a>01001   int (*xFullPathname)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, <span class="keyword">const</span> <span class="keywordtype">char</span> *zName, <span class="keywordtype">int</span> nOut, <span class="keywordtype">char</span> *zOut);
    1055. 

  1055. <a name="l01002"></a>01002   <span class="keywordtype">void</span> *(*xDlOpen)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, <span class="keyword">const</span> <span class="keywordtype">char</span> *zFilename);
    1056. 

  1056. <a name="l01003"></a>01003   void (*xDlError)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, <span class="keywordtype">int</span> nByte, <span class="keywordtype">char</span> *zErrMsg);
    1057. 

  1057. <a name="l01004"></a>01004   void (*(*xDlSym)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*,<span class="keywordtype">void</span>*, <span class="keyword">const</span> <span class="keywordtype">char</span> *zSymbol))(void);
    1058. 

  1058. <a name="l01005"></a>01005   void (*xDlClose)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, <span class="keywordtype">void</span>*);
    1059. 

  1059. <a name="l01006"></a>01006   int (*xRandomness)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, <span class="keywordtype">int</span> nByte, <span class="keywordtype">char</span> *zOut);
    1060. 

  1060. <a name="l01007"></a>01007   int (*xSleep)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, <span class="keywordtype">int</span> microseconds);
    1061. 

  1061. <a name="l01008"></a>01008   int (*xCurrentTime)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, <span class="keywordtype">double</span>*);
    1062. 

  1062. <a name="l01009"></a>01009   int (*xGetLastError)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, int, <span class="keywordtype">char</span> *);
    1063. 

  1063. <a name="l01010"></a>01010   <span class="comment">/*</span>
    1064. 

  1064. <a name="l01011"></a>01011 <span class="comment">  ** The methods above are in version 1 of the sqlite_vfs object</span>
    1065. 

  1065. <a name="l01012"></a>01012 <span class="comment">  ** definition.  Those that follow are added in version 2 or later</span>
    1066. 

  1066. <a name="l01013"></a>01013 <span class="comment">  */</span>
    1067. 

  1067. <a name="l01014"></a>01014   int (*xCurrentTimeInt64)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, sqlite3_int64*);
    1068. 

  1068. <a name="l01015"></a>01015   <span class="comment">/*</span>
    1069. 

  1069. <a name="l01016"></a>01016 <span class="comment">  ** The methods above are in versions 1 and 2 of the sqlite_vfs object.</span>
    1070. 

  1070. <a name="l01017"></a>01017 <span class="comment">  ** Those below are for version 3 and greater.</span>
    1071. 

  1071. <a name="l01018"></a>01018 <span class="comment">  */</span>
    1072. 

  1072. <a name="l01019"></a>01019   int (*xSetSystemCall)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, <span class="keyword">const</span> <span class="keywordtype">char</span> *zName, sqlite3_syscall_ptr);
    1073. 

  1073. <a name="l01020"></a>01020   sqlite3_syscall_ptr (*xGetSystemCall)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, <span class="keyword">const</span> <span class="keywordtype">char</span> *zName);
    1074. 

  1074. <a name="l01021"></a>01021   <span class="keyword">const</span> <span class="keywordtype">char</span> *(*xNextSystemCall)(<a class="code" href="structsqlite3__vfs.html">sqlite3_vfs</a>*, <span class="keyword">const</span> <span class="keywordtype">char</span> *zName);
    1075. 

  1075. <a name="l01022"></a>01022   <span class="comment">/*</span>
    1076. 

  1076. <a name="l01023"></a>01023 <span class="comment">  ** The methods above are in versions 1 through 3 of the sqlite_vfs object.</span>
    1077. 

  1077. <a name="l01024"></a>01024 <span class="comment">  ** New fields may be appended in figure versions.  The iVersion</span>
    1078. 

  1078. <a name="l01025"></a>01025 <span class="comment">  ** value will increment whenever this happens. </span>
    1079. 

  1079. <a name="l01026"></a>01026 <span class="comment">  */</span>
    1080. 

  1080. <a name="l01027"></a>01027 };
    1081. 

  1081. <a name="l01028"></a>01028 
    1082. 

  1082. <a name="l01029"></a>01029 <span class="comment">/*</span>
    1083. 

  1083. <a name="l01030"></a>01030 <span class="comment">** CAPI3REF: Flags for the xAccess VFS method</span>
    1084. 

  1084. <a name="l01031"></a>01031 <span class="comment">**</span>
    1085. 

  1085. <a name="l01032"></a>01032 <span class="comment">** These integer constants can be used as the third parameter to</span>
    1086. 

  1086. <a name="l01033"></a>01033 <span class="comment">** the xAccess method of an [sqlite3_vfs] object.  They determine</span>
    1087. 

  1087. <a name="l01034"></a>01034 <span class="comment">** what kind of permissions the xAccess method is looking for.</span>
    1088. 

  1088. <a name="l01035"></a>01035 <span class="comment">** With SQLITE_ACCESS_EXISTS, the xAccess method</span>
    1089. 

  1089. <a name="l01036"></a>01036 <span class="comment">** simply checks whether the file exists.</span>
    1090. 

  1090. <a name="l01037"></a>01037 <span class="comment">** With SQLITE_ACCESS_READWRITE, the xAccess method</span>
    1091. 

  1091. <a name="l01038"></a>01038 <span class="comment">** checks whether the named directory is both readable and writable</span>
    1092. 

  1092. <a name="l01039"></a>01039 <span class="comment">** (in other words, if files can be added, removed, and renamed within</span>
    1093. 

  1093. <a name="l01040"></a>01040 <span class="comment">** the directory).</span>
    1094. 

  1094. <a name="l01041"></a>01041 <span class="comment">** The SQLITE_ACCESS_READWRITE constant is currently used only by the</span>
    1095. 

  1095. <a name="l01042"></a>01042 <span class="comment">** [temp_store_directory pragma], though this could change in a future</span>
    1096. 

  1096. <a name="l01043"></a>01043 <span class="comment">** release of SQLite.</span>
    1097. 

  1097. <a name="l01044"></a>01044 <span class="comment">** With SQLITE_ACCESS_READ, the xAccess method</span>
    1098. 

  1098. <a name="l01045"></a>01045 <span class="comment">** checks whether the file is readable.  The SQLITE_ACCESS_READ constant is</span>
    1099. 

  1099. <a name="l01046"></a>01046 <span class="comment">** currently unused, though it might be used in a future release of</span>
    1100. 

  1100. <a name="l01047"></a>01047 <span class="comment">** SQLite.</span>
    1101. 

  1101. <a name="l01048"></a>01048 <span class="comment">*/</span>
    1102. 

  1102. <a name="l01049"></a>01049 <span class="preprocessor">#define SQLITE_ACCESS_EXISTS    0</span>
    1103. 

  1103. <a name="l01050"></a>01050 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_ACCESS_READWRITE 1   </span><span class="comment">/* Used by PRAGMA temp_store_directory */</span>
    1104. 

  1104. <a name="l01051"></a>01051 <span class="preprocessor">#define SQLITE_ACCESS_READ      2   </span><span class="comment">/* Unused */</span>
    1105. 

  1105. <a name="l01052"></a>01052 
    1106. 

  1106. <a name="l01053"></a>01053 <span class="comment">/*</span>
    1107. 

  1107. <a name="l01054"></a>01054 <span class="comment">** CAPI3REF: Flags for the xShmLock VFS method</span>
    1108. 

  1108. <a name="l01055"></a>01055 <span class="comment">**</span>
    1109. 

  1109. <a name="l01056"></a>01056 <span class="comment">** These integer constants define the various locking operations</span>
    1110. 

  1110. <a name="l01057"></a>01057 <span class="comment">** allowed by the xShmLock method of [sqlite3_io_methods].  The</span>
    1111. 

  1111. <a name="l01058"></a>01058 <span class="comment">** following are the only legal combinations of flags to the</span>
    1112. 

  1112. <a name="l01059"></a>01059 <span class="comment">** xShmLock method:</span>
    1113. 

  1113. <a name="l01060"></a>01060 <span class="comment">**</span>
    1114. 

  1114. <a name="l01061"></a>01061 <span class="comment">** &lt;ul&gt;</span>
    1115. 

  1115. <a name="l01062"></a>01062 <span class="comment">** &lt;li&gt;  SQLITE_SHM_LOCK | SQLITE_SHM_SHARED</span>
    1116. 

  1116. <a name="l01063"></a>01063 <span class="comment">** &lt;li&gt;  SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE</span>
    1117. 

  1117. <a name="l01064"></a>01064 <span class="comment">** &lt;li&gt;  SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED</span>
    1118. 

  1118. <a name="l01065"></a>01065 <span class="comment">** &lt;li&gt;  SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE</span>
    1119. 

  1119. <a name="l01066"></a>01066 <span class="comment">** &lt;/ul&gt;</span>
    1120. 

  1120. <a name="l01067"></a>01067 <span class="comment">**</span>
    1121. 

  1121. <a name="l01068"></a>01068 <span class="comment">** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as</span>
    1122. 

  1122. <a name="l01069"></a>01069 <span class="comment">** was given no the corresponding lock.  </span>
    1123. 

  1123. <a name="l01070"></a>01070 <span class="comment">**</span>
    1124. 

  1124. <a name="l01071"></a>01071 <span class="comment">** The xShmLock method can transition between unlocked and SHARED or</span>
    1125. 

  1125. <a name="l01072"></a>01072 <span class="comment">** between unlocked and EXCLUSIVE.  It cannot transition between SHARED</span>
    1126. 

  1126. <a name="l01073"></a>01073 <span class="comment">** and EXCLUSIVE.</span>
    1127. 

  1127. <a name="l01074"></a>01074 <span class="comment">*/</span>
    1128. 

  1128. <a name="l01075"></a>01075 <span class="preprocessor">#define SQLITE_SHM_UNLOCK       1</span>
    1129. 

  1129. <a name="l01076"></a>01076 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_SHM_LOCK         2</span>
    1130. 

  1130. <a name="l01077"></a>01077 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_SHM_SHARED       4</span>
    1131. 

  1131. <a name="l01078"></a>01078 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_SHM_EXCLUSIVE    8</span>
    1132. 

  1132. <a name="l01079"></a>01079 <span class="preprocessor"></span>
    1133. 

  1133. <a name="l01080"></a>01080 <span class="comment">/*</span>
    1134. 

  1134. <a name="l01081"></a>01081 <span class="comment">** CAPI3REF: Maximum xShmLock index</span>
    1135. 

  1135. <a name="l01082"></a>01082 <span class="comment">**</span>
    1136. 

  1136. <a name="l01083"></a>01083 <span class="comment">** The xShmLock method on [sqlite3_io_methods] may use values</span>
    1137. 

  1137. <a name="l01084"></a>01084 <span class="comment">** between 0 and this upper bound as its &quot;offset&quot; argument.</span>
    1138. 

  1138. <a name="l01085"></a>01085 <span class="comment">** The SQLite core will never attempt to acquire or release a</span>
    1139. 

  1139. <a name="l01086"></a>01086 <span class="comment">** lock outside of this range</span>
    1140. 

  1140. <a name="l01087"></a>01087 <span class="comment">*/</span>
    1141. 

  1141. <a name="l01088"></a>01088 <span class="preprocessor">#define SQLITE_SHM_NLOCK        8</span>
    1142. 

  1142. <a name="l01089"></a>01089 <span class="preprocessor"></span>
    1143. 

  1143. <a name="l01090"></a>01090 
    1144. 

  1144. <a name="l01091"></a>01091 <span class="comment">/*</span>
    1145. 

  1145. <a name="l01092"></a>01092 <span class="comment">** CAPI3REF: Initialize The SQLite Library</span>
    1146. 

  1146. <a name="l01093"></a>01093 <span class="comment">**</span>
    1147. 

  1147. <a name="l01094"></a>01094 <span class="comment">** ^The sqlite3_initialize() routine initializes the</span>
    1148. 

  1148. <a name="l01095"></a>01095 <span class="comment">** SQLite library.  ^The sqlite3_shutdown() routine</span>
    1149. 

  1149. <a name="l01096"></a>01096 <span class="comment">** deallocates any resources that were allocated by sqlite3_initialize().</span>
    1150. 

  1150. <a name="l01097"></a>01097 <span class="comment">** These routines are designed to aid in process initialization and</span>
    1151. 

  1151. <a name="l01098"></a>01098 <span class="comment">** shutdown on embedded systems.  Workstation applications using</span>
    1152. 

  1152. <a name="l01099"></a>01099 <span class="comment">** SQLite normally do not need to invoke either of these routines.</span>
    1153. 

  1153. <a name="l01100"></a>01100 <span class="comment">**</span>
    1154. 

  1154. <a name="l01101"></a>01101 <span class="comment">** A call to sqlite3_initialize() is an &quot;effective&quot; call if it is</span>
    1155. 

  1155. <a name="l01102"></a>01102 <span class="comment">** the first time sqlite3_initialize() is invoked during the lifetime of</span>
    1156. 

  1156. <a name="l01103"></a>01103 <span class="comment">** the process, or if it is the first time sqlite3_initialize() is invoked</span>
    1157. 

  1157. <a name="l01104"></a>01104 <span class="comment">** following a call to sqlite3_shutdown().  ^(Only an effective call</span>
    1158. 

  1158. <a name="l01105"></a>01105 <span class="comment">** of sqlite3_initialize() does any initialization.  All other calls</span>
    1159. 

  1159. <a name="l01106"></a>01106 <span class="comment">** are harmless no-ops.)^</span>
    1160. 

  1160. <a name="l01107"></a>01107 <span class="comment">**</span>
    1161. 

  1161. <a name="l01108"></a>01108 <span class="comment">** A call to sqlite3_shutdown() is an &quot;effective&quot; call if it is the first</span>
    1162. 

  1162. <a name="l01109"></a>01109 <span class="comment">** call to sqlite3_shutdown() since the last sqlite3_initialize().  ^(Only</span>
    1163. 

  1163. <a name="l01110"></a>01110 <span class="comment">** an effective call to sqlite3_shutdown() does any deinitialization.</span>
    1164. 

  1164. <a name="l01111"></a>01111 <span class="comment">** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^</span>
    1165. 

  1165. <a name="l01112"></a>01112 <span class="comment">**</span>
    1166. 

  1166. <a name="l01113"></a>01113 <span class="comment">** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()</span>
    1167. 

  1167. <a name="l01114"></a>01114 <span class="comment">** is not.  The sqlite3_shutdown() interface must only be called from a</span>
    1168. 

  1168. <a name="l01115"></a>01115 <span class="comment">** single thread.  All open [database connections] must be closed and all</span>
    1169. 

  1169. <a name="l01116"></a>01116 <span class="comment">** other SQLite resources must be deallocated prior to invoking</span>
    1170. 

  1170. <a name="l01117"></a>01117 <span class="comment">** sqlite3_shutdown().</span>
    1171. 

  1171. <a name="l01118"></a>01118 <span class="comment">**</span>
    1172. 

  1172. <a name="l01119"></a>01119 <span class="comment">** Among other things, ^sqlite3_initialize() will invoke</span>
    1173. 

  1173. <a name="l01120"></a>01120 <span class="comment">** sqlite3_os_init().  Similarly, ^sqlite3_shutdown()</span>
    1174. 

  1174. <a name="l01121"></a>01121 <span class="comment">** will invoke sqlite3_os_end().</span>
    1175. 

  1175. <a name="l01122"></a>01122 <span class="comment">**</span>
    1176. 

  1176. <a name="l01123"></a>01123 <span class="comment">** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.</span>
    1177. 

  1177. <a name="l01124"></a>01124 <span class="comment">** ^If for some reason, sqlite3_initialize() is unable to initialize</span>
    1178. 

  1178. <a name="l01125"></a>01125 <span class="comment">** the library (perhaps it is unable to allocate a needed resource such</span>
    1179. 

  1179. <a name="l01126"></a>01126 <span class="comment">** as a mutex) it returns an [error code] other than [SQLITE_OK].</span>
    1180. 

  1180. <a name="l01127"></a>01127 <span class="comment">**</span>
    1181. 

  1181. <a name="l01128"></a>01128 <span class="comment">** ^The sqlite3_initialize() routine is called internally by many other</span>
    1182. 

  1182. <a name="l01129"></a>01129 <span class="comment">** SQLite interfaces so that an application usually does not need to</span>
    1183. 

  1183. <a name="l01130"></a>01130 <span class="comment">** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]</span>
    1184. 

  1184. <a name="l01131"></a>01131 <span class="comment">** calls sqlite3_initialize() so the SQLite library will be automatically</span>
    1185. 

  1185. <a name="l01132"></a>01132 <span class="comment">** initialized when [sqlite3_open()] is called if it has not be initialized</span>
    1186. 

  1186. <a name="l01133"></a>01133 <span class="comment">** already.  ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]</span>
    1187. 

  1187. <a name="l01134"></a>01134 <span class="comment">** compile-time option, then the automatic calls to sqlite3_initialize()</span>
    1188. 

  1188. <a name="l01135"></a>01135 <span class="comment">** are omitted and the application must call sqlite3_initialize() directly</span>
    1189. 

  1189. <a name="l01136"></a>01136 <span class="comment">** prior to using any other SQLite interface.  For maximum portability,</span>
    1190. 

  1190. <a name="l01137"></a>01137 <span class="comment">** it is recommended that applications always invoke sqlite3_initialize()</span>
    1191. 

  1191. <a name="l01138"></a>01138 <span class="comment">** directly prior to using any other SQLite interface.  Future releases</span>
    1192. 

  1192. <a name="l01139"></a>01139 <span class="comment">** of SQLite may require this.  In other words, the behavior exhibited</span>
    1193. 

  1193. <a name="l01140"></a>01140 <span class="comment">** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the</span>
    1194. 

  1194. <a name="l01141"></a>01141 <span class="comment">** default behavior in some future release of SQLite.</span>
    1195. 

  1195. <a name="l01142"></a>01142 <span class="comment">**</span>
    1196. 

  1196. <a name="l01143"></a>01143 <span class="comment">** The sqlite3_os_init() routine does operating-system specific</span>
    1197. 

  1197. <a name="l01144"></a>01144 <span class="comment">** initialization of the SQLite library.  The sqlite3_os_end()</span>
    1198. 

  1198. <a name="l01145"></a>01145 <span class="comment">** routine undoes the effect of sqlite3_os_init().  Typical tasks</span>
    1199. 

  1199. <a name="l01146"></a>01146 <span class="comment">** performed by these routines include allocation or deallocation</span>
    1200. 

  1200. <a name="l01147"></a>01147 <span class="comment">** of static resources, initialization of global variables,</span>
    1201. 

  1201. <a name="l01148"></a>01148 <span class="comment">** setting up a default [sqlite3_vfs] module, or setting up</span>
    1202. 

  1202. <a name="l01149"></a>01149 <span class="comment">** a default configuration using [sqlite3_config()].</span>
    1203. 

  1203. <a name="l01150"></a>01150 <span class="comment">**</span>
    1204. 

  1204. <a name="l01151"></a>01151 <span class="comment">** The application should never invoke either sqlite3_os_init()</span>
    1205. 

  1205. <a name="l01152"></a>01152 <span class="comment">** or sqlite3_os_end() directly.  The application should only invoke</span>
    1206. 

  1206. <a name="l01153"></a>01153 <span class="comment">** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()</span>
    1207. 

  1207. <a name="l01154"></a>01154 <span class="comment">** interface is called automatically by sqlite3_initialize() and</span>
    1208. 

  1208. <a name="l01155"></a>01155 <span class="comment">** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate</span>
    1209. 

  1209. <a name="l01156"></a>01156 <span class="comment">** implementations for sqlite3_os_init() and sqlite3_os_end()</span>
    1210. 

  1210. <a name="l01157"></a>01157 <span class="comment">** are built into SQLite when it is compiled for Unix, Windows, or OS/2.</span>
    1211. 

  1211. <a name="l01158"></a>01158 <span class="comment">** When [custom builds | built for other platforms]</span>
    1212. 

  1212. <a name="l01159"></a>01159 <span class="comment">** (using the [SQLITE_OS_OTHER=1] compile-time</span>
    1213. 

  1213. <a name="l01160"></a>01160 <span class="comment">** option) the application must supply a suitable implementation for</span>
    1214. 

  1214. <a name="l01161"></a>01161 <span class="comment">** sqlite3_os_init() and sqlite3_os_end().  An application-supplied</span>
    1215. 

  1215. <a name="l01162"></a>01162 <span class="comment">** implementation of sqlite3_os_init() or sqlite3_os_end()</span>
    1216. 

  1216. <a name="l01163"></a>01163 <span class="comment">** must return [SQLITE_OK] on success and some other [error code] upon</span>
    1217. 

  1217. <a name="l01164"></a>01164 <span class="comment">** failure.</span>
    1218. 

  1218. <a name="l01165"></a>01165 <span class="comment">*/</span>
    1219. 

  1219. <a name="l01166"></a>01166 SQLITE_API <span class="keywordtype">int</span> sqlite3_initialize(<span class="keywordtype">void</span>);
    1220. 

  1220. <a name="l01167"></a>01167 SQLITE_API <span class="keywordtype">int</span> sqlite3_shutdown(<span class="keywordtype">void</span>);
    1221. 

  1221. <a name="l01168"></a>01168 SQLITE_API <span class="keywordtype">int</span> sqlite3_os_init(<span class="keywordtype">void</span>);
    1222. 

  1222. <a name="l01169"></a>01169 SQLITE_API <span class="keywordtype">int</span> sqlite3_os_end(<span class="keywordtype">void</span>);
    1223. 

  1223. <a name="l01170"></a>01170 
    1224. 

  1224. <a name="l01171"></a>01171 <span class="comment">/*</span>
    1225. 

  1225. <a name="l01172"></a>01172 <span class="comment">** CAPI3REF: Configuring The SQLite Library</span>
    1226. 

  1226. <a name="l01173"></a>01173 <span class="comment">**</span>
    1227. 

  1227. <a name="l01174"></a>01174 <span class="comment">** The sqlite3_config() interface is used to make global configuration</span>
    1228. 

  1228. <a name="l01175"></a>01175 <span class="comment">** changes to SQLite in order to tune SQLite to the specific needs of</span>
    1229. 

  1229. <a name="l01176"></a>01176 <span class="comment">** the application.  The default configuration is recommended for most</span>
    1230. 

  1230. <a name="l01177"></a>01177 <span class="comment">** applications and so this routine is usually not necessary.  It is</span>
    1231. 

  1231. <a name="l01178"></a>01178 <span class="comment">** provided to support rare applications with unusual needs.</span>
    1232. 

  1232. <a name="l01179"></a>01179 <span class="comment">**</span>
    1233. 

  1233. <a name="l01180"></a>01180 <span class="comment">** The sqlite3_config() interface is not threadsafe.  The application</span>
    1234. 

  1234. <a name="l01181"></a>01181 <span class="comment">** must insure that no other SQLite interfaces are invoked by other</span>
    1235. 

  1235. <a name="l01182"></a>01182 <span class="comment">** threads while sqlite3_config() is running.  Furthermore, sqlite3_config()</span>
    1236. 

  1236. <a name="l01183"></a>01183 <span class="comment">** may only be invoked prior to library initialization using</span>
    1237. 

  1237. <a name="l01184"></a>01184 <span class="comment">** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].</span>
    1238. 

  1238. <a name="l01185"></a>01185 <span class="comment">** ^If sqlite3_config() is called after [sqlite3_initialize()] and before</span>
    1239. 

  1239. <a name="l01186"></a>01186 <span class="comment">** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.</span>
    1240. 

  1240. <a name="l01187"></a>01187 <span class="comment">** Note, however, that ^sqlite3_config() can be called as part of the</span>
    1241. 

  1241. <a name="l01188"></a>01188 <span class="comment">** implementation of an application-defined [sqlite3_os_init()].</span>
    1242. 

  1242. <a name="l01189"></a>01189 <span class="comment">**</span>
    1243. 

  1243. <a name="l01190"></a>01190 <span class="comment">** The first argument to sqlite3_config() is an integer</span>
    1244. 

  1244. <a name="l01191"></a>01191 <span class="comment">** [configuration option] that determines</span>
    1245. 

  1245. <a name="l01192"></a>01192 <span class="comment">** what property of SQLite is to be configured.  Subsequent arguments</span>
    1246. 

  1246. <a name="l01193"></a>01193 <span class="comment">** vary depending on the [configuration option]</span>
    1247. 

  1247. <a name="l01194"></a>01194 <span class="comment">** in the first argument.</span>
    1248. 

  1248. <a name="l01195"></a>01195 <span class="comment">**</span>
    1249. 

  1249. <a name="l01196"></a>01196 <span class="comment">** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].</span>
    1250. 

  1250. <a name="l01197"></a>01197 <span class="comment">** ^If the option is unknown or SQLite is unable to set the option</span>
    1251. 

  1251. <a name="l01198"></a>01198 <span class="comment">** then this routine returns a non-zero [error code].</span>
    1252. 

  1252. <a name="l01199"></a>01199 <span class="comment">*/</span>
    1253. 

  1253. <a name="l01200"></a>01200 SQLITE_API <span class="keywordtype">int</span> sqlite3_config(<span class="keywordtype">int</span>, ...);
    1254. 

  1254. <a name="l01201"></a>01201 
    1255. 

  1255. <a name="l01202"></a>01202 <span class="comment">/*</span>
    1256. 

  1256. <a name="l01203"></a>01203 <span class="comment">** CAPI3REF: Configure database connections</span>
    1257. 

  1257. <a name="l01204"></a>01204 <span class="comment">**</span>
    1258. 

  1258. <a name="l01205"></a>01205 <span class="comment">** The sqlite3_db_config() interface is used to make configuration</span>
    1259. 

  1259. <a name="l01206"></a>01206 <span class="comment">** changes to a [database connection].  The interface is similar to</span>
    1260. 

  1260. <a name="l01207"></a>01207 <span class="comment">** [sqlite3_config()] except that the changes apply to a single</span>
    1261. 

  1261. <a name="l01208"></a>01208 <span class="comment">** [database connection] (specified in the first argument).</span>
    1262. 

  1262. <a name="l01209"></a>01209 <span class="comment">**</span>
    1263. 

  1263. <a name="l01210"></a>01210 <span class="comment">** The second argument to sqlite3_db_config(D,V,...)  is the</span>
    1264. 

  1264. <a name="l01211"></a>01211 <span class="comment">** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code </span>
    1265. 

  1265. <a name="l01212"></a>01212 <span class="comment">** that indicates what aspect of the [database connection] is being configured.</span>
    1266. 

  1266. <a name="l01213"></a>01213 <span class="comment">** Subsequent arguments vary depending on the configuration verb.</span>
    1267. 

  1267. <a name="l01214"></a>01214 <span class="comment">**</span>
    1268. 

  1268. <a name="l01215"></a>01215 <span class="comment">** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if</span>
    1269. 

  1269. <a name="l01216"></a>01216 <span class="comment">** the call is considered successful.</span>
    1270. 

  1270. <a name="l01217"></a>01217 <span class="comment">*/</span>
    1271. 

  1271. <a name="l01218"></a>01218 SQLITE_API <span class="keywordtype">int</span> sqlite3_db_config(<a class="code" href="structsqlite3.html">sqlite3</a>*, <span class="keywordtype">int</span> op, ...);
    1272. 

  1272. <a name="l01219"></a>01219 
    1273. 

  1273. <a name="l01220"></a>01220 <span class="comment">/*</span>
    1274. 

  1274. <a name="l01221"></a>01221 <span class="comment">** CAPI3REF: Memory Allocation Routines</span>
    1275. 

  1275. <a name="l01222"></a>01222 <span class="comment">**</span>
    1276. 

  1276. <a name="l01223"></a>01223 <span class="comment">** An instance of this object defines the interface between SQLite</span>
    1277. 

  1277. <a name="l01224"></a>01224 <span class="comment">** and low-level memory allocation routines.</span>
    1278. 

  1278. <a name="l01225"></a>01225 <span class="comment">**</span>
    1279. 

  1279. <a name="l01226"></a>01226 <span class="comment">** This object is used in only one place in the SQLite interface.</span>
    1280. 

  1280. <a name="l01227"></a>01227 <span class="comment">** A pointer to an instance of this object is the argument to</span>
    1281. 

  1281. <a name="l01228"></a>01228 <span class="comment">** [sqlite3_config()] when the configuration option is</span>
    1282. 

  1282. <a name="l01229"></a>01229 <span class="comment">** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].  </span>
    1283. 

  1283. <a name="l01230"></a>01230 <span class="comment">** By creating an instance of this object</span>
    1284. 

  1284. <a name="l01231"></a>01231 <span class="comment">** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])</span>
    1285. 

  1285. <a name="l01232"></a>01232 <span class="comment">** during configuration, an application can specify an alternative</span>
    1286. 

  1286. <a name="l01233"></a>01233 <span class="comment">** memory allocation subsystem for SQLite to use for all of its</span>
    1287. 

  1287. <a name="l01234"></a>01234 <span class="comment">** dynamic memory needs.</span>
    1288. 

  1288. <a name="l01235"></a>01235 <span class="comment">**</span>
    1289. 

  1289. <a name="l01236"></a>01236 <span class="comment">** Note that SQLite comes with several [built-in memory allocators]</span>
    1290. 

  1290. <a name="l01237"></a>01237 <span class="comment">** that are perfectly adequate for the overwhelming majority of applications</span>
    1291. 

  1291. <a name="l01238"></a>01238 <span class="comment">** and that this object is only useful to a tiny minority of applications</span>
    1292. 

  1292. <a name="l01239"></a>01239 <span class="comment">** with specialized memory allocation requirements.  This object is</span>
    1293. 

  1293. <a name="l01240"></a>01240 <span class="comment">** also used during testing of SQLite in order to specify an alternative</span>
    1294. 

  1294. <a name="l01241"></a>01241 <span class="comment">** memory allocator that simulates memory out-of-memory conditions in</span>
    1295. 

  1295. <a name="l01242"></a>01242 <span class="comment">** order to verify that SQLite recovers gracefully from such</span>
    1296. 

  1296. <a name="l01243"></a>01243 <span class="comment">** conditions.</span>
    1297. 

  1297. <a name="l01244"></a>01244 <span class="comment">**</span>
    1298. 

  1298. <a name="l01245"></a>01245 <span class="comment">** The xMalloc, xRealloc, and xFree methods must work like the</span>
    1299. 

  1299. <a name="l01246"></a>01246 <span class="comment">** malloc(), realloc() and free() functions from the standard C library.</span>
    1300. 

  1300. <a name="l01247"></a>01247 <span class="comment">** ^SQLite guarantees that the second argument to</span>
    1301. 

  1301. <a name="l01248"></a>01248 <span class="comment">** xRealloc is always a value returned by a prior call to xRoundup.</span>
    1302. 

  1302. <a name="l01249"></a>01249 <span class="comment">**</span>
    1303. 

  1303. <a name="l01250"></a>01250 <span class="comment">** xSize should return the allocated size of a memory allocation</span>
    1304. 

  1304. <a name="l01251"></a>01251 <span class="comment">** previously obtained from xMalloc or xRealloc.  The allocated size</span>
    1305. 

  1305. <a name="l01252"></a>01252 <span class="comment">** is always at least as big as the requested size but may be larger.</span>
    1306. 

  1306. <a name="l01253"></a>01253 <span class="comment">**</span>
    1307. 

  1307. <a name="l01254"></a>01254 <span class="comment">** The xRoundup method returns what would be the allocated size of</span>
    1308. 

  1308. <a name="l01255"></a>01255 <span class="comment">** a memory allocation given a particular requested size.  Most memory</span>
    1309. 

  1309. <a name="l01256"></a>01256 <span class="comment">** allocators round up memory allocations at least to the next multiple</span>
    1310. 

  1310. <a name="l01257"></a>01257 <span class="comment">** of 8.  Some allocators round up to a larger multiple or to a power of 2.</span>
    1311. 

  1311. <a name="l01258"></a>01258 <span class="comment">** Every memory allocation request coming in through [sqlite3_malloc()]</span>
    1312. 

  1312. <a name="l01259"></a>01259 <span class="comment">** or [sqlite3_realloc()] first calls xRoundup.  If xRoundup returns 0, </span>
    1313. 

  1313. <a name="l01260"></a>01260 <span class="comment">** that causes the corresponding memory allocation to fail.</span>
    1314. 

  1314. <a name="l01261"></a>01261 <span class="comment">**</span>
    1315. 

  1315. <a name="l01262"></a>01262 <span class="comment">** The xInit method initializes the memory allocator.  (For example,</span>
    1316. 

  1316. <a name="l01263"></a>01263 <span class="comment">** it might allocate any require mutexes or initialize internal data</span>
    1317. 

  1317. <a name="l01264"></a>01264 <span class="comment">** structures.  The xShutdown method is invoked (indirectly) by</span>
    1318. 

  1318. <a name="l01265"></a>01265 <span class="comment">** [sqlite3_shutdown()] and should deallocate any resources acquired</span>
    1319. 

  1319. <a name="l01266"></a>01266 <span class="comment">** by xInit.  The pAppData pointer is used as the only parameter to</span>
    1320. 

  1320. <a name="l01267"></a>01267 <span class="comment">** xInit and xShutdown.</span>
    1321. 

  1321. <a name="l01268"></a>01268 <span class="comment">**</span>
    1322. 

  1322. <a name="l01269"></a>01269 <span class="comment">** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes</span>
    1323. 

  1323. <a name="l01270"></a>01270 <span class="comment">** the xInit method, so the xInit method need not be threadsafe.  The</span>
    1324. 

  1324. <a name="l01271"></a>01271 <span class="comment">** xShutdown method is only called from [sqlite3_shutdown()] so it does</span>
    1325. 

  1325. <a name="l01272"></a>01272 <span class="comment">** not need to be threadsafe either.  For all other methods, SQLite</span>
    1326. 

  1326. <a name="l01273"></a>01273 <span class="comment">** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the</span>
    1327. 

  1327. <a name="l01274"></a>01274 <span class="comment">** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which</span>
    1328. 

  1328. <a name="l01275"></a>01275 <span class="comment">** it is by default) and so the methods are automatically serialized.</span>
    1329. 

  1329. <a name="l01276"></a>01276 <span class="comment">** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other</span>
    1330. 

  1330. <a name="l01277"></a>01277 <span class="comment">** methods must be threadsafe or else make their own arrangements for</span>
    1331. 

  1331. <a name="l01278"></a>01278 <span class="comment">** serialization.</span>
    1332. 

  1332. <a name="l01279"></a>01279 <span class="comment">**</span>
    1333. 

  1333. <a name="l01280"></a>01280 <span class="comment">** SQLite will never invoke xInit() more than once without an intervening</span>
    1334. 

  1334. <a name="l01281"></a>01281 <span class="comment">** call to xShutdown().</span>
    1335. 

  1335. <a name="l01282"></a>01282 <span class="comment">*/</span>
    1336. 

  1336. <a name="l01283"></a>01283 <span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="structsqlite3__mem__methods.html">sqlite3_mem_methods</a> <a class="code" href="structsqlite3__mem__methods.html">sqlite3_mem_methods</a>;
    1337. 

  1337. <a name="l01284"></a>01284 <span class="keyword">struct </span><a class="code" href="structsqlite3__mem__methods.html">sqlite3_mem_methods</a> {
    1338. 

  1338. <a name="l01285"></a>01285   <span class="keywordtype">void</span> *(*xMalloc)(int);         <span class="comment">/* Memory allocation function */</span>
    1339. 

  1339. <a name="l01286"></a>01286   void (*xFree)(<span class="keywordtype">void</span>*);          <span class="comment">/* Free a prior allocation */</span>
    1340. 

  1340. <a name="l01287"></a>01287   <span class="keywordtype">void</span> *(*xRealloc)(<span class="keywordtype">void</span>*,int);  <span class="comment">/* Resize an allocation */</span>
    1341. 

  1341. <a name="l01288"></a>01288   int (*xSize)(<span class="keywordtype">void</span>*);           <span class="comment">/* Return the size of an allocation */</span>
    1342. 

  1342. <a name="l01289"></a>01289   int (*xRoundup)(int);          <span class="comment">/* Round up request size to allocation size */</span>
    1343. 

  1343. <a name="l01290"></a>01290   int (*xInit)(<span class="keywordtype">void</span>*);           <span class="comment">/* Initialize the memory allocator */</span>
    1344. 

  1344. <a name="l01291"></a>01291   void (*xShutdown)(<span class="keywordtype">void</span>*);      <span class="comment">/* Deinitialize the memory allocator */</span>
    1345. 

  1345. <a name="l01292"></a>01292   <span class="keywordtype">void</span> *pAppData;                <span class="comment">/* Argument to xInit() and xShutdown() */</span>
    1346. 

  1346. <a name="l01293"></a>01293 };
    1347. 

  1347. <a name="l01294"></a>01294 
    1348. 

  1348. <a name="l01295"></a>01295 <span class="comment">/*</span>
    1349. 

  1349. <a name="l01296"></a>01296 <span class="comment">** CAPI3REF: Configuration Options</span>
    1350. 

  1350. <a name="l01297"></a>01297 <span class="comment">** KEYWORDS: {configuration option}</span>
    1351. 

  1351. <a name="l01298"></a>01298 <span class="comment">**</span>
    1352. 

  1352. <a name="l01299"></a>01299 <span class="comment">** These constants are the available integer configuration options that</span>
    1353. 

  1353. <a name="l01300"></a>01300 <span class="comment">** can be passed as the first argument to the [sqlite3_config()] interface.</span>
    1354. 

  1354. <a name="l01301"></a>01301 <span class="comment">**</span>
    1355. 

  1355. <a name="l01302"></a>01302 <span class="comment">** New configuration options may be added in future releases of SQLite.</span>
    1356. 

  1356. <a name="l01303"></a>01303 <span class="comment">** Existing configuration options might be discontinued.  Applications</span>
    1357. 

  1357. <a name="l01304"></a>01304 <span class="comment">** should check the return code from [sqlite3_config()] to make sure that</span>
    1358. 

  1358. <a name="l01305"></a>01305 <span class="comment">** the call worked.  The [sqlite3_config()] interface will return a</span>
    1359. 

  1359. <a name="l01306"></a>01306 <span class="comment">** non-zero [error code] if a discontinued or unsupported configuration option</span>
    1360. 

  1360. <a name="l01307"></a>01307 <span class="comment">** is invoked.</span>
    1361. 

  1361. <a name="l01308"></a>01308 <span class="comment">**</span>
    1362. 

  1362. <a name="l01309"></a>01309 <span class="comment">** &lt;dl&gt;</span>
    1363. 

  1363. <a name="l01310"></a>01310 <span class="comment">** [[SQLITE_CONFIG_SINGLETHREAD]] &lt;dt&gt;SQLITE_CONFIG_SINGLETHREAD&lt;/dt&gt;</span>
    1364. 

  1364. <a name="l01311"></a>01311 <span class="comment">** &lt;dd&gt;There are no arguments to this option.  ^This option sets the</span>
    1365. 

  1365. <a name="l01312"></a>01312 <span class="comment">** [threading mode] to Single-thread.  In other words, it disables</span>
    1366. 

  1366. <a name="l01313"></a>01313 <span class="comment">** all mutexing and puts SQLite into a mode where it can only be used</span>
    1367. 

  1367. <a name="l01314"></a>01314 <span class="comment">** by a single thread.   ^If SQLite is compiled with</span>
    1368. 

  1368. <a name="l01315"></a>01315 <span class="comment">** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then</span>
    1369. 

  1369. <a name="l01316"></a>01316 <span class="comment">** it is not possible to change the [threading mode] from its default</span>
    1370. 

  1370. <a name="l01317"></a>01317 <span class="comment">** value of Single-thread and so [sqlite3_config()] will return </span>
    1371. 

  1371. <a name="l01318"></a>01318 <span class="comment">** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD</span>
    1372. 

  1372. <a name="l01319"></a>01319 <span class="comment">** configuration option.&lt;/dd&gt;</span>
    1373. 

  1373. <a name="l01320"></a>01320 <span class="comment">**</span>
    1374. 

  1374. <a name="l01321"></a>01321 <span class="comment">** [[SQLITE_CONFIG_MULTITHREAD]] &lt;dt&gt;SQLITE_CONFIG_MULTITHREAD&lt;/dt&gt;</span>
    1375. 

  1375. <a name="l01322"></a>01322 <span class="comment">** &lt;dd&gt;There are no arguments to this option.  ^This option sets the</span>
    1376. 

  1376. <a name="l01323"></a>01323 <span class="comment">** [threading mode] to Multi-thread.  In other words, it disables</span>
    1377. 

  1377. <a name="l01324"></a>01324 <span class="comment">** mutexing on [database connection] and [prepared statement] objects.</span>
    1378. 

  1378. <a name="l01325"></a>01325 <span class="comment">** The application is responsible for serializing access to</span>
    1379. 

  1379. <a name="l01326"></a>01326 <span class="comment">** [database connections] and [prepared statements].  But other mutexes</span>
    1380. 

  1380. <a name="l01327"></a>01327 <span class="comment">** are enabled so that SQLite will be safe to use in a multi-threaded</span>
    1381. 

  1381. <a name="l01328"></a>01328 <span class="comment">** environment as long as no two threads attempt to use the same</span>
    1382. 

  1382. <a name="l01329"></a>01329 <span class="comment">** [database connection] at the same time.  ^If SQLite is compiled with</span>
    1383. 

  1383. <a name="l01330"></a>01330 <span class="comment">** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then</span>
    1384. 

  1384. <a name="l01331"></a>01331 <span class="comment">** it is not possible to set the Multi-thread [threading mode] and</span>
    1385. 

  1385. <a name="l01332"></a>01332 <span class="comment">** [sqlite3_config()] will return [SQLITE_ERROR] if called with the</span>
    1386. 

  1386. <a name="l01333"></a>01333 <span class="comment">** SQLITE_CONFIG_MULTITHREAD configuration option.&lt;/dd&gt;</span>
    1387. 

  1387. <a name="l01334"></a>01334 <span class="comment">**</span>
    1388. 

  1388. <a name="l01335"></a>01335 <span class="comment">** [[SQLITE_CONFIG_SERIALIZED]] &lt;dt&gt;SQLITE_CONFIG_SERIALIZED&lt;/dt&gt;</span>
    1389. 

  1389. <a name="l01336"></a>01336 <span class="comment">** &lt;dd&gt;There are no arguments to this option.  ^This option sets the</span>
    1390. 

  1390. <a name="l01337"></a>01337 <span class="comment">** [threading mode] to Serialized. In other words, this option enables</span>
    1391. 

  1391. <a name="l01338"></a>01338 <span class="comment">** all mutexes including the recursive</span>
    1392. 

  1392. <a name="l01339"></a>01339 <span class="comment">** mutexes on [database connection] and [prepared statement] objects.</span>
    1393. 

  1393. <a name="l01340"></a>01340 <span class="comment">** In this mode (which is the default when SQLite is compiled with</span>
    1394. 

  1394. <a name="l01341"></a>01341 <span class="comment">** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access</span>
    1395. 

  1395. <a name="l01342"></a>01342 <span class="comment">** to [database connections] and [prepared statements] so that the</span>
    1396. 

  1396. <a name="l01343"></a>01343 <span class="comment">** application is free to use the same [database connection] or the</span>
    1397. 

  1397. <a name="l01344"></a>01344 <span class="comment">** same [prepared statement] in different threads at the same time.</span>
    1398. 

  1398. <a name="l01345"></a>01345 <span class="comment">** ^If SQLite is compiled with</span>
    1399. 

  1399. <a name="l01346"></a>01346 <span class="comment">** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then</span>
    1400. 

  1400. <a name="l01347"></a>01347 <span class="comment">** it is not possible to set the Serialized [threading mode] and</span>
    1401. 

  1401. <a name="l01348"></a>01348 <span class="comment">** [sqlite3_config()] will return [SQLITE_ERROR] if called with the</span>
    1402. 

  1402. <a name="l01349"></a>01349 <span class="comment">** SQLITE_CONFIG_SERIALIZED configuration option.&lt;/dd&gt;</span>
    1403. 

  1403. <a name="l01350"></a>01350 <span class="comment">**</span>
    1404. 

  1404. <a name="l01351"></a>01351 <span class="comment">** [[SQLITE_CONFIG_MALLOC]] &lt;dt&gt;SQLITE_CONFIG_MALLOC&lt;/dt&gt;</span>
    1405. 

  1405. <a name="l01352"></a>01352 <span class="comment">** &lt;dd&gt; ^(This option takes a single argument which is a pointer to an</span>
    1406. 

  1406. <a name="l01353"></a>01353 <span class="comment">** instance of the [sqlite3_mem_methods] structure.  The argument specifies</span>
    1407. 

  1407. <a name="l01354"></a>01354 <span class="comment">** alternative low-level memory allocation routines to be used in place of</span>
    1408. 

  1408. <a name="l01355"></a>01355 <span class="comment">** the memory allocation routines built into SQLite.)^ ^SQLite makes</span>
    1409. 

  1409. <a name="l01356"></a>01356 <span class="comment">** its own private copy of the content of the [sqlite3_mem_methods] structure</span>
    1410. 

  1410. <a name="l01357"></a>01357 <span class="comment">** before the [sqlite3_config()] call returns.&lt;/dd&gt;</span>
    1411. 

  1411. <a name="l01358"></a>01358 <span class="comment">**</span>
    1412. 

  1412. <a name="l01359"></a>01359 <span class="comment">** [[SQLITE_CONFIG_GETMALLOC]] &lt;dt&gt;SQLITE_CONFIG_GETMALLOC&lt;/dt&gt;</span>
    1413. 

  1413. <a name="l01360"></a>01360 <span class="comment">** &lt;dd&gt; ^(This option takes a single argument which is a pointer to an</span>
    1414. 

  1414. <a name="l01361"></a>01361 <span class="comment">** instance of the [sqlite3_mem_methods] structure.  The [sqlite3_mem_methods]</span>
    1415. 

  1415. <a name="l01362"></a>01362 <span class="comment">** structure is filled with the currently defined memory allocation routines.)^</span>
    1416. 

  1416. <a name="l01363"></a>01363 <span class="comment">** This option can be used to overload the default memory allocation</span>
    1417. 

  1417. <a name="l01364"></a>01364 <span class="comment">** routines with a wrapper that simulations memory allocation failure or</span>
    1418. 

  1418. <a name="l01365"></a>01365 <span class="comment">** tracks memory usage, for example. &lt;/dd&gt;</span>
    1419. 

  1419. <a name="l01366"></a>01366 <span class="comment">**</span>
    1420. 

  1420. <a name="l01367"></a>01367 <span class="comment">** [[SQLITE_CONFIG_MEMSTATUS]] &lt;dt&gt;SQLITE_CONFIG_MEMSTATUS&lt;/dt&gt;</span>
    1421. 

  1421. <a name="l01368"></a>01368 <span class="comment">** &lt;dd&gt; ^This option takes single argument of type int, interpreted as a </span>
    1422. 

  1422. <a name="l01369"></a>01369 <span class="comment">** boolean, which enables or disables the collection of memory allocation </span>
    1423. 

  1423. <a name="l01370"></a>01370 <span class="comment">** statistics. ^(When memory allocation statistics are disabled, the </span>
    1424. 

  1424. <a name="l01371"></a>01371 <span class="comment">** following SQLite interfaces become non-operational:</span>
    1425. 

  1425. <a name="l01372"></a>01372 <span class="comment">**   &lt;ul&gt;</span>
    1426. 

  1426. <a name="l01373"></a>01373 <span class="comment">**   &lt;li&gt; [sqlite3_memory_used()]</span>
    1427. 

  1427. <a name="l01374"></a>01374 <span class="comment">**   &lt;li&gt; [sqlite3_memory_highwater()]</span>
    1428. 

  1428. <a name="l01375"></a>01375 <span class="comment">**   &lt;li&gt; [sqlite3_soft_heap_limit64()]</span>
    1429. 

  1429. <a name="l01376"></a>01376 <span class="comment">**   &lt;li&gt; [sqlite3_status()]</span>
    1430. 

  1430. <a name="l01377"></a>01377 <span class="comment">**   &lt;/ul&gt;)^</span>
    1431. 

  1431. <a name="l01378"></a>01378 <span class="comment">** ^Memory allocation statistics are enabled by default unless SQLite is</span>
    1432. 

  1432. <a name="l01379"></a>01379 <span class="comment">** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory</span>
    1433. 

  1433. <a name="l01380"></a>01380 <span class="comment">** allocation statistics are disabled by default.</span>
    1434. 

  1434. <a name="l01381"></a>01381 <span class="comment">** &lt;/dd&gt;</span>
    1435. 

  1435. <a name="l01382"></a>01382 <span class="comment">**</span>
    1436. 

  1436. <a name="l01383"></a>01383 <span class="comment">** [[SQLITE_CONFIG_SCRATCH]] &lt;dt&gt;SQLITE_CONFIG_SCRATCH&lt;/dt&gt;</span>
    1437. 

  1437. <a name="l01384"></a>01384 <span class="comment">** &lt;dd&gt; ^This option specifies a static memory buffer that SQLite can use for</span>
    1438. 

  1438. <a name="l01385"></a>01385 <span class="comment">** scratch memory.  There are three arguments:  A pointer an 8-byte</span>
    1439. 

  1439. <a name="l01386"></a>01386 <span class="comment">** aligned memory buffer from which the scratch allocations will be</span>
    1440. 

  1440. <a name="l01387"></a>01387 <span class="comment">** drawn, the size of each scratch allocation (sz),</span>
    1441. 

  1441. <a name="l01388"></a>01388 <span class="comment">** and the maximum number of scratch allocations (N).  The sz</span>
    1442. 

  1442. <a name="l01389"></a>01389 <span class="comment">** argument must be a multiple of 16.</span>
    1443. 

  1443. <a name="l01390"></a>01390 <span class="comment">** The first argument must be a pointer to an 8-byte aligned buffer</span>
    1444. 

  1444. <a name="l01391"></a>01391 <span class="comment">** of at least sz*N bytes of memory.</span>
    1445. 

  1445. <a name="l01392"></a>01392 <span class="comment">** ^SQLite will use no more than two scratch buffers per thread.  So</span>
    1446. 

  1446. <a name="l01393"></a>01393 <span class="comment">** N should be set to twice the expected maximum number of threads.</span>
    1447. 

  1447. <a name="l01394"></a>01394 <span class="comment">** ^SQLite will never require a scratch buffer that is more than 6</span>
    1448. 

  1448. <a name="l01395"></a>01395 <span class="comment">** times the database page size. ^If SQLite needs needs additional</span>
    1449. 

  1449. <a name="l01396"></a>01396 <span class="comment">** scratch memory beyond what is provided by this configuration option, then </span>
    1450. 

  1450. <a name="l01397"></a>01397 <span class="comment">** [sqlite3_malloc()] will be used to obtain the memory needed.&lt;/dd&gt;</span>
    1451. 

  1451. <a name="l01398"></a>01398 <span class="comment">**</span>
    1452. 

  1452. <a name="l01399"></a>01399 <span class="comment">** [[SQLITE_CONFIG_PAGECACHE]] &lt;dt&gt;SQLITE_CONFIG_PAGECACHE&lt;/dt&gt;</span>
    1453. 

  1453. <a name="l01400"></a>01400 <span class="comment">** &lt;dd&gt; ^This option specifies a static memory buffer that SQLite can use for</span>
    1454. 

  1454. <a name="l01401"></a>01401 <span class="comment">** the database page cache with the default page cache implementation.  </span>
    1455. 

  1455. <a name="l01402"></a>01402 <span class="comment">** This configuration should not be used if an application-define page</span>
    1456. 

  1456. <a name="l01403"></a>01403 <span class="comment">** cache implementation is loaded using the SQLITE_CONFIG_PCACHE2 option.</span>
    1457. 

  1457. <a name="l01404"></a>01404 <span class="comment">** There are three arguments to this option: A pointer to 8-byte aligned</span>
    1458. 

  1458. <a name="l01405"></a>01405 <span class="comment">** memory, the size of each page buffer (sz), and the number of pages (N).</span>
    1459. 

  1459. <a name="l01406"></a>01406 <span class="comment">** The sz argument should be the size of the largest database page</span>
    1460. 

  1460. <a name="l01407"></a>01407 <span class="comment">** (a power of two between 512 and 32768) plus a little extra for each</span>
    1461. 

  1461. <a name="l01408"></a>01408 <span class="comment">** page header.  ^The page header size is 20 to 40 bytes depending on</span>
    1462. 

  1462. <a name="l01409"></a>01409 <span class="comment">** the host architecture.  ^It is harmless, apart from the wasted memory,</span>
    1463. 

  1463. <a name="l01410"></a>01410 <span class="comment">** to make sz a little too large.  The first</span>
    1464. 

  1464. <a name="l01411"></a>01411 <span class="comment">** argument should point to an allocation of at least sz*N bytes of memory.</span>
    1465. 

  1465. <a name="l01412"></a>01412 <span class="comment">** ^SQLite will use the memory provided by the first argument to satisfy its</span>
    1466. 

  1466. <a name="l01413"></a>01413 <span class="comment">** memory needs for the first N pages that it adds to cache.  ^If additional</span>
    1467. 

  1467. <a name="l01414"></a>01414 <span class="comment">** page cache memory is needed beyond what is provided by this option, then</span>
    1468. 

  1468. <a name="l01415"></a>01415 <span class="comment">** SQLite goes to [sqlite3_malloc()] for the additional storage space.</span>
    1469. 

  1469. <a name="l01416"></a>01416 <span class="comment">** The pointer in the first argument must</span>
    1470. 

  1470. <a name="l01417"></a>01417 <span class="comment">** be aligned to an 8-byte boundary or subsequent behavior of SQLite</span>
    1471. 

  1471. <a name="l01418"></a>01418 <span class="comment">** will be undefined.&lt;/dd&gt;</span>
    1472. 

  1472. <a name="l01419"></a>01419 <span class="comment">**</span>
    1473. 

  1473. <a name="l01420"></a>01420 <span class="comment">** [[SQLITE_CONFIG_HEAP]] &lt;dt&gt;SQLITE_CONFIG_HEAP&lt;/dt&gt;</span>
    1474. 

  1474. <a name="l01421"></a>01421 <span class="comment">** &lt;dd&gt; ^This option specifies a static memory buffer that SQLite will use</span>
    1475. 

  1475. <a name="l01422"></a>01422 <span class="comment">** for all of its dynamic memory allocation needs beyond those provided</span>
    1476. 

  1476. <a name="l01423"></a>01423 <span class="comment">** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].</span>
    1477. 

  1477. <a name="l01424"></a>01424 <span class="comment">** There are three arguments: An 8-byte aligned pointer to the memory,</span>
    1478. 

  1478. <a name="l01425"></a>01425 <span class="comment">** the number of bytes in the memory buffer, and the minimum allocation size.</span>
    1479. 

  1479. <a name="l01426"></a>01426 <span class="comment">** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts</span>
    1480. 

  1480. <a name="l01427"></a>01427 <span class="comment">** to using its default memory allocator (the system malloc() implementation),</span>
    1481. 

  1481. <a name="l01428"></a>01428 <span class="comment">** undoing any prior invocation of [SQLITE_CONFIG_MALLOC].  ^If the</span>
    1482. 

  1482. <a name="l01429"></a>01429 <span class="comment">** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or</span>
    1483. 

  1483. <a name="l01430"></a>01430 <span class="comment">** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory</span>
    1484. 

  1484. <a name="l01431"></a>01431 <span class="comment">** allocator is engaged to handle all of SQLites memory allocation needs.</span>
    1485. 

  1485. <a name="l01432"></a>01432 <span class="comment">** The first pointer (the memory pointer) must be aligned to an 8-byte</span>
    1486. 

  1486. <a name="l01433"></a>01433 <span class="comment">** boundary or subsequent behavior of SQLite will be undefined.</span>
    1487. 

  1487. <a name="l01434"></a>01434 <span class="comment">** The minimum allocation size is capped at 2**12. Reasonable values</span>
    1488. 

  1488. <a name="l01435"></a>01435 <span class="comment">** for the minimum allocation size are 2**5 through 2**8.&lt;/dd&gt;</span>
    1489. 

  1489. <a name="l01436"></a>01436 <span class="comment">**</span>
    1490. 

  1490. <a name="l01437"></a>01437 <span class="comment">** [[SQLITE_CONFIG_MUTEX]] &lt;dt&gt;SQLITE_CONFIG_MUTEX&lt;/dt&gt;</span>
    1491. 

  1491. <a name="l01438"></a>01438 <span class="comment">** &lt;dd&gt; ^(This option takes a single argument which is a pointer to an</span>
    1492. 

  1492. <a name="l01439"></a>01439 <span class="comment">** instance of the [sqlite3_mutex_methods] structure.  The argument specifies</span>
    1493. 

  1493. <a name="l01440"></a>01440 <span class="comment">** alternative low-level mutex routines to be used in place</span>
    1494. 

  1494. <a name="l01441"></a>01441 <span class="comment">** the mutex routines built into SQLite.)^  ^SQLite makes a copy of the</span>
    1495. 

  1495. <a name="l01442"></a>01442 <span class="comment">** content of the [sqlite3_mutex_methods] structure before the call to</span>
    1496. 

  1496. <a name="l01443"></a>01443 <span class="comment">** [sqlite3_config()] returns. ^If SQLite is compiled with</span>
    1497. 

  1497. <a name="l01444"></a>01444 <span class="comment">** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then</span>
    1498. 

  1498. <a name="l01445"></a>01445 <span class="comment">** the entire mutexing subsystem is omitted from the build and hence calls to</span>
    1499. 

  1499. <a name="l01446"></a>01446 <span class="comment">** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will</span>
    1500. 

  1500. <a name="l01447"></a>01447 <span class="comment">** return [SQLITE_ERROR].&lt;/dd&gt;</span>
    1501. 

  1501. <a name="l01448"></a>01448 <span class="comment">**</span>
    1502. 

  1502. <a name="l01449"></a>01449 <span class="comment">** [[SQLITE_CONFIG_GETMUTEX]] &lt;dt&gt;SQLITE_CONFIG_GETMUTEX&lt;/dt&gt;</span>
    1503. 

  1503. <a name="l01450"></a>01450 <span class="comment">** &lt;dd&gt; ^(This option takes a single argument which is a pointer to an</span>
    1504. 

  1504. <a name="l01451"></a>01451 <span class="comment">** instance of the [sqlite3_mutex_methods] structure.  The</span>
    1505. 

  1505. <a name="l01452"></a>01452 <span class="comment">** [sqlite3_mutex_methods]</span>
    1506. 

  1506. <a name="l01453"></a>01453 <span class="comment">** structure is filled with the currently defined mutex routines.)^</span>
    1507. 

  1507. <a name="l01454"></a>01454 <span class="comment">** This option can be used to overload the default mutex allocation</span>
    1508. 

  1508. <a name="l01455"></a>01455 <span class="comment">** routines with a wrapper used to track mutex usage for performance</span>
    1509. 

  1509. <a name="l01456"></a>01456 <span class="comment">** profiling or testing, for example.   ^If SQLite is compiled with</span>
    1510. 

  1510. <a name="l01457"></a>01457 <span class="comment">** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then</span>
    1511. 

  1511. <a name="l01458"></a>01458 <span class="comment">** the entire mutexing subsystem is omitted from the build and hence calls to</span>
    1512. 

  1512. <a name="l01459"></a>01459 <span class="comment">** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will</span>
    1513. 

  1513. <a name="l01460"></a>01460 <span class="comment">** return [SQLITE_ERROR].&lt;/dd&gt;</span>
    1514. 

  1514. <a name="l01461"></a>01461 <span class="comment">**</span>
    1515. 

  1515. <a name="l01462"></a>01462 <span class="comment">** [[SQLITE_CONFIG_LOOKASIDE]] &lt;dt&gt;SQLITE_CONFIG_LOOKASIDE&lt;/dt&gt;</span>
    1516. 

  1516. <a name="l01463"></a>01463 <span class="comment">** &lt;dd&gt; ^(This option takes two arguments that determine the default</span>
    1517. 

  1517. <a name="l01464"></a>01464 <span class="comment">** memory allocation for the lookaside memory allocator on each</span>
    1518. 

  1518. <a name="l01465"></a>01465 <span class="comment">** [database connection].  The first argument is the</span>
    1519. 

  1519. <a name="l01466"></a>01466 <span class="comment">** size of each lookaside buffer slot and the second is the number of</span>
    1520. 

  1520. <a name="l01467"></a>01467 <span class="comment">** slots allocated to each database connection.)^  ^(This option sets the</span>
    1521. 

  1521. <a name="l01468"></a>01468 <span class="comment">** &lt;i&gt;default&lt;/i&gt; lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]</span>
    1522. 

  1522. <a name="l01469"></a>01469 <span class="comment">** verb to [sqlite3_db_config()] can be used to change the lookaside</span>
    1523. 

  1523. <a name="l01470"></a>01470 <span class="comment">** configuration on individual connections.)^ &lt;/dd&gt;</span>
    1524. 

  1524. <a name="l01471"></a>01471 <span class="comment">**</span>
    1525. 

  1525. <a name="l01472"></a>01472 <span class="comment">** [[SQLITE_CONFIG_PCACHE2]] &lt;dt&gt;SQLITE_CONFIG_PCACHE2&lt;/dt&gt;</span>
    1526. 

  1526. <a name="l01473"></a>01473 <span class="comment">** &lt;dd&gt; ^(This option takes a single argument which is a pointer to</span>
    1527. 

  1527. <a name="l01474"></a>01474 <span class="comment">** an [sqlite3_pcache_methods2] object.  This object specifies the interface</span>
    1528. 

  1528. <a name="l01475"></a>01475 <span class="comment">** to a custom page cache implementation.)^  ^SQLite makes a copy of the</span>
    1529. 

  1529. <a name="l01476"></a>01476 <span class="comment">** object and uses it for page cache memory allocations.&lt;/dd&gt;</span>
    1530. 

  1530. <a name="l01477"></a>01477 <span class="comment">**</span>
    1531. 

  1531. <a name="l01478"></a>01478 <span class="comment">** [[SQLITE_CONFIG_GETPCACHE2]] &lt;dt&gt;SQLITE_CONFIG_GETPCACHE2&lt;/dt&gt;</span>
    1532. 

  1532. <a name="l01479"></a>01479 <span class="comment">** &lt;dd&gt; ^(This option takes a single argument which is a pointer to an</span>
    1533. 

  1533. <a name="l01480"></a>01480 <span class="comment">** [sqlite3_pcache_methods2] object.  SQLite copies of the current</span>
    1534. 

  1534. <a name="l01481"></a>01481 <span class="comment">** page cache implementation into that object.)^ &lt;/dd&gt;</span>
    1535. 

  1535. <a name="l01482"></a>01482 <span class="comment">**</span>
    1536. 

  1536. <a name="l01483"></a>01483 <span class="comment">** [[SQLITE_CONFIG_LOG]] &lt;dt&gt;SQLITE_CONFIG_LOG&lt;/dt&gt;</span>
    1537. 

  1537. <a name="l01484"></a>01484 <span class="comment">** &lt;dd&gt; ^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a</span>
    1538. 

  1538. <a name="l01485"></a>01485 <span class="comment">** function with a call signature of void(*)(void*,int,const char*), </span>
    1539. 

  1539. <a name="l01486"></a>01486 <span class="comment">** and a pointer to void. ^If the function pointer is not NULL, it is</span>
    1540. 

  1540. <a name="l01487"></a>01487 <span class="comment">** invoked by [sqlite3_log()] to process each logging event.  ^If the</span>
    1541. 

  1541. <a name="l01488"></a>01488 <span class="comment">** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.</span>
    1542. 

  1542. <a name="l01489"></a>01489 <span class="comment">** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is</span>
    1543. 

  1543. <a name="l01490"></a>01490 <span class="comment">** passed through as the first parameter to the application-defined logger</span>
    1544. 

  1544. <a name="l01491"></a>01491 <span class="comment">** function whenever that function is invoked.  ^The second parameter to</span>
    1545. 

  1545. <a name="l01492"></a>01492 <span class="comment">** the logger function is a copy of the first parameter to the corresponding</span>
    1546. 

  1546. <a name="l01493"></a>01493 <span class="comment">** [sqlite3_log()] call and is intended to be a [result code] or an</span>
    1547. 

  1547. <a name="l01494"></a>01494 <span class="comment">** [extended result code].  ^The third parameter passed to the logger is</span>
    1548. 

  1548. <a name="l01495"></a>01495 <span class="comment">** log message after formatting via [sqlite3_snprintf()].</span>
    1549. 

  1549. <a name="l01496"></a>01496 <span class="comment">** The SQLite logging interface is not reentrant; the logger function</span>
    1550. 

  1550. <a name="l01497"></a>01497 <span class="comment">** supplied by the application must not invoke any SQLite interface.</span>
    1551. 

  1551. <a name="l01498"></a>01498 <span class="comment">** In a multi-threaded application, the application-defined logger</span>
    1552. 

  1552. <a name="l01499"></a>01499 <span class="comment">** function must be threadsafe. &lt;/dd&gt;</span>
    1553. 

  1553. <a name="l01500"></a>01500 <span class="comment">**</span>
    1554. 

  1554. <a name="l01501"></a>01501 <span class="comment">** [[SQLITE_CONFIG_URI]] &lt;dt&gt;SQLITE_CONFIG_URI</span>
    1555. 

  1555. <a name="l01502"></a>01502 <span class="comment">** &lt;dd&gt; This option takes a single argument of type int. If non-zero, then</span>
    1556. 

  1556. <a name="l01503"></a>01503 <span class="comment">** URI handling is globally enabled. If the parameter is zero, then URI handling</span>
    1557. 

  1557. <a name="l01504"></a>01504 <span class="comment">** is globally disabled. If URI handling is globally enabled, all filenames</span>
    1558. 

  1558. <a name="l01505"></a>01505 <span class="comment">** passed to [sqlite3_open()], [sqlite3_open_v2()], [sqlite3_open16()] or</span>
    1559. 

  1559. <a name="l01506"></a>01506 <span class="comment">** specified as part of [ATTACH] commands are interpreted as URIs, regardless</span>
    1560. 

  1560. <a name="l01507"></a>01507 <span class="comment">** of whether or not the [SQLITE_OPEN_URI] flag is set when the database</span>
    1561. 

  1561. <a name="l01508"></a>01508 <span class="comment">** connection is opened. If it is globally disabled, filenames are</span>
    1562. 

  1562. <a name="l01509"></a>01509 <span class="comment">** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the</span>
    1563. 

  1563. <a name="l01510"></a>01510 <span class="comment">** database connection is opened. By default, URI handling is globally</span>
    1564. 

  1564. <a name="l01511"></a>01511 <span class="comment">** disabled. The default value may be changed by compiling with the</span>
    1565. 

  1565. <a name="l01512"></a>01512 <span class="comment">** [SQLITE_USE_URI] symbol defined.</span>
    1566. 

  1566. <a name="l01513"></a>01513 <span class="comment">**</span>
    1567. 

  1567. <a name="l01514"></a>01514 <span class="comment">** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]</span>
    1568. 

  1568. <a name="l01515"></a>01515 <span class="comment">** &lt;dt&gt;SQLITE_CONFIG_PCACHE and SQLITE_CONFNIG_GETPCACHE</span>
    1569. 

  1569. <a name="l01516"></a>01516 <span class="comment">** &lt;dd&gt; These options are obsolete and should not be used by new code.</span>
    1570. 

  1570. <a name="l01517"></a>01517 <span class="comment">** They are retained for backwards compatibility but are now no-ops.</span>
    1571. 

  1571. <a name="l01518"></a>01518 <span class="comment">** &lt;/dl&gt;</span>
    1572. 

  1572. <a name="l01519"></a>01519 <span class="comment">*/</span>
    1573. 

  1573. <a name="l01520"></a>01520 <span class="preprocessor">#define SQLITE_CONFIG_SINGLETHREAD  1  </span><span class="comment">/* nil */</span>
    1574. 

  1574. <a name="l01521"></a>01521 <span class="preprocessor">#define SQLITE_CONFIG_MULTITHREAD   2  </span><span class="comment">/* nil */</span>
    1575. 

  1575. <a name="l01522"></a>01522 <span class="preprocessor">#define SQLITE_CONFIG_SERIALIZED    3  </span><span class="comment">/* nil */</span>
    1576. 

  1576. <a name="l01523"></a>01523 <span class="preprocessor">#define SQLITE_CONFIG_MALLOC        4  </span><span class="comment">/* sqlite3_mem_methods* */</span>
    1577. 

  1577. <a name="l01524"></a>01524 <span class="preprocessor">#define SQLITE_CONFIG_GETMALLOC     5  </span><span class="comment">/* sqlite3_mem_methods* */</span>
    1578. 

  1578. <a name="l01525"></a>01525 <span class="preprocessor">#define SQLITE_CONFIG_SCRATCH       6  </span><span class="comment">/* void*, int sz, int N */</span>
    1579. 

  1579. <a name="l01526"></a>01526 <span class="preprocessor">#define SQLITE_CONFIG_PAGECACHE     7  </span><span class="comment">/* void*, int sz, int N */</span>
    1580. 

  1580. <a name="l01527"></a>01527 <span class="preprocessor">#define SQLITE_CONFIG_HEAP          8  </span><span class="comment">/* void*, int nByte, int min */</span>
    1581. 

  1581. <a name="l01528"></a>01528 <span class="preprocessor">#define SQLITE_CONFIG_MEMSTATUS     9  </span><span class="comment">/* boolean */</span>
    1582. 

  1582. <a name="l01529"></a>01529 <span class="preprocessor">#define SQLITE_CONFIG_MUTEX        10  </span><span class="comment">/* sqlite3_mutex_methods* */</span>
    1583. 

  1583. <a name="l01530"></a>01530 <span class="preprocessor">#define SQLITE_CONFIG_GETMUTEX     11  </span><span class="comment">/* sqlite3_mutex_methods* */</span>
    1584. 

  1584. <a name="l01531"></a>01531 <span class="comment">/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */</span> 
    1585. 

  1585. <a name="l01532"></a>01532 <span class="preprocessor">#define SQLITE_CONFIG_LOOKASIDE    13  </span><span class="comment">/* int int */</span>
    1586. 

  1586. <a name="l01533"></a>01533 <span class="preprocessor">#define SQLITE_CONFIG_PCACHE       14  </span><span class="comment">/* no-op */</span>
    1587. 

  1587. <a name="l01534"></a>01534 <span class="preprocessor">#define SQLITE_CONFIG_GETPCACHE    15  </span><span class="comment">/* no-op */</span>
    1588. 

  1588. <a name="l01535"></a>01535 <span class="preprocessor">#define SQLITE_CONFIG_LOG          16  </span><span class="comment">/* xFunc, void* */</span>
    1589. 

  1589. <a name="l01536"></a>01536 <span class="preprocessor">#define SQLITE_CONFIG_URI          17  </span><span class="comment">/* int */</span>
    1590. 

  1590. <a name="l01537"></a>01537 <span class="preprocessor">#define SQLITE_CONFIG_PCACHE2      18  </span><span class="comment">/* sqlite3_pcache_methods2* */</span>
    1591. 

  1591. <a name="l01538"></a>01538 <span class="preprocessor">#define SQLITE_CONFIG_GETPCACHE2   19  </span><span class="comment">/* sqlite3_pcache_methods2* */</span>
    1592. 

  1592. <a name="l01539"></a>01539 
    1593. 

  1593. <a name="l01540"></a>01540 <span class="comment">/*</span>
    1594. 

  1594. <a name="l01541"></a>01541 <span class="comment">** CAPI3REF: Database Connection Configuration Options</span>
    1595. 

  1595. <a name="l01542"></a>01542 <span class="comment">**</span>
    1596. 

  1596. <a name="l01543"></a>01543 <span class="comment">** These constants are the available integer configuration options that</span>
    1597. 

  1597. <a name="l01544"></a>01544 <span class="comment">** can be passed as the second argument to the [sqlite3_db_config()] interface.</span>
    1598. 

  1598. <a name="l01545"></a>01545 <span class="comment">**</span>
    1599. 

  1599. <a name="l01546"></a>01546 <span class="comment">** New configuration options may be added in future releases of SQLite.</span>
    1600. 

  1600. <a name="l01547"></a>01547 <span class="comment">** Existing configuration options might be discontinued.  Applications</span>
    1601. 

  1601. <a name="l01548"></a>01548 <span class="comment">** should check the return code from [sqlite3_db_config()] to make sure that</span>
    1602. 

  1602. <a name="l01549"></a>01549 <span class="comment">** the call worked.  ^The [sqlite3_db_config()] interface will return a</span>
    1603. 

  1603. <a name="l01550"></a>01550 <span class="comment">** non-zero [error code] if a discontinued or unsupported configuration option</span>
    1604. 

  1604. <a name="l01551"></a>01551 <span class="comment">** is invoked.</span>
    1605. 

  1605. <a name="l01552"></a>01552 <span class="comment">**</span>
    1606. 

  1606. <a name="l01553"></a>01553 <span class="comment">** &lt;dl&gt;</span>
    1607. 

  1607. <a name="l01554"></a>01554 <span class="comment">** &lt;dt&gt;SQLITE_DBCONFIG_LOOKASIDE&lt;/dt&gt;</span>
    1608. 

  1608. <a name="l01555"></a>01555 <span class="comment">** &lt;dd&gt; ^This option takes three additional arguments that determine the </span>
    1609. 

  1609. <a name="l01556"></a>01556 <span class="comment">** [lookaside memory allocator] configuration for the [database connection].</span>
    1610. 

  1610. <a name="l01557"></a>01557 <span class="comment">** ^The first argument (the third parameter to [sqlite3_db_config()] is a</span>
    1611. 

  1611. <a name="l01558"></a>01558 <span class="comment">** pointer to a memory buffer to use for lookaside memory.</span>
    1612. 

  1612. <a name="l01559"></a>01559 <span class="comment">** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb</span>
    1613. 

  1613. <a name="l01560"></a>01560 <span class="comment">** may be NULL in which case SQLite will allocate the</span>
    1614. 

  1614. <a name="l01561"></a>01561 <span class="comment">** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the</span>
    1615. 

  1615. <a name="l01562"></a>01562 <span class="comment">** size of each lookaside buffer slot.  ^The third argument is the number of</span>
    1616. 

  1616. <a name="l01563"></a>01563 <span class="comment">** slots.  The size of the buffer in the first argument must be greater than</span>
    1617. 

  1617. <a name="l01564"></a>01564 <span class="comment">** or equal to the product of the second and third arguments.  The buffer</span>
    1618. 

  1618. <a name="l01565"></a>01565 <span class="comment">** must be aligned to an 8-byte boundary.  ^If the second argument to</span>
    1619. 

  1619. <a name="l01566"></a>01566 <span class="comment">** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally</span>
    1620. 

  1620. <a name="l01567"></a>01567 <span class="comment">** rounded down to the next smaller multiple of 8.  ^(The lookaside memory</span>
    1621. 

  1621. <a name="l01568"></a>01568 <span class="comment">** configuration for a database connection can only be changed when that</span>
    1622. 

  1622. <a name="l01569"></a>01569 <span class="comment">** connection is not currently using lookaside memory, or in other words</span>
    1623. 

  1623. <a name="l01570"></a>01570 <span class="comment">** when the &quot;current value&quot; returned by</span>
    1624. 

  1624. <a name="l01571"></a>01571 <span class="comment">** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.</span>
    1625. 

  1625. <a name="l01572"></a>01572 <span class="comment">** Any attempt to change the lookaside memory configuration when lookaside</span>
    1626. 

  1626. <a name="l01573"></a>01573 <span class="comment">** memory is in use leaves the configuration unchanged and returns </span>
    1627. 

  1627. <a name="l01574"></a>01574 <span class="comment">** [SQLITE_BUSY].)^&lt;/dd&gt;</span>
    1628. 

  1628. <a name="l01575"></a>01575 <span class="comment">**</span>
    1629. 

  1629. <a name="l01576"></a>01576 <span class="comment">** &lt;dt&gt;SQLITE_DBCONFIG_ENABLE_FKEY&lt;/dt&gt;</span>
    1630. 

  1630. <a name="l01577"></a>01577 <span class="comment">** &lt;dd&gt; ^This option is used to enable or disable the enforcement of</span>
    1631. 

  1631. <a name="l01578"></a>01578 <span class="comment">** [foreign key constraints].  There should be two additional arguments.</span>
    1632. 

  1632. <a name="l01579"></a>01579 <span class="comment">** The first argument is an integer which is 0 to disable FK enforcement,</span>
    1633. 

  1633. <a name="l01580"></a>01580 <span class="comment">** positive to enable FK enforcement or negative to leave FK enforcement</span>
    1634. 

  1634. <a name="l01581"></a>01581 <span class="comment">** unchanged.  The second parameter is a pointer to an integer into which</span>
    1635. 

  1635. <a name="l01582"></a>01582 <span class="comment">** is written 0 or 1 to indicate whether FK enforcement is off or on</span>
    1636. 

  1636. <a name="l01583"></a>01583 <span class="comment">** following this call.  The second parameter may be a NULL pointer, in</span>
    1637. 

  1637. <a name="l01584"></a>01584 <span class="comment">** which case the FK enforcement setting is not reported back. &lt;/dd&gt;</span>
    1638. 

  1638. <a name="l01585"></a>01585 <span class="comment">**</span>
    1639. 

  1639. <a name="l01586"></a>01586 <span class="comment">** &lt;dt&gt;SQLITE_DBCONFIG_ENABLE_TRIGGER&lt;/dt&gt;</span>
    1640. 

  1640. <a name="l01587"></a>01587 <span class="comment">** &lt;dd&gt; ^This option is used to enable or disable [CREATE TRIGGER | triggers].</span>
    1641. 

  1641. <a name="l01588"></a>01588 <span class="comment">** There should be two additional arguments.</span>
    1642. 

  1642. <a name="l01589"></a>01589 <span class="comment">** The first argument is an integer which is 0 to disable triggers,</span>
    1643. 

  1643. <a name="l01590"></a>01590 <span class="comment">** positive to enable triggers or negative to leave the setting unchanged.</span>
    1644. 

  1644. <a name="l01591"></a>01591 <span class="comment">** The second parameter is a pointer to an integer into which</span>
    1645. 

  1645. <a name="l01592"></a>01592 <span class="comment">** is written 0 or 1 to indicate whether triggers are disabled or enabled</span>
    1646. 

  1646. <a name="l01593"></a>01593 <span class="comment">** following this call.  The second parameter may be a NULL pointer, in</span>
    1647. 

  1647. <a name="l01594"></a>01594 <span class="comment">** which case the trigger setting is not reported back. &lt;/dd&gt;</span>
    1648. 

  1648. <a name="l01595"></a>01595 <span class="comment">**</span>
    1649. 

  1649. <a name="l01596"></a>01596 <span class="comment">** &lt;/dl&gt;</span>
    1650. 

  1650. <a name="l01597"></a>01597 <span class="comment">*/</span>
    1651. 

  1651. <a name="l01598"></a>01598 <span class="preprocessor">#define SQLITE_DBCONFIG_LOOKASIDE       1001  </span><span class="comment">/* void* int int */</span>
    1652. 

  1652. <a name="l01599"></a>01599 <span class="preprocessor">#define SQLITE_DBCONFIG_ENABLE_FKEY     1002  </span><span class="comment">/* int int* */</span>
    1653. 

  1653. <a name="l01600"></a>01600 <span class="preprocessor">#define SQLITE_DBCONFIG_ENABLE_TRIGGER  1003  </span><span class="comment">/* int int* */</span>
    1654. 

  1654. <a name="l01601"></a>01601 
    1655. 

  1655. <a name="l01602"></a>01602 
    1656. 

  1656. <a name="l01603"></a>01603 <span class="comment">/*</span>
    1657. 

  1657. <a name="l01604"></a>01604 <span class="comment">** CAPI3REF: Enable Or Disable Extended Result Codes</span>
    1658. 

  1658. <a name="l01605"></a>01605 <span class="comment">**</span>
    1659. 

  1659. <a name="l01606"></a>01606 <span class="comment">** ^The sqlite3_extended_result_codes() routine enables or disables the</span>
    1660. 

  1660. <a name="l01607"></a>01607 <span class="comment">** [extended result codes] feature of SQLite. ^The extended result</span>
    1661. 

  1661. <a name="l01608"></a>01608 <span class="comment">** codes are disabled by default for historical compatibility.</span>
    1662. 

  1662. <a name="l01609"></a>01609 <span class="comment">*/</span>
    1663. 

  1663. <a name="l01610"></a>01610 SQLITE_API <span class="keywordtype">int</span> sqlite3_extended_result_codes(<a class="code" href="structsqlite3.html">sqlite3</a>*, <span class="keywordtype">int</span> onoff);
    1664. 

  1664. <a name="l01611"></a>01611 
    1665. 

  1665. <a name="l01612"></a>01612 <span class="comment">/*</span>
    1666. 

  1666. <a name="l01613"></a>01613 <span class="comment">** CAPI3REF: Last Insert Rowid</span>
    1667. 

  1667. <a name="l01614"></a>01614 <span class="comment">**</span>
    1668. 

  1668. <a name="l01615"></a>01615 <span class="comment">** ^Each entry in an SQLite table has a unique 64-bit signed</span>
    1669. 

  1669. <a name="l01616"></a>01616 <span class="comment">** integer key called the [ROWID | &quot;rowid&quot;]. ^The rowid is always available</span>
    1670. 

  1670. <a name="l01617"></a>01617 <span class="comment">** as an undeclared column named ROWID, OID, or _ROWID_ as long as those</span>
    1671. 

  1671. <a name="l01618"></a>01618 <span class="comment">** names are not also used by explicitly declared columns. ^If</span>
    1672. 

  1672. <a name="l01619"></a>01619 <span class="comment">** the table has a column of type [INTEGER PRIMARY KEY] then that column</span>
    1673. 

  1673. <a name="l01620"></a>01620 <span class="comment">** is another alias for the rowid.</span>
    1674. 

  1674. <a name="l01621"></a>01621 <span class="comment">**</span>
    1675. 

  1675. <a name="l01622"></a>01622 <span class="comment">** ^This routine returns the [rowid] of the most recent</span>
    1676. 

  1676. <a name="l01623"></a>01623 <span class="comment">** successful [INSERT] into the database from the [database connection]</span>
    1677. 

  1677. <a name="l01624"></a>01624 <span class="comment">** in the first argument.  ^As of SQLite version 3.7.7, this routines</span>
    1678. 

  1678. <a name="l01625"></a>01625 <span class="comment">** records the last insert rowid of both ordinary tables and [virtual tables].</span>
    1679. 

  1679. <a name="l01626"></a>01626 <span class="comment">** ^If no successful [INSERT]s</span>
    1680. 

  1680. <a name="l01627"></a>01627 <span class="comment">** have ever occurred on that database connection, zero is returned.</span>
    1681. 

  1681. <a name="l01628"></a>01628 <span class="comment">**</span>
    1682. 

  1682. <a name="l01629"></a>01629 <span class="comment">** ^(If an [INSERT] occurs within a trigger or within a [virtual table]</span>
    1683. 

  1683. <a name="l01630"></a>01630 <span class="comment">** method, then this routine will return the [rowid] of the inserted</span>
    1684. 

  1684. <a name="l01631"></a>01631 <span class="comment">** row as long as the trigger or virtual table method is running.</span>
    1685. 

  1685. <a name="l01632"></a>01632 <span class="comment">** But once the trigger or virtual table method ends, the value returned </span>
    1686. 

  1686. <a name="l01633"></a>01633 <span class="comment">** by this routine reverts to what it was before the trigger or virtual</span>
    1687. 

  1687. <a name="l01634"></a>01634 <span class="comment">** table method began.)^</span>
    1688. 

  1688. <a name="l01635"></a>01635 <span class="comment">**</span>
    1689. 

  1689. <a name="l01636"></a>01636 <span class="comment">** ^An [INSERT] that fails due to a constraint violation is not a</span>
    1690. 

  1690. <a name="l01637"></a>01637 <span class="comment">** successful [INSERT] and does not change the value returned by this</span>
    1691. 

  1691. <a name="l01638"></a>01638 <span class="comment">** routine.  ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,</span>
    1692. 

  1692. <a name="l01639"></a>01639 <span class="comment">** and INSERT OR ABORT make no changes to the return value of this</span>
    1693. 

  1693. <a name="l01640"></a>01640 <span class="comment">** routine when their insertion fails.  ^(When INSERT OR REPLACE</span>
    1694. 

  1694. <a name="l01641"></a>01641 <span class="comment">** encounters a constraint violation, it does not fail.  The</span>
    1695. 

  1695. <a name="l01642"></a>01642 <span class="comment">** INSERT continues to completion after deleting rows that caused</span>
    1696. 

  1696. <a name="l01643"></a>01643 <span class="comment">** the constraint problem so INSERT OR REPLACE will always change</span>
    1697. 

  1697. <a name="l01644"></a>01644 <span class="comment">** the return value of this interface.)^</span>
    1698. 

  1698. <a name="l01645"></a>01645 <span class="comment">**</span>
    1699. 

  1699. <a name="l01646"></a>01646 <span class="comment">** ^For the purposes of this routine, an [INSERT] is considered to</span>
    1700. 

  1700. <a name="l01647"></a>01647 <span class="comment">** be successful even if it is subsequently rolled back.</span>
    1701. 

  1701. <a name="l01648"></a>01648 <span class="comment">**</span>
    1702. 

  1702. <a name="l01649"></a>01649 <span class="comment">** This function is accessible to SQL statements via the</span>
    1703. 

  1703. <a name="l01650"></a>01650 <span class="comment">** [last_insert_rowid() SQL function].</span>
    1704. 

  1704. <a name="l01651"></a>01651 <span class="comment">**</span>
    1705. 

  1705. <a name="l01652"></a>01652 <span class="comment">** If a separate thread performs a new [INSERT] on the same</span>
    1706. 

  1706. <a name="l01653"></a>01653 <span class="comment">** database connection while the [sqlite3_last_insert_rowid()]</span>
    1707. 

  1707. <a name="l01654"></a>01654 <span class="comment">** function is running and thus changes the last insert [rowid],</span>
    1708. 

  1708. <a name="l01655"></a>01655 <span class="comment">** then the value returned by [sqlite3_last_insert_rowid()] is</span>
    1709. 

  1709. <a name="l01656"></a>01656 <span class="comment">** unpredictable and might not equal either the old or the new</span>
    1710. 

  1710. <a name="l01657"></a>01657 <span class="comment">** last insert [rowid].</span>
    1711. 

  1711. <a name="l01658"></a>01658 <span class="comment">*/</span>
    1712. 

  1712. <a name="l01659"></a>01659 SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(<a class="code" href="structsqlite3.html">sqlite3</a>*);
    1713. 

  1713. <a name="l01660"></a>01660 
    1714. 

  1714. <a name="l01661"></a>01661 <span class="comment">/*</span>
    1715. 

  1715. <a name="l01662"></a>01662 <span class="comment">** CAPI3REF: Count The Number Of Rows Modified</span>
    1716. 

  1716. <a name="l01663"></a>01663 <span class="comment">**</span>
    1717. 

  1717. <a name="l01664"></a>01664 <span class="comment">** ^This function returns the number of database rows that were changed</span>
    1718. 

  1718. <a name="l01665"></a>01665 <span class="comment">** or inserted or deleted by the most recently completed SQL statement</span>
    1719. 

  1719. <a name="l01666"></a>01666 <span class="comment">** on the [database connection] specified by the first parameter.</span>
    1720. 

  1720. <a name="l01667"></a>01667 <span class="comment">** ^(Only changes that are directly specified by the [INSERT], [UPDATE],</span>
    1721. 

  1721. <a name="l01668"></a>01668 <span class="comment">** or [DELETE] statement are counted.  Auxiliary changes caused by</span>
    1722. 

  1722. <a name="l01669"></a>01669 <span class="comment">** triggers or [foreign key actions] are not counted.)^ Use the</span>
    1723. 

  1723. <a name="l01670"></a>01670 <span class="comment">** [sqlite3_total_changes()] function to find the total number of changes</span>
    1724. 

  1724. <a name="l01671"></a>01671 <span class="comment">** including changes caused by triggers and foreign key actions.</span>
    1725. 

  1725. <a name="l01672"></a>01672 <span class="comment">**</span>
    1726. 

  1726. <a name="l01673"></a>01673 <span class="comment">** ^Changes to a view that are simulated by an [INSTEAD OF trigger]</span>
    1727. 

  1727. <a name="l01674"></a>01674 <span class="comment">** are not counted.  Only real table changes are counted.</span>
    1728. 

  1728. <a name="l01675"></a>01675 <span class="comment">**</span>
    1729. 

  1729. <a name="l01676"></a>01676 <span class="comment">** ^(A &quot;row change&quot; is a change to a single row of a single table</span>
    1730. 

  1730. <a name="l01677"></a>01677 <span class="comment">** caused by an INSERT, DELETE, or UPDATE statement.  Rows that</span>
    1731. 

  1731. <a name="l01678"></a>01678 <span class="comment">** are changed as side effects of [REPLACE] constraint resolution,</span>
    1732. 

  1732. <a name="l01679"></a>01679 <span class="comment">** rollback, ABORT processing, [DROP TABLE], or by any other</span>
    1733. 

  1733. <a name="l01680"></a>01680 <span class="comment">** mechanisms do not count as direct row changes.)^</span>
    1734. 

  1734. <a name="l01681"></a>01681 <span class="comment">**</span>
    1735. 

  1735. <a name="l01682"></a>01682 <span class="comment">** A &quot;trigger context&quot; is a scope of execution that begins and</span>
    1736. 

  1736. <a name="l01683"></a>01683 <span class="comment">** ends with the script of a [CREATE TRIGGER | trigger]. </span>
    1737. 

  1737. <a name="l01684"></a>01684 <span class="comment">** Most SQL statements are</span>
    1738. 

  1738. <a name="l01685"></a>01685 <span class="comment">** evaluated outside of any trigger.  This is the &quot;top level&quot;</span>
    1739. 

  1739. <a name="l01686"></a>01686 <span class="comment">** trigger context.  If a trigger fires from the top level, a</span>
    1740. 

  1740. <a name="l01687"></a>01687 <span class="comment">** new trigger context is entered for the duration of that one</span>
    1741. 

  1741. <a name="l01688"></a>01688 <span class="comment">** trigger.  Subtriggers create subcontexts for their duration.</span>
    1742. 

  1742. <a name="l01689"></a>01689 <span class="comment">**</span>
    1743. 

  1743. <a name="l01690"></a>01690 <span class="comment">** ^Calling [sqlite3_exec()] or [sqlite3_step()] recursively does</span>
    1744. 

  1744. <a name="l01691"></a>01691 <span class="comment">** not create a new trigger context.</span>
    1745. 

  1745. <a name="l01692"></a>01692 <span class="comment">**</span>
    1746. 

  1746. <a name="l01693"></a>01693 <span class="comment">** ^This function returns the number of direct row changes in the</span>
    1747. 

  1747. <a name="l01694"></a>01694 <span class="comment">** most recent INSERT, UPDATE, or DELETE statement within the same</span>
    1748. 

  1748. <a name="l01695"></a>01695 <span class="comment">** trigger context.</span>
    1749. 

  1749. <a name="l01696"></a>01696 <span class="comment">**</span>
    1750. 

  1750. <a name="l01697"></a>01697 <span class="comment">** ^Thus, when called from the top level, this function returns the</span>
    1751. 

  1751. <a name="l01698"></a>01698 <span class="comment">** number of changes in the most recent INSERT, UPDATE, or DELETE</span>
    1752. 

  1752. <a name="l01699"></a>01699 <span class="comment">** that also occurred at the top level.  ^(Within the body of a trigger,</span>
    1753. 

  1753. <a name="l01700"></a>01700 <span class="comment">** the sqlite3_changes() interface can be called to find the number of</span>
    1754. 

  1754. <a name="l01701"></a>01701 <span class="comment">** changes in the most recently completed INSERT, UPDATE, or DELETE</span>
    1755. 

  1755. <a name="l01702"></a>01702 <span class="comment">** statement within the body of the same trigger.</span>
    1756. 

  1756. <a name="l01703"></a>01703 <span class="comment">** However, the number returned does not include changes</span>
    1757. 

  1757. <a name="l01704"></a>01704 <span class="comment">** caused by subtriggers since those have their own context.)^</span>
    1758. 

  1758. <a name="l01705"></a>01705 <span class="comment">**</span>
    1759. 

  1759. <a name="l01706"></a>01706 <span class="comment">** See also the [sqlite3_total_changes()] interface, the</span>
    1760. 

  1760. <a name="l01707"></a>01707 <span class="comment">** [count_changes pragma], and the [changes() SQL function].</span>
    1761. 

  1761. <a name="l01708"></a>01708 <span class="comment">**</span>
    1762. 

  1762. <a name="l01709"></a>01709 <span class="comment">** If a separate thread makes changes on the same database connection</span>
    1763. 

  1763. <a name="l01710"></a>01710 <span class="comment">** while [sqlite3_changes()] is running then the value returned</span>
    1764. 

  1764. <a name="l01711"></a>01711 <span class="comment">** is unpredictable and not meaningful.</span>
    1765. 

  1765. <a name="l01712"></a>01712 <span class="comment">*/</span>
    1766. 

  1766. <a name="l01713"></a>01713 SQLITE_API <span class="keywordtype">int</span> sqlite3_changes(<a class="code" href="structsqlite3.html">sqlite3</a>*);
    1767. 

  1767. <a name="l01714"></a>01714 
    1768. 

  1768. <a name="l01715"></a>01715 <span class="comment">/*</span>
    1769. 

  1769. <a name="l01716"></a>01716 <span class="comment">** CAPI3REF: Total Number Of Rows Modified</span>
    1770. 

  1770. <a name="l01717"></a>01717 <span class="comment">**</span>
    1771. 

  1771. <a name="l01718"></a>01718 <span class="comment">** ^This function returns the number of row changes caused by [INSERT],</span>
    1772. 

  1772. <a name="l01719"></a>01719 <span class="comment">** [UPDATE] or [DELETE] statements since the [database connection] was opened.</span>
    1773. 

  1773. <a name="l01720"></a>01720 <span class="comment">** ^(The count returned by sqlite3_total_changes() includes all changes</span>
    1774. 

  1774. <a name="l01721"></a>01721 <span class="comment">** from all [CREATE TRIGGER | trigger] contexts and changes made by</span>
    1775. 

  1775. <a name="l01722"></a>01722 <span class="comment">** [foreign key actions]. However,</span>
    1776. 

  1776. <a name="l01723"></a>01723 <span class="comment">** the count does not include changes used to implement [REPLACE] constraints,</span>
    1777. 

  1777. <a name="l01724"></a>01724 <span class="comment">** do rollbacks or ABORT processing, or [DROP TABLE] processing.  The</span>
    1778. 

  1778. <a name="l01725"></a>01725 <span class="comment">** count does not include rows of views that fire an [INSTEAD OF trigger],</span>
    1779. 

  1779. <a name="l01726"></a>01726 <span class="comment">** though if the INSTEAD OF trigger makes changes of its own, those changes </span>
    1780. 

  1780. <a name="l01727"></a>01727 <span class="comment">** are counted.)^</span>
    1781. 

  1781. <a name="l01728"></a>01728 <span class="comment">** ^The sqlite3_total_changes() function counts the changes as soon as</span>
    1782. 

  1782. <a name="l01729"></a>01729 <span class="comment">** the statement that makes them is completed (when the statement handle</span>
    1783. 

  1783. <a name="l01730"></a>01730 <span class="comment">** is passed to [sqlite3_reset()] or [sqlite3_finalize()]).</span>
    1784. 

  1784. <a name="l01731"></a>01731 <span class="comment">**</span>
    1785. 

  1785. <a name="l01732"></a>01732 <span class="comment">** See also the [sqlite3_changes()] interface, the</span>
    1786. 

  1786. <a name="l01733"></a>01733 <span class="comment">** [count_changes pragma], and the [total_changes() SQL function].</span>
    1787. 

  1787. <a name="l01734"></a>01734 <span class="comment">**</span>
    1788. 

  1788. <a name="l01735"></a>01735 <span class="comment">** If a separate thread makes changes on the same database connection</span>
    1789. 

  1789. <a name="l01736"></a>01736 <span class="comment">** while [sqlite3_total_changes()] is running then the value</span>
    1790. 

  1790. <a name="l01737"></a>01737 <span class="comment">** returned is unpredictable and not meaningful.</span>
    1791. 

  1791. <a name="l01738"></a>01738 <span class="comment">*/</span>
    1792. 

  1792. <a name="l01739"></a>01739 SQLITE_API <span class="keywordtype">int</span> sqlite3_total_changes(<a class="code" href="structsqlite3.html">sqlite3</a>*);
    1793. 

  1793. <a name="l01740"></a>01740 
    1794. 

  1794. <a name="l01741"></a>01741 <span class="comment">/*</span>
    1795. 

  1795. <a name="l01742"></a>01742 <span class="comment">** CAPI3REF: Interrupt A Long-Running Query</span>
    1796. 

  1796. <a name="l01743"></a>01743 <span class="comment">**</span>
    1797. 

  1797. <a name="l01744"></a>01744 <span class="comment">** ^This function causes any pending database operation to abort and</span>
    1798. 

  1798. <a name="l01745"></a>01745 <span class="comment">** return at its earliest opportunity. This routine is typically</span>
    1799. 

  1799. <a name="l01746"></a>01746 <span class="comment">** called in response to a user action such as pressing &quot;Cancel&quot;</span>
    1800. 

  1800. <a name="l01747"></a>01747 <span class="comment">** or Ctrl-C where the user wants a long query operation to halt</span>
    1801. 

  1801. <a name="l01748"></a>01748 <span class="comment">** immediately.</span>
    1802. 

  1802. <a name="l01749"></a>01749 <span class="comment">**</span>
    1803. 

  1803. <a name="l01750"></a>01750 <span class="comment">** ^It is safe to call this routine from a thread different from the</span>
    1804. 

  1804. <a name="l01751"></a>01751 <span class="comment">** thread that is currently running the database operation.  But it</span>
    1805. 

  1805. <a name="l01752"></a>01752 <span class="comment">** is not safe to call this routine with a [database connection] that</span>
    1806. 

  1806. <a name="l01753"></a>01753 <span class="comment">** is closed or might close before sqlite3_interrupt() returns.</span>
    1807. 

  1807. <a name="l01754"></a>01754 <span class="comment">**</span>
    1808. 

  1808. <a name="l01755"></a>01755 <span class="comment">** ^If an SQL operation is very nearly finished at the time when</span>
    1809. 

  1809. <a name="l01756"></a>01756 <span class="comment">** sqlite3_interrupt() is called, then it might not have an opportunity</span>
    1810. 

  1810. <a name="l01757"></a>01757 <span class="comment">** to be interrupted and might continue to completion.</span>
    1811. 

  1811. <a name="l01758"></a>01758 <span class="comment">**</span>
    1812. 

  1812. <a name="l01759"></a>01759 <span class="comment">** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].</span>
    1813. 

  1813. <a name="l01760"></a>01760 <span class="comment">** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE</span>
    1814. 

  1814. <a name="l01761"></a>01761 <span class="comment">** that is inside an explicit transaction, then the entire transaction</span>
    1815. 

  1815. <a name="l01762"></a>01762 <span class="comment">** will be rolled back automatically.</span>
    1816. 

  1816. <a name="l01763"></a>01763 <span class="comment">**</span>
    1817. 

  1817. <a name="l01764"></a>01764 <span class="comment">** ^The sqlite3_interrupt(D) call is in effect until all currently running</span>
    1818. 

  1818. <a name="l01765"></a>01765 <span class="comment">** SQL statements on [database connection] D complete.  ^Any new SQL statements</span>
    1819. 

  1819. <a name="l01766"></a>01766 <span class="comment">** that are started after the sqlite3_interrupt() call and before the </span>
    1820. 

  1820. <a name="l01767"></a>01767 <span class="comment">** running statements reaches zero are interrupted as if they had been</span>
    1821. 

  1821. <a name="l01768"></a>01768 <span class="comment">** running prior to the sqlite3_interrupt() call.  ^New SQL statements</span>
    1822. 

  1822. <a name="l01769"></a>01769 <span class="comment">** that are started after the running statement count reaches zero are</span>
    1823. 

  1823. <a name="l01770"></a>01770 <span class="comment">** not effected by the sqlite3_interrupt().</span>
    1824. 

  1824. <a name="l01771"></a>01771 <span class="comment">** ^A call to sqlite3_interrupt(D) that occurs when there are no running</span>
    1825. 

  1825. <a name="l01772"></a>01772 <span class="comment">** SQL statements is a no-op and has no effect on SQL statements</span>
    1826. 

  1826. <a name="l01773"></a>01773 <span class="comment">** that are started after the sqlite3_interrupt() call returns.</span>
    1827. 

  1827. <a name="l01774"></a>01774 <span class="comment">**</span>
    1828. 

  1828. <a name="l01775"></a>01775 <span class="comment">** If the database connection closes while [sqlite3_interrupt()]</span>
    1829. 

  1829. <a name="l01776"></a>01776 <span class="comment">** is running then bad things will likely happen.</span>
    1830. 

  1830. <a name="l01777"></a>01777 <span class="comment">*/</span>
    1831. 

  1831. <a name="l01778"></a>01778 SQLITE_API <span class="keywordtype">void</span> sqlite3_interrupt(<a class="code" href="structsqlite3.html">sqlite3</a>*);
    1832. 

  1832. <a name="l01779"></a>01779 
    1833. 

  1833. <a name="l01780"></a>01780 <span class="comment">/*</span>
    1834. 

  1834. <a name="l01781"></a>01781 <span class="comment">** CAPI3REF: Determine If An SQL Statement Is Complete</span>
    1835. 

  1835. <a name="l01782"></a>01782 <span class="comment">**</span>
    1836. 

  1836. <a name="l01783"></a>01783 <span class="comment">** These routines are useful during command-line input to determine if the</span>
    1837. 

  1837. <a name="l01784"></a>01784 <span class="comment">** currently entered text seems to form a complete SQL statement or</span>
    1838. 

  1838. <a name="l01785"></a>01785 <span class="comment">** if additional input is needed before sending the text into</span>
    1839. 

  1839. <a name="l01786"></a>01786 <span class="comment">** SQLite for parsing.  ^These routines return 1 if the input string</span>
    1840. 

  1840. <a name="l01787"></a>01787 <span class="comment">** appears to be a complete SQL statement.  ^A statement is judged to be</span>
    1841. 

  1841. <a name="l01788"></a>01788 <span class="comment">** complete if it ends with a semicolon token and is not a prefix of a</span>
    1842. 

  1842. <a name="l01789"></a>01789 <span class="comment">** well-formed CREATE TRIGGER statement.  ^Semicolons that are embedded within</span>
    1843. 

  1843. <a name="l01790"></a>01790 <span class="comment">** string literals or quoted identifier names or comments are not</span>
    1844. 

  1844. <a name="l01791"></a>01791 <span class="comment">** independent tokens (they are part of the token in which they are</span>
    1845. 

  1845. <a name="l01792"></a>01792 <span class="comment">** embedded) and thus do not count as a statement terminator.  ^Whitespace</span>
    1846. 

  1846. <a name="l01793"></a>01793 <span class="comment">** and comments that follow the final semicolon are ignored.</span>
    1847. 

  1847. <a name="l01794"></a>01794 <span class="comment">**</span>
    1848. 

  1848. <a name="l01795"></a>01795 <span class="comment">** ^These routines return 0 if the statement is incomplete.  ^If a</span>
    1849. 

  1849. <a name="l01796"></a>01796 <span class="comment">** memory allocation fails, then SQLITE_NOMEM is returned.</span>
    1850. 

  1850. <a name="l01797"></a>01797 <span class="comment">**</span>
    1851. 

  1851. <a name="l01798"></a>01798 <span class="comment">** ^These routines do not parse the SQL statements thus</span>
    1852. 

  1852. <a name="l01799"></a>01799 <span class="comment">** will not detect syntactically incorrect SQL.</span>
    1853. 

  1853. <a name="l01800"></a>01800 <span class="comment">**</span>
    1854. 

  1854. <a name="l01801"></a>01801 <span class="comment">** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior </span>
    1855. 

  1855. <a name="l01802"></a>01802 <span class="comment">** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked</span>
    1856. 

  1856. <a name="l01803"></a>01803 <span class="comment">** automatically by sqlite3_complete16().  If that initialization fails,</span>
    1857. 

  1857. <a name="l01804"></a>01804 <span class="comment">** then the return value from sqlite3_complete16() will be non-zero</span>
    1858. 

  1858. <a name="l01805"></a>01805 <span class="comment">** regardless of whether or not the input SQL is complete.)^</span>
    1859. 

  1859. <a name="l01806"></a>01806 <span class="comment">**</span>
    1860. 

  1860. <a name="l01807"></a>01807 <span class="comment">** The input to [sqlite3_complete()] must be a zero-terminated</span>
    1861. 

  1861. <a name="l01808"></a>01808 <span class="comment">** UTF-8 string.</span>
    1862. 

  1862. <a name="l01809"></a>01809 <span class="comment">**</span>
    1863. 

  1863. <a name="l01810"></a>01810 <span class="comment">** The input to [sqlite3_complete16()] must be a zero-terminated</span>
    1864. 

  1864. <a name="l01811"></a>01811 <span class="comment">** UTF-16 string in native byte order.</span>
    1865. 

  1865. <a name="l01812"></a>01812 <span class="comment">*/</span>
    1866. 

  1866. <a name="l01813"></a>01813 SQLITE_API <span class="keywordtype">int</span> sqlite3_complete(<span class="keyword">const</span> <span class="keywordtype">char</span> *sql);
    1867. 

  1867. <a name="l01814"></a>01814 SQLITE_API <span class="keywordtype">int</span> sqlite3_complete16(<span class="keyword">const</span> <span class="keywordtype">void</span> *sql);
    1868. 

  1868. <a name="l01815"></a>01815 
    1869. 

  1869. <a name="l01816"></a>01816 <span class="comment">/*</span>
    1870. 

  1870. <a name="l01817"></a>01817 <span class="comment">** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors</span>
    1871. 

  1871. <a name="l01818"></a>01818 <span class="comment">**</span>
    1872. 

  1872. <a name="l01819"></a>01819 <span class="comment">** ^This routine sets a callback function that might be invoked whenever</span>
    1873. 

  1873. <a name="l01820"></a>01820 <span class="comment">** an attempt is made to open a database table that another thread</span>
    1874. 

  1874. <a name="l01821"></a>01821 <span class="comment">** or process has locked.</span>
    1875. 

  1875. <a name="l01822"></a>01822 <span class="comment">**</span>
    1876. 

  1876. <a name="l01823"></a>01823 <span class="comment">** ^If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]</span>
    1877. 

  1877. <a name="l01824"></a>01824 <span class="comment">** is returned immediately upon encountering the lock.  ^If the busy callback</span>
    1878. 

  1878. <a name="l01825"></a>01825 <span class="comment">** is not NULL, then the callback might be invoked with two arguments.</span>
    1879. 

  1879. <a name="l01826"></a>01826 <span class="comment">**</span>
    1880. 

  1880. <a name="l01827"></a>01827 <span class="comment">** ^The first argument to the busy handler is a copy of the void* pointer which</span>
    1881. 

  1881. <a name="l01828"></a>01828 <span class="comment">** is the third argument to sqlite3_busy_handler().  ^The second argument to</span>
    1882. 

  1882. <a name="l01829"></a>01829 <span class="comment">** the busy handler callback is the number of times that the busy handler has</span>
    1883. 

  1883. <a name="l01830"></a>01830 <span class="comment">** been invoked for this locking event.  ^If the</span>
    1884. 

  1884. <a name="l01831"></a>01831 <span class="comment">** busy callback returns 0, then no additional attempts are made to</span>
    1885. 

  1885. <a name="l01832"></a>01832 <span class="comment">** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.</span>
    1886. 

  1886. <a name="l01833"></a>01833 <span class="comment">** ^If the callback returns non-zero, then another attempt</span>
    1887. 

  1887. <a name="l01834"></a>01834 <span class="comment">** is made to open the database for reading and the cycle repeats.</span>
    1888. 

  1888. <a name="l01835"></a>01835 <span class="comment">**</span>
    1889. 

  1889. <a name="l01836"></a>01836 <span class="comment">** The presence of a busy handler does not guarantee that it will be invoked</span>
    1890. 

  1890. <a name="l01837"></a>01837 <span class="comment">** when there is lock contention. ^If SQLite determines that invoking the busy</span>
    1891. 

  1891. <a name="l01838"></a>01838 <span class="comment">** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]</span>
    1892. 

  1892. <a name="l01839"></a>01839 <span class="comment">** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler.</span>
    1893. 

  1893. <a name="l01840"></a>01840 <span class="comment">** Consider a scenario where one process is holding a read lock that</span>
    1894. 

  1894. <a name="l01841"></a>01841 <span class="comment">** it is trying to promote to a reserved lock and</span>
    1895. 

  1895. <a name="l01842"></a>01842 <span class="comment">** a second process is holding a reserved lock that it is trying</span>
    1896. 

  1896. <a name="l01843"></a>01843 <span class="comment">** to promote to an exclusive lock.  The first process cannot proceed</span>
    1897. 

  1897. <a name="l01844"></a>01844 <span class="comment">** because it is blocked by the second and the second process cannot</span>
    1898. 

  1898. <a name="l01845"></a>01845 <span class="comment">** proceed because it is blocked by the first.  If both processes</span>
    1899. 

  1899. <a name="l01846"></a>01846 <span class="comment">** invoke the busy handlers, neither will make any progress.  Therefore,</span>
    1900. 

  1900. <a name="l01847"></a>01847 <span class="comment">** SQLite returns [SQLITE_BUSY] for the first process, hoping that this</span>
    1901. 

  1901. <a name="l01848"></a>01848 <span class="comment">** will induce the first process to release its read lock and allow</span>
    1902. 

  1902. <a name="l01849"></a>01849 <span class="comment">** the second process to proceed.</span>
    1903. 

  1903. <a name="l01850"></a>01850 <span class="comment">**</span>
    1904. 

  1904. <a name="l01851"></a>01851 <span class="comment">** ^The default busy callback is NULL.</span>
    1905. 

  1905. <a name="l01852"></a>01852 <span class="comment">**</span>
    1906. 

  1906. <a name="l01853"></a>01853 <span class="comment">** ^The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]</span>
    1907. 

  1907. <a name="l01854"></a>01854 <span class="comment">** when SQLite is in the middle of a large transaction where all the</span>
    1908. 

  1908. <a name="l01855"></a>01855 <span class="comment">** changes will not fit into the in-memory cache.  SQLite will</span>
    1909. 

  1909. <a name="l01856"></a>01856 <span class="comment">** already hold a RESERVED lock on the database file, but it needs</span>
    1910. 

  1910. <a name="l01857"></a>01857 <span class="comment">** to promote this lock to EXCLUSIVE so that it can spill cache</span>
    1911. 

  1911. <a name="l01858"></a>01858 <span class="comment">** pages into the database file without harm to concurrent</span>
    1912. 

  1912. <a name="l01859"></a>01859 <span class="comment">** readers.  ^If it is unable to promote the lock, then the in-memory</span>
    1913. 

  1913. <a name="l01860"></a>01860 <span class="comment">** cache will be left in an inconsistent state and so the error</span>
    1914. 

  1914. <a name="l01861"></a>01861 <span class="comment">** code is promoted from the relatively benign [SQLITE_BUSY] to</span>
    1915. 

  1915. <a name="l01862"></a>01862 <span class="comment">** the more severe [SQLITE_IOERR_BLOCKED].  ^This error code promotion</span>
    1916. 

  1916. <a name="l01863"></a>01863 <span class="comment">** forces an automatic rollback of the changes.  See the</span>
    1917. 

  1917. <a name="l01864"></a>01864 <span class="comment">** &lt;a href=&quot;/cvstrac/wiki?p=CorruptionFollowingBusyError&quot;&gt;</span>
    1918. 

  1918. <a name="l01865"></a>01865 <span class="comment">** CorruptionFollowingBusyError&lt;/a&gt; wiki page for a discussion of why</span>
    1919. 

  1919. <a name="l01866"></a>01866 <span class="comment">** this is important.</span>
    1920. 

  1920. <a name="l01867"></a>01867 <span class="comment">**</span>
    1921. 

  1921. <a name="l01868"></a>01868 <span class="comment">** ^(There can only be a single busy handler defined for each</span>
    1922. 

  1922. <a name="l01869"></a>01869 <span class="comment">** [database connection].  Setting a new busy handler clears any</span>
    1923. 

  1923. <a name="l01870"></a>01870 <span class="comment">** previously set handler.)^  ^Note that calling [sqlite3_busy_timeout()]</span>
    1924. 

  1924. <a name="l01871"></a>01871 <span class="comment">** will also set or clear the busy handler.</span>
    1925. 

  1925. <a name="l01872"></a>01872 <span class="comment">**</span>
    1926. 

  1926. <a name="l01873"></a>01873 <span class="comment">** The busy callback should not take any actions which modify the</span>
    1927. 

  1927. <a name="l01874"></a>01874 <span class="comment">** database connection that invoked the busy handler.  Any such actions</span>
    1928. 

  1928. <a name="l01875"></a>01875 <span class="comment">** result in undefined behavior.</span>
    1929. 

  1929. <a name="l01876"></a>01876 <span class="comment">** </span>
    1930. 

  1930. <a name="l01877"></a>01877 <span class="comment">** A busy handler must not close the database connection</span>
    1931. 

  1931. <a name="l01878"></a>01878 <span class="comment">** or [prepared statement] that invoked the busy handler.</span>
    1932. 

  1932. <a name="l01879"></a>01879 <span class="comment">*/</span>
    1933. 

  1933. <a name="l01880"></a>01880 SQLITE_API <span class="keywordtype">int</span> sqlite3_busy_handler(<a class="code" href="structsqlite3.html">sqlite3</a>*, <span class="keywordtype">int</span>(*)(<span class="keywordtype">void</span>*,<span class="keywordtype">int</span>), <span class="keywordtype">void</span>*);
    1934. 

  1934. <a name="l01881"></a>01881 
    1935. 

  1935. <a name="l01882"></a>01882 <span class="comment">/*</span>
    1936. 

  1936. <a name="l01883"></a>01883 <span class="comment">** CAPI3REF: Set A Busy Timeout</span>
    1937. 

  1937. <a name="l01884"></a>01884 <span class="comment">**</span>
    1938. 

  1938. <a name="l01885"></a>01885 <span class="comment">** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps</span>
    1939. 

  1939. <a name="l01886"></a>01886 <span class="comment">** for a specified amount of time when a table is locked.  ^The handler</span>
    1940. 

  1940. <a name="l01887"></a>01887 <span class="comment">** will sleep multiple times until at least &quot;ms&quot; milliseconds of sleeping</span>
    1941. 

  1941. <a name="l01888"></a>01888 <span class="comment">** have accumulated.  ^After at least &quot;ms&quot; milliseconds of sleeping,</span>
    1942. 

  1942. <a name="l01889"></a>01889 <span class="comment">** the handler returns 0 which causes [sqlite3_step()] to return</span>
    1943. 

  1943. <a name="l01890"></a>01890 <span class="comment">** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].</span>
    1944. 

  1944. <a name="l01891"></a>01891 <span class="comment">**</span>
    1945. 

  1945. <a name="l01892"></a>01892 <span class="comment">** ^Calling this routine with an argument less than or equal to zero</span>
    1946. 

  1946. <a name="l01893"></a>01893 <span class="comment">** turns off all busy handlers.</span>
    1947. 

  1947. <a name="l01894"></a>01894 <span class="comment">**</span>
    1948. 

  1948. <a name="l01895"></a>01895 <span class="comment">** ^(There can only be a single busy handler for a particular</span>
    1949. 

  1949. <a name="l01896"></a>01896 <span class="comment">** [database connection] any any given moment.  If another busy handler</span>
    1950. 

  1950. <a name="l01897"></a>01897 <span class="comment">** was defined  (using [sqlite3_busy_handler()]) prior to calling</span>
    1951. 

  1951. <a name="l01898"></a>01898 <span class="comment">** this routine, that other busy handler is cleared.)^</span>
    1952. 

  1952. <a name="l01899"></a>01899 <span class="comment">*/</span>
    1953. 

  1953. <a name="l01900"></a>01900 SQLITE_API <span class="keywordtype">int</span> sqlite3_busy_timeout(<a class="code" href="structsqlite3.html">sqlite3</a>*, <span class="keywordtype">int</span> ms);
    1954. 

  1954. <a name="l01901"></a>01901 
    1955. 

  1955. <a name="l01902"></a>01902 <span class="comment">/*</span>
    1956. 

  1956. <a name="l01903"></a>01903 <span class="comment">** CAPI3REF: Convenience Routines For Running Queries</span>
    1957. 

  1957. <a name="l01904"></a>01904 <span class="comment">**</span>
    1958. 

  1958. <a name="l01905"></a>01905 <span class="comment">** This is a legacy interface that is preserved for backwards compatibility.</span>
    1959. 

  1959. <a name="l01906"></a>01906 <span class="comment">** Use of this interface is not recommended.</span>
    1960. 

  1960. <a name="l01907"></a>01907 <span class="comment">**</span>
    1961. 

  1961. <a name="l01908"></a>01908 <span class="comment">** Definition: A &lt;b&gt;result table&lt;/b&gt; is memory data structure created by the</span>
    1962. 

  1962. <a name="l01909"></a>01909 <span class="comment">** [sqlite3_get_table()] interface.  A result table records the</span>
    1963. 

  1963. <a name="l01910"></a>01910 <span class="comment">** complete query results from one or more queries.</span>
    1964. 

  1964. <a name="l01911"></a>01911 <span class="comment">**</span>
    1965. 

  1965. <a name="l01912"></a>01912 <span class="comment">** The table conceptually has a number of rows and columns.  But</span>
    1966. 

  1966. <a name="l01913"></a>01913 <span class="comment">** these numbers are not part of the result table itself.  These</span>
    1967. 

  1967. <a name="l01914"></a>01914 <span class="comment">** numbers are obtained separately.  Let N be the number of rows</span>
    1968. 

  1968. <a name="l01915"></a>01915 <span class="comment">** and M be the number of columns.</span>
    1969. 

  1969. <a name="l01916"></a>01916 <span class="comment">**</span>
    1970. 

  1970. <a name="l01917"></a>01917 <span class="comment">** A result table is an array of pointers to zero-terminated UTF-8 strings.</span>
    1971. 

  1971. <a name="l01918"></a>01918 <span class="comment">** There are (N+1)*M elements in the array.  The first M pointers point</span>
    1972. 

  1972. <a name="l01919"></a>01919 <span class="comment">** to zero-terminated strings that  contain the names of the columns.</span>
    1973. 

  1973. <a name="l01920"></a>01920 <span class="comment">** The remaining entries all point to query results.  NULL values result</span>
    1974. 

  1974. <a name="l01921"></a>01921 <span class="comment">** in NULL pointers.  All other values are in their UTF-8 zero-terminated</span>
    1975. 

  1975. <a name="l01922"></a>01922 <span class="comment">** string representation as returned by [sqlite3_column_text()].</span>
    1976. 

  1976. <a name="l01923"></a>01923 <span class="comment">**</span>
    1977. 

  1977. <a name="l01924"></a>01924 <span class="comment">** A result table might consist of one or more memory allocations.</span>
    1978. 

  1978. <a name="l01925"></a>01925 <span class="comment">** It is not safe to pass a result table directly to [sqlite3_free()].</span>
    1979. 

  1979. <a name="l01926"></a>01926 <span class="comment">** A result table should be deallocated using [sqlite3_free_table()].</span>
    1980. 

  1980. <a name="l01927"></a>01927 <span class="comment">**</span>
    1981. 

  1981. <a name="l01928"></a>01928 <span class="comment">** ^(As an example of the result table format, suppose a query result</span>
    1982. 

  1982. <a name="l01929"></a>01929 <span class="comment">** is as follows:</span>
    1983. 

  1983. <a name="l01930"></a>01930 <span class="comment">**</span>
    1984. 

  1984. <a name="l01931"></a>01931 <span class="comment">** &lt;blockquote&gt;&lt;pre&gt;</span>
    1985. 

  1985. <a name="l01932"></a>01932 <span class="comment">**        Name        | Age</span>
    1986. 

  1986. <a name="l01933"></a>01933 <span class="comment">**        -----------------------</span>
    1987. 

  1987. <a name="l01934"></a>01934 <span class="comment">**        Alice       | 43</span>
    1988. 

  1988. <a name="l01935"></a>01935 <span class="comment">**        Bob         | 28</span>
    1989. 

  1989. <a name="l01936"></a>01936 <span class="comment">**        Cindy       | 21</span>
    1990. 

  1990. <a name="l01937"></a>01937 <span class="comment">** &lt;/pre&gt;&lt;/blockquote&gt;</span>
    1991. 

  1991. <a name="l01938"></a>01938 <span class="comment">**</span>
    1992. 

  1992. <a name="l01939"></a>01939 <span class="comment">** There are two column (M==2) and three rows (N==3).  Thus the</span>
    1993. 

  1993. <a name="l01940"></a>01940 <span class="comment">** result table has 8 entries.  Suppose the result table is stored</span>
    1994. 

  1994. <a name="l01941"></a>01941 <span class="comment">** in an array names azResult.  Then azResult holds this content:</span>
    1995. 

  1995. <a name="l01942"></a>01942 <span class="comment">**</span>
    1996. 

  1996. <a name="l01943"></a>01943 <span class="comment">** &lt;blockquote&gt;&lt;pre&gt;</span>
    1997. 

  1997. <a name="l01944"></a>01944 <span class="comment">**        azResult&amp;#91;0] = &quot;Name&quot;;</span>
    1998. 

  1998. <a name="l01945"></a>01945 <span class="comment">**        azResult&amp;#91;1] = &quot;Age&quot;;</span>
    1999. 

  1999. <a name="l01946"></a>01946 <span class="comment">**        azResult&amp;#91;2] = &quot;Alice&quot;;</span>
    2000. 

  2000. <a name="l01947"></a>01947 <span class="comment">**        azResult&amp;#91;3] = &quot;43&quot;;</span>
    2001. 

  2001. <a name="l01948"></a>01948 <span class="comment">**        azResult&amp;#91;4] = &quot;Bob&quot;;</span>
    2002. 

  2002. <a name="l01949"></a>01949 <span class="comment">**        azResult&amp;#91;5] = &quot;28&quot;;</span>
    2003. 

  2003. <a name="l01950"></a>01950 <span class="comment">**        azResult&amp;#91;6] = &quot;Cindy&quot;;</span>
    2004. 

  2004. <a name="l01951"></a>01951 <span class="comment">**        azResult&amp;#91;7] = &quot;21&quot;;</span>
    2005. 

  2005. <a name="l01952"></a>01952 <span class="comment">** &lt;/pre&gt;&lt;/blockquote&gt;)^</span>
    2006. 

  2006. <a name="l01953"></a>01953 <span class="comment">**</span>
    2007. 

  2007. <a name="l01954"></a>01954 <span class="comment">** ^The sqlite3_get_table() function evaluates one or more</span>
    2008. 

  2008. <a name="l01955"></a>01955 <span class="comment">** semicolon-separated SQL statements in the zero-terminated UTF-8</span>
    2009. 

  2009. <a name="l01956"></a>01956 <span class="comment">** string of its 2nd parameter and returns a result table to the</span>
    2010. 

  2010. <a name="l01957"></a>01957 <span class="comment">** pointer given in its 3rd parameter.</span>
    2011. 

  2011. <a name="l01958"></a>01958 <span class="comment">**</span>
    2012. 

  2012. <a name="l01959"></a>01959 <span class="comment">** After the application has finished with the result from sqlite3_get_table(),</span>
    2013. 

  2013. <a name="l01960"></a>01960 <span class="comment">** it must pass the result table pointer to sqlite3_free_table() in order to</span>
    2014. 

  2014. <a name="l01961"></a>01961 <span class="comment">** release the memory that was malloced.  Because of the way the</span>
    2015. 

  2015. <a name="l01962"></a>01962 <span class="comment">** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling</span>
    2016. 

  2016. <a name="l01963"></a>01963 <span class="comment">** function must not try to call [sqlite3_free()] directly.  Only</span>
    2017. 

  2017. <a name="l01964"></a>01964 <span class="comment">** [sqlite3_free_table()] is able to release the memory properly and safely.</span>
    2018. 

  2018. <a name="l01965"></a>01965 <span class="comment">**</span>
    2019. 

  2019. <a name="l01966"></a>01966 <span class="comment">** The sqlite3_get_table() interface is implemented as a wrapper around</span>
    2020. 

  2020. <a name="l01967"></a>01967 <span class="comment">** [sqlite3_exec()].  The sqlite3_get_table() routine does not have access</span>
    2021. 

  2021. <a name="l01968"></a>01968 <span class="comment">** to any internal data structures of SQLite.  It uses only the public</span>
    2022. 

  2022. <a name="l01969"></a>01969 <span class="comment">** interface defined here.  As a consequence, errors that occur in the</span>
    2023. 

  2023. <a name="l01970"></a>01970 <span class="comment">** wrapper layer outside of the internal [sqlite3_exec()] call are not</span>
    2024. 

  2024. <a name="l01971"></a>01971 <span class="comment">** reflected in subsequent calls to [sqlite3_errcode()] or</span>
    2025. 

  2025. <a name="l01972"></a>01972 <span class="comment">** [sqlite3_errmsg()].</span>
    2026. 

  2026. <a name="l01973"></a>01973 <span class="comment">*/</span>
    2027. 

  2027. <a name="l01974"></a>01974 SQLITE_API <span class="keywordtype">int</span> sqlite3_get_table(
    2028. 

  2028. <a name="l01975"></a>01975   <a class="code" href="structsqlite3.html">sqlite3</a> *db,          <span class="comment">/* An open database */</span>
    2029. 

  2029. <a name="l01976"></a>01976   <span class="keyword">const</span> <span class="keywordtype">char</span> *zSql,     <span class="comment">/* SQL to be evaluated */</span>
    2030. 

  2030. <a name="l01977"></a>01977   <span class="keywordtype">char</span> ***pazResult,    <span class="comment">/* Results of the query */</span>
    2031. 

  2031. <a name="l01978"></a>01978   <span class="keywordtype">int</span> *pnRow,           <span class="comment">/* Number of result rows written here */</span>
    2032. 

  2032. <a name="l01979"></a>01979   <span class="keywordtype">int</span> *pnColumn,        <span class="comment">/* Number of result columns written here */</span>
    2033. 

  2033. <a name="l01980"></a>01980   <span class="keywordtype">char</span> **pzErrmsg       <span class="comment">/* Error msg written here */</span>
    2034. 

  2034. <a name="l01981"></a>01981 );
    2035. 

  2035. <a name="l01982"></a>01982 SQLITE_API <span class="keywordtype">void</span> sqlite3_free_table(<span class="keywordtype">char</span> **result);
    2036. 

  2036. <a name="l01983"></a>01983 
    2037. 

  2037. <a name="l01984"></a>01984 <span class="comment">/*</span>
    2038. 

  2038. <a name="l01985"></a>01985 <span class="comment">** CAPI3REF: Formatted String Printing Functions</span>
    2039. 

  2039. <a name="l01986"></a>01986 <span class="comment">**</span>
    2040. 

  2040. <a name="l01987"></a>01987 <span class="comment">** These routines are work-alikes of the &quot;printf()&quot; family of functions</span>
    2041. 

  2041. <a name="l01988"></a>01988 <span class="comment">** from the standard C library.</span>
    2042. 

  2042. <a name="l01989"></a>01989 <span class="comment">**</span>
    2043. 

  2043. <a name="l01990"></a>01990 <span class="comment">** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their</span>
    2044. 

  2044. <a name="l01991"></a>01991 <span class="comment">** results into memory obtained from [sqlite3_malloc()].</span>
    2045. 

  2045. <a name="l01992"></a>01992 <span class="comment">** The strings returned by these two routines should be</span>
    2046. 

  2046. <a name="l01993"></a>01993 <span class="comment">** released by [sqlite3_free()].  ^Both routines return a</span>
    2047. 

  2047. <a name="l01994"></a>01994 <span class="comment">** NULL pointer if [sqlite3_malloc()] is unable to allocate enough</span>
    2048. 

  2048. <a name="l01995"></a>01995 <span class="comment">** memory to hold the resulting string.</span>
    2049. 

  2049. <a name="l01996"></a>01996 <span class="comment">**</span>
    2050. 

  2050. <a name="l01997"></a>01997 <span class="comment">** ^(The sqlite3_snprintf() routine is similar to &quot;snprintf()&quot; from</span>
    2051. 

  2051. <a name="l01998"></a>01998 <span class="comment">** the standard C library.  The result is written into the</span>
    2052. 

  2052. <a name="l01999"></a>01999 <span class="comment">** buffer supplied as the second parameter whose size is given by</span>
    2053. 

  2053. <a name="l02000"></a>02000 <span class="comment">** the first parameter. Note that the order of the</span>
    2054. 

  2054. <a name="l02001"></a>02001 <span class="comment">** first two parameters is reversed from snprintf().)^  This is an</span>
    2055. 

  2055. <a name="l02002"></a>02002 <span class="comment">** historical accident that cannot be fixed without breaking</span>
    2056. 

  2056. <a name="l02003"></a>02003 <span class="comment">** backwards compatibility.  ^(Note also that sqlite3_snprintf()</span>
    2057. 

  2057. <a name="l02004"></a>02004 <span class="comment">** returns a pointer to its buffer instead of the number of</span>
    2058. 

  2058. <a name="l02005"></a>02005 <span class="comment">** characters actually written into the buffer.)^  We admit that</span>
    2059. 

  2059. <a name="l02006"></a>02006 <span class="comment">** the number of characters written would be a more useful return</span>
    2060. 

  2060. <a name="l02007"></a>02007 <span class="comment">** value but we cannot change the implementation of sqlite3_snprintf()</span>
    2061. 

  2061. <a name="l02008"></a>02008 <span class="comment">** now without breaking compatibility.</span>
    2062. 

  2062. <a name="l02009"></a>02009 <span class="comment">**</span>
    2063. 

  2063. <a name="l02010"></a>02010 <span class="comment">** ^As long as the buffer size is greater than zero, sqlite3_snprintf()</span>
    2064. 

  2064. <a name="l02011"></a>02011 <span class="comment">** guarantees that the buffer is always zero-terminated.  ^The first</span>
    2065. 

  2065. <a name="l02012"></a>02012 <span class="comment">** parameter &quot;n&quot; is the total size of the buffer, including space for</span>
    2066. 

  2066. <a name="l02013"></a>02013 <span class="comment">** the zero terminator.  So the longest string that can be completely</span>
    2067. 

  2067. <a name="l02014"></a>02014 <span class="comment">** written will be n-1 characters.</span>
    2068. 

  2068. <a name="l02015"></a>02015 <span class="comment">**</span>
    2069. 

  2069. <a name="l02016"></a>02016 <span class="comment">** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().</span>
    2070. 

  2070. <a name="l02017"></a>02017 <span class="comment">**</span>
    2071. 

  2071. <a name="l02018"></a>02018 <span class="comment">** These routines all implement some additional formatting</span>
    2072. 

  2072. <a name="l02019"></a>02019 <span class="comment">** options that are useful for constructing SQL statements.</span>
    2073. 

  2073. <a name="l02020"></a>02020 <span class="comment">** All of the usual printf() formatting options apply.  In addition, there</span>
    2074. 

  2074. <a name="l02021"></a>02021 <span class="comment">** is are &quot;%q&quot;, &quot;%Q&quot;, and &quot;%z&quot; options.</span>
    2075. 

  2075. <a name="l02022"></a>02022 <span class="comment">**</span>
    2076. 

  2076. <a name="l02023"></a>02023 <span class="comment">** ^(The %q option works like %s in that it substitutes a nul-terminated</span>
    2077. 

  2077. <a name="l02024"></a>02024 <span class="comment">** string from the argument list.  But %q also doubles every &#39;\&#39;&#39; character.</span>
    2078. 

  2078. <a name="l02025"></a>02025 <span class="comment">** %q is designed for use inside a string literal.)^  By doubling each &#39;\&#39;&#39;</span>
    2079. 

  2079. <a name="l02026"></a>02026 <span class="comment">** character it escapes that character and allows it to be inserted into</span>
    2080. 

  2080. <a name="l02027"></a>02027 <span class="comment">** the string.</span>
    2081. 

  2081. <a name="l02028"></a>02028 <span class="comment">**</span>
    2082. 

  2082. <a name="l02029"></a>02029 <span class="comment">** For example, assume the string variable zText contains text as follows:</span>
    2083. 

  2083. <a name="l02030"></a>02030 <span class="comment">**</span>
    2084. 

  2084. <a name="l02031"></a>02031 <span class="comment">** &lt;blockquote&gt;&lt;pre&gt;</span>
    2085. 

  2085. <a name="l02032"></a>02032 <span class="comment">**  char *zText = &quot;It&#39;s a happy day!&quot;;</span>
    2086. 

  2086. <a name="l02033"></a>02033 <span class="comment">** &lt;/pre&gt;&lt;/blockquote&gt;</span>
    2087. 

  2087. <a name="l02034"></a>02034 <span class="comment">**</span>
    2088. 

  2088. <a name="l02035"></a>02035 <span class="comment">** One can use this text in an SQL statement as follows:</span>
    2089. 

  2089. <a name="l02036"></a>02036 <span class="comment">**</span>
    2090. 

  2090. <a name="l02037"></a>02037 <span class="comment">** &lt;blockquote&gt;&lt;pre&gt;</span>
    2091. 

  2091. <a name="l02038"></a>02038 <span class="comment">**  char *zSQL = sqlite3_mprintf(&quot;INSERT INTO table VALUES(&#39;%q&#39;)&quot;, zText);</span>
    2092. 

  2092. <a name="l02039"></a>02039 <span class="comment">**  sqlite3_exec(db, zSQL, 0, 0, 0);</span>
    2093. 

  2093. <a name="l02040"></a>02040 <span class="comment">**  sqlite3_free(zSQL);</span>
    2094. 

  2094. <a name="l02041"></a>02041 <span class="comment">** &lt;/pre&gt;&lt;/blockquote&gt;</span>
    2095. 

  2095. <a name="l02042"></a>02042 <span class="comment">**</span>
    2096. 

  2096. <a name="l02043"></a>02043 <span class="comment">** Because the %q format string is used, the &#39;\&#39;&#39; character in zText</span>
    2097. 

  2097. <a name="l02044"></a>02044 <span class="comment">** is escaped and the SQL generated is as follows:</span>
    2098. 

  2098. <a name="l02045"></a>02045 <span class="comment">**</span>
    2099. 

  2099. <a name="l02046"></a>02046 <span class="comment">** &lt;blockquote&gt;&lt;pre&gt;</span>
    2100. 

  2100. <a name="l02047"></a>02047 <span class="comment">**  INSERT INTO table1 VALUES(&#39;It&#39;&#39;s a happy day!&#39;)</span>
    2101. 

  2101. <a name="l02048"></a>02048 <span class="comment">** &lt;/pre&gt;&lt;/blockquote&gt;</span>
    2102. 

  2102. <a name="l02049"></a>02049 <span class="comment">**</span>
    2103. 

  2103. <a name="l02050"></a>02050 <span class="comment">** This is correct.  Had we used %s instead of %q, the generated SQL</span>
    2104. 

  2104. <a name="l02051"></a>02051 <span class="comment">** would have looked like this:</span>
    2105. 

  2105. <a name="l02052"></a>02052 <span class="comment">**</span>
    2106. 

  2106. <a name="l02053"></a>02053 <span class="comment">** &lt;blockquote&gt;&lt;pre&gt;</span>
    2107. 

  2107. <a name="l02054"></a>02054 <span class="comment">**  INSERT INTO table1 VALUES(&#39;It&#39;s a happy day!&#39;);</span>
    2108. 

  2108. <a name="l02055"></a>02055 <span class="comment">** &lt;/pre&gt;&lt;/blockquote&gt;</span>
    2109. 

  2109. <a name="l02056"></a>02056 <span class="comment">**</span>
    2110. 

  2110. <a name="l02057"></a>02057 <span class="comment">** This second example is an SQL syntax error.  As a general rule you should</span>
    2111. 

  2111. <a name="l02058"></a>02058 <span class="comment">** always use %q instead of %s when inserting text into a string literal.</span>
    2112. 

  2112. <a name="l02059"></a>02059 <span class="comment">**</span>
    2113. 

  2113. <a name="l02060"></a>02060 <span class="comment">** ^(The %Q option works like %q except it also adds single quotes around</span>
    2114. 

  2114. <a name="l02061"></a>02061 <span class="comment">** the outside of the total string.  Additionally, if the parameter in the</span>
    2115. 

  2115. <a name="l02062"></a>02062 <span class="comment">** argument list is a NULL pointer, %Q substitutes the text &quot;NULL&quot; (without</span>
    2116. 

  2116. <a name="l02063"></a>02063 <span class="comment">** single quotes).)^  So, for example, one could say:</span>
    2117. 

  2117. <a name="l02064"></a>02064 <span class="comment">**</span>
    2118. 

  2118. <a name="l02065"></a>02065 <span class="comment">** &lt;blockquote&gt;&lt;pre&gt;</span>
    2119. 

  2119. <a name="l02066"></a>02066 <span class="comment">**  char *zSQL = sqlite3_mprintf(&quot;INSERT INTO table VALUES(%Q)&quot;, zText);</span>
    2120. 

  2120. <a name="l02067"></a>02067 <span class="comment">**  sqlite3_exec(db, zSQL, 0, 0, 0);</span>
    2121. 

  2121. <a name="l02068"></a>02068 <span class="comment">**  sqlite3_free(zSQL);</span>
    2122. 

  2122. <a name="l02069"></a>02069 <span class="comment">** &lt;/pre&gt;&lt;/blockquote&gt;</span>
    2123. 

  2123. <a name="l02070"></a>02070 <span class="comment">**</span>
    2124. 

  2124. <a name="l02071"></a>02071 <span class="comment">** The code above will render a correct SQL statement in the zSQL</span>
    2125. 

  2125. <a name="l02072"></a>02072 <span class="comment">** variable even if the zText variable is a NULL pointer.</span>
    2126. 

  2126. <a name="l02073"></a>02073 <span class="comment">**</span>
    2127. 

  2127. <a name="l02074"></a>02074 <span class="comment">** ^(The &quot;%z&quot; formatting option works like &quot;%s&quot; but with the</span>
    2128. 

  2128. <a name="l02075"></a>02075 <span class="comment">** addition that after the string has been read and copied into</span>
    2129. 

  2129. <a name="l02076"></a>02076 <span class="comment">** the result, [sqlite3_free()] is called on the input string.)^</span>
    2130. 

  2130. <a name="l02077"></a>02077 <span class="comment">*/</span>
    2131. 

  2131. <a name="l02078"></a>02078 SQLITE_API <span class="keywordtype">char</span> *sqlite3_mprintf(<span class="keyword">const</span> <span class="keywordtype">char</span>*,...);
    2132. 

  2132. <a name="l02079"></a>02079 SQLITE_API <span class="keywordtype">char</span> *sqlite3_vmprintf(<span class="keyword">const</span> <span class="keywordtype">char</span>*, va_list);
    2133. 

  2133. <a name="l02080"></a>02080 SQLITE_API <span class="keywordtype">char</span> *sqlite3_snprintf(<span class="keywordtype">int</span>,<span class="keywordtype">char</span>*,<span class="keyword">const</span> <span class="keywordtype">char</span>*, ...);
    2134. 

  2134. <a name="l02081"></a>02081 SQLITE_API <span class="keywordtype">char</span> *sqlite3_vsnprintf(<span class="keywordtype">int</span>,<span class="keywordtype">char</span>*,<span class="keyword">const</span> <span class="keywordtype">char</span>*, va_list);
    2135. 

  2135. <a name="l02082"></a>02082 
    2136. 

  2136. <a name="l02083"></a>02083 <span class="comment">/*</span>
    2137. 

  2137. <a name="l02084"></a>02084 <span class="comment">** CAPI3REF: Memory Allocation Subsystem</span>
    2138. 

  2138. <a name="l02085"></a>02085 <span class="comment">**</span>
    2139. 

  2139. <a name="l02086"></a>02086 <span class="comment">** The SQLite core uses these three routines for all of its own</span>
    2140. 

  2140. <a name="l02087"></a>02087 <span class="comment">** internal memory allocation needs. &quot;Core&quot; in the previous sentence</span>
    2141. 

  2141. <a name="l02088"></a>02088 <span class="comment">** does not include operating-system specific VFS implementation.  The</span>
    2142. 

  2142. <a name="l02089"></a>02089 <span class="comment">** Windows VFS uses native malloc() and free() for some operations.</span>
    2143. 

  2143. <a name="l02090"></a>02090 <span class="comment">**</span>
    2144. 

  2144. <a name="l02091"></a>02091 <span class="comment">** ^The sqlite3_malloc() routine returns a pointer to a block</span>
    2145. 

  2145. <a name="l02092"></a>02092 <span class="comment">** of memory at least N bytes in length, where N is the parameter.</span>
    2146. 

  2146. <a name="l02093"></a>02093 <span class="comment">** ^If sqlite3_malloc() is unable to obtain sufficient free</span>
    2147. 

  2147. <a name="l02094"></a>02094 <span class="comment">** memory, it returns a NULL pointer.  ^If the parameter N to</span>
    2148. 

  2148. <a name="l02095"></a>02095 <span class="comment">** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns</span>
    2149. 

  2149. <a name="l02096"></a>02096 <span class="comment">** a NULL pointer.</span>
    2150. 

  2150. <a name="l02097"></a>02097 <span class="comment">**</span>
    2151. 

  2151. <a name="l02098"></a>02098 <span class="comment">** ^Calling sqlite3_free() with a pointer previously returned</span>
    2152. 

  2152. <a name="l02099"></a>02099 <span class="comment">** by sqlite3_malloc() or sqlite3_realloc() releases that memory so</span>
    2153. 

  2153. <a name="l02100"></a>02100 <span class="comment">** that it might be reused.  ^The sqlite3_free() routine is</span>
    2154. 

  2154. <a name="l02101"></a>02101 <span class="comment">** a no-op if is called with a NULL pointer.  Passing a NULL pointer</span>
    2155. 

  2155. <a name="l02102"></a>02102 <span class="comment">** to sqlite3_free() is harmless.  After being freed, memory</span>
    2156. 

  2156. <a name="l02103"></a>02103 <span class="comment">** should neither be read nor written.  Even reading previously freed</span>
    2157. 

  2157. <a name="l02104"></a>02104 <span class="comment">** memory might result in a segmentation fault or other severe error.</span>
    2158. 

  2158. <a name="l02105"></a>02105 <span class="comment">** Memory corruption, a segmentation fault, or other severe error</span>
    2159. 

  2159. <a name="l02106"></a>02106 <span class="comment">** might result if sqlite3_free() is called with a non-NULL pointer that</span>
    2160. 

  2160. <a name="l02107"></a>02107 <span class="comment">** was not obtained from sqlite3_malloc() or sqlite3_realloc().</span>
    2161. 

  2161. <a name="l02108"></a>02108 <span class="comment">**</span>
    2162. 

  2162. <a name="l02109"></a>02109 <span class="comment">** ^(The sqlite3_realloc() interface attempts to resize a</span>
    2163. 

  2163. <a name="l02110"></a>02110 <span class="comment">** prior memory allocation to be at least N bytes, where N is the</span>
    2164. 

  2164. <a name="l02111"></a>02111 <span class="comment">** second parameter.  The memory allocation to be resized is the first</span>
    2165. 

  2165. <a name="l02112"></a>02112 <span class="comment">** parameter.)^ ^ If the first parameter to sqlite3_realloc()</span>
    2166. 

  2166. <a name="l02113"></a>02113 <span class="comment">** is a NULL pointer then its behavior is identical to calling</span>
    2167. 

  2167. <a name="l02114"></a>02114 <span class="comment">** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().</span>
    2168. 

  2168. <a name="l02115"></a>02115 <span class="comment">** ^If the second parameter to sqlite3_realloc() is zero or</span>
    2169. 

  2169. <a name="l02116"></a>02116 <span class="comment">** negative then the behavior is exactly the same as calling</span>
    2170. 

  2170. <a name="l02117"></a>02117 <span class="comment">** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().</span>
    2171. 

  2171. <a name="l02118"></a>02118 <span class="comment">** ^sqlite3_realloc() returns a pointer to a memory allocation</span>
    2172. 

  2172. <a name="l02119"></a>02119 <span class="comment">** of at least N bytes in size or NULL if sufficient memory is unavailable.</span>
    2173. 

  2173. <a name="l02120"></a>02120 <span class="comment">** ^If M is the size of the prior allocation, then min(N,M) bytes</span>
    2174. 

  2174. <a name="l02121"></a>02121 <span class="comment">** of the prior allocation are copied into the beginning of buffer returned</span>
    2175. 

  2175. <a name="l02122"></a>02122 <span class="comment">** by sqlite3_realloc() and the prior allocation is freed.</span>
    2176. 

  2176. <a name="l02123"></a>02123 <span class="comment">** ^If sqlite3_realloc() returns NULL, then the prior allocation</span>
    2177. 

  2177. <a name="l02124"></a>02124 <span class="comment">** is not freed.</span>
    2178. 

  2178. <a name="l02125"></a>02125 <span class="comment">**</span>
    2179. 

  2179. <a name="l02126"></a>02126 <span class="comment">** ^The memory returned by sqlite3_malloc() and sqlite3_realloc()</span>
    2180. 

  2180. <a name="l02127"></a>02127 <span class="comment">** is always aligned to at least an 8 byte boundary, or to a</span>
    2181. 

  2181. <a name="l02128"></a>02128 <span class="comment">** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time</span>
    2182. 

  2182. <a name="l02129"></a>02129 <span class="comment">** option is used.</span>
    2183. 

  2183. <a name="l02130"></a>02130 <span class="comment">**</span>
    2184. 

  2184. <a name="l02131"></a>02131 <span class="comment">** In SQLite version 3.5.0 and 3.5.1, it was possible to define</span>
    2185. 

  2185. <a name="l02132"></a>02132 <span class="comment">** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in</span>
    2186. 

  2186. <a name="l02133"></a>02133 <span class="comment">** implementation of these routines to be omitted.  That capability</span>
    2187. 

  2187. <a name="l02134"></a>02134 <span class="comment">** is no longer provided.  Only built-in memory allocators can be used.</span>
    2188. 

  2188. <a name="l02135"></a>02135 <span class="comment">**</span>
    2189. 

  2189. <a name="l02136"></a>02136 <span class="comment">** The Windows OS interface layer calls</span>
    2190. 

  2190. <a name="l02137"></a>02137 <span class="comment">** the system malloc() and free() directly when converting</span>
    2191. 

  2191. <a name="l02138"></a>02138 <span class="comment">** filenames between the UTF-8 encoding used by SQLite</span>
    2192. 

  2192. <a name="l02139"></a>02139 <span class="comment">** and whatever filename encoding is used by the particular Windows</span>
    2193. 

  2193. <a name="l02140"></a>02140 <span class="comment">** installation.  Memory allocation errors are detected, but</span>
    2194. 

  2194. <a name="l02141"></a>02141 <span class="comment">** they are reported back as [SQLITE_CANTOPEN] or</span>
    2195. 

  2195. <a name="l02142"></a>02142 <span class="comment">** [SQLITE_IOERR] rather than [SQLITE_NOMEM].</span>
    2196. 

  2196. <a name="l02143"></a>02143 <span class="comment">**</span>
    2197. 

  2197. <a name="l02144"></a>02144 <span class="comment">** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]</span>
    2198. 

  2198. <a name="l02145"></a>02145 <span class="comment">** must be either NULL or else pointers obtained from a prior</span>
    2199. 

  2199. <a name="l02146"></a>02146 <span class="comment">** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have</span>
    2200. 

  2200. <a name="l02147"></a>02147 <span class="comment">** not yet been released.</span>
    2201. 

  2201. <a name="l02148"></a>02148 <span class="comment">**</span>
    2202. 

  2202. <a name="l02149"></a>02149 <span class="comment">** The application must not read or write any part of</span>
    2203. 

  2203. <a name="l02150"></a>02150 <span class="comment">** a block of memory after it has been released using</span>
    2204. 

  2204. <a name="l02151"></a>02151 <span class="comment">** [sqlite3_free()] or [sqlite3_realloc()].</span>
    2205. 

  2205. <a name="l02152"></a>02152 <span class="comment">*/</span>
    2206. 

  2206. <a name="l02153"></a>02153 SQLITE_API <span class="keywordtype">void</span> *sqlite3_malloc(<span class="keywordtype">int</span>);
    2207. 

  2207. <a name="l02154"></a>02154 SQLITE_API <span class="keywordtype">void</span> *sqlite3_realloc(<span class="keywordtype">void</span>*, <span class="keywordtype">int</span>);
    2208. 

  2208. <a name="l02155"></a>02155 SQLITE_API <span class="keywordtype">void</span> sqlite3_free(<span class="keywordtype">void</span>*);
    2209. 

  2209. <a name="l02156"></a>02156 
    2210. 

  2210. <a name="l02157"></a>02157 <span class="comment">/*</span>
    2211. 

  2211. <a name="l02158"></a>02158 <span class="comment">** CAPI3REF: Memory Allocator Statistics</span>
    2212. 

  2212. <a name="l02159"></a>02159 <span class="comment">**</span>
    2213. 

  2213. <a name="l02160"></a>02160 <span class="comment">** SQLite provides these two interfaces for reporting on the status</span>
    2214. 

  2214. <a name="l02161"></a>02161 <span class="comment">** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]</span>
    2215. 

  2215. <a name="l02162"></a>02162 <span class="comment">** routines, which form the built-in memory allocation subsystem.</span>
    2216. 

  2216. <a name="l02163"></a>02163 <span class="comment">**</span>
    2217. 

  2217. <a name="l02164"></a>02164 <span class="comment">** ^The [sqlite3_memory_used()] routine returns the number of bytes</span>
    2218. 

  2218. <a name="l02165"></a>02165 <span class="comment">** of memory currently outstanding (malloced but not freed).</span>
    2219. 

  2219. <a name="l02166"></a>02166 <span class="comment">** ^The [sqlite3_memory_highwater()] routine returns the maximum</span>
    2220. 

  2220. <a name="l02167"></a>02167 <span class="comment">** value of [sqlite3_memory_used()] since the high-water mark</span>
    2221. 

  2221. <a name="l02168"></a>02168 <span class="comment">** was last reset.  ^The values returned by [sqlite3_memory_used()] and</span>
    2222. 

  2222. <a name="l02169"></a>02169 <span class="comment">** [sqlite3_memory_highwater()] include any overhead</span>
    2223. 

  2223. <a name="l02170"></a>02170 <span class="comment">** added by SQLite in its implementation of [sqlite3_malloc()],</span>
    2224. 

  2224. <a name="l02171"></a>02171 <span class="comment">** but not overhead added by the any underlying system library</span>
    2225. 

  2225. <a name="l02172"></a>02172 <span class="comment">** routines that [sqlite3_malloc()] may call.</span>
    2226. 

  2226. <a name="l02173"></a>02173 <span class="comment">**</span>
    2227. 

  2227. <a name="l02174"></a>02174 <span class="comment">** ^The memory high-water mark is reset to the current value of</span>
    2228. 

  2228. <a name="l02175"></a>02175 <span class="comment">** [sqlite3_memory_used()] if and only if the parameter to</span>
    2229. 

  2229. <a name="l02176"></a>02176 <span class="comment">** [sqlite3_memory_highwater()] is true.  ^The value returned</span>
    2230. 

  2230. <a name="l02177"></a>02177 <span class="comment">** by [sqlite3_memory_highwater(1)] is the high-water mark</span>
    2231. 

  2231. <a name="l02178"></a>02178 <span class="comment">** prior to the reset.</span>
    2232. 

  2232. <a name="l02179"></a>02179 <span class="comment">*/</span>
    2233. 

  2233. <a name="l02180"></a>02180 SQLITE_API sqlite3_int64 sqlite3_memory_used(<span class="keywordtype">void</span>);
    2234. 

  2234. <a name="l02181"></a>02181 SQLITE_API sqlite3_int64 sqlite3_memory_highwater(<span class="keywordtype">int</span> resetFlag);
    2235. 

  2235. <a name="l02182"></a>02182 
    2236. 

  2236. <a name="l02183"></a>02183 <span class="comment">/*</span>
    2237. 

  2237. <a name="l02184"></a>02184 <span class="comment">** CAPI3REF: Pseudo-Random Number Generator</span>
    2238. 

  2238. <a name="l02185"></a>02185 <span class="comment">**</span>
    2239. 

  2239. <a name="l02186"></a>02186 <span class="comment">** SQLite contains a high-quality pseudo-random number generator (PRNG) used to</span>
    2240. 

  2240. <a name="l02187"></a>02187 <span class="comment">** select random [ROWID | ROWIDs] when inserting new records into a table that</span>
    2241. 

  2241. <a name="l02188"></a>02188 <span class="comment">** already uses the largest possible [ROWID].  The PRNG is also used for</span>
    2242. 

  2242. <a name="l02189"></a>02189 <span class="comment">** the build-in random() and randomblob() SQL functions.  This interface allows</span>
    2243. 

  2243. <a name="l02190"></a>02190 <span class="comment">** applications to access the same PRNG for other purposes.</span>
    2244. 

  2244. <a name="l02191"></a>02191 <span class="comment">**</span>
    2245. 

  2245. <a name="l02192"></a>02192 <span class="comment">** ^A call to this routine stores N bytes of randomness into buffer P.</span>
    2246. 

  2246. <a name="l02193"></a>02193 <span class="comment">**</span>
    2247. 

  2247. <a name="l02194"></a>02194 <span class="comment">** ^The first time this routine is invoked (either internally or by</span>
    2248. 

  2248. <a name="l02195"></a>02195 <span class="comment">** the application) the PRNG is seeded using randomness obtained</span>
    2249. 

  2249. <a name="l02196"></a>02196 <span class="comment">** from the xRandomness method of the default [sqlite3_vfs] object.</span>
    2250. 

  2250. <a name="l02197"></a>02197 <span class="comment">** ^On all subsequent invocations, the pseudo-randomness is generated</span>
    2251. 

  2251. <a name="l02198"></a>02198 <span class="comment">** internally and without recourse to the [sqlite3_vfs] xRandomness</span>
    2252. 

  2252. <a name="l02199"></a>02199 <span class="comment">** method.</span>
    2253. 

  2253. <a name="l02200"></a>02200 <span class="comment">*/</span>
    2254. 

  2254. <a name="l02201"></a>02201 SQLITE_API <span class="keywordtype">void</span> sqlite3_randomness(<span class="keywordtype">int</span> N, <span class="keywordtype">void</span> *P);
    2255. 

  2255. <a name="l02202"></a>02202 
    2256. 

  2256. <a name="l02203"></a>02203 <span class="comment">/*</span>
    2257. 

  2257. <a name="l02204"></a>02204 <span class="comment">** CAPI3REF: Compile-Time Authorization Callbacks</span>
    2258. 

  2258. <a name="l02205"></a>02205 <span class="comment">**</span>
    2259. 

  2259. <a name="l02206"></a>02206 <span class="comment">** ^This routine registers an authorizer callback with a particular</span>
    2260. 

  2260. <a name="l02207"></a>02207 <span class="comment">** [database connection], supplied in the first argument.</span>
    2261. 

  2261. <a name="l02208"></a>02208 <span class="comment">** ^The authorizer callback is invoked as SQL statements are being compiled</span>
    2262. 

  2262. <a name="l02209"></a>02209 <span class="comment">** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],</span>
    2263. 

  2263. <a name="l02210"></a>02210 <span class="comment">** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()].  ^At various</span>
    2264. 

  2264. <a name="l02211"></a>02211 <span class="comment">** points during the compilation process, as logic is being created</span>
    2265. 

  2265. <a name="l02212"></a>02212 <span class="comment">** to perform various actions, the authorizer callback is invoked to</span>
    2266. 

  2266. <a name="l02213"></a>02213 <span class="comment">** see if those actions are allowed.  ^The authorizer callback should</span>
    2267. 

  2267. <a name="l02214"></a>02214 <span class="comment">** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the</span>
    2268. 

  2268. <a name="l02215"></a>02215 <span class="comment">** specific action but allow the SQL statement to continue to be</span>
    2269. 

  2269. <a name="l02216"></a>02216 <span class="comment">** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be</span>
    2270. 

  2270. <a name="l02217"></a>02217 <span class="comment">** rejected with an error.  ^If the authorizer callback returns</span>
    2271. 

  2271. <a name="l02218"></a>02218 <span class="comment">** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]</span>
    2272. 

  2272. <a name="l02219"></a>02219 <span class="comment">** then the [sqlite3_prepare_v2()] or equivalent call that triggered</span>
    2273. 

  2273. <a name="l02220"></a>02220 <span class="comment">** the authorizer will fail with an error message.</span>
    2274. 

  2274. <a name="l02221"></a>02221 <span class="comment">**</span>
    2275. 

  2275. <a name="l02222"></a>02222 <span class="comment">** When the callback returns [SQLITE_OK], that means the operation</span>
    2276. 

  2276. <a name="l02223"></a>02223 <span class="comment">** requested is ok.  ^When the callback returns [SQLITE_DENY], the</span>
    2277. 

  2277. <a name="l02224"></a>02224 <span class="comment">** [sqlite3_prepare_v2()] or equivalent call that triggered the</span>
    2278. 

  2278. <a name="l02225"></a>02225 <span class="comment">** authorizer will fail with an error message explaining that</span>
    2279. 

  2279. <a name="l02226"></a>02226 <span class="comment">** access is denied. </span>
    2280. 

  2280. <a name="l02227"></a>02227 <span class="comment">**</span>
    2281. 

  2281. <a name="l02228"></a>02228 <span class="comment">** ^The first parameter to the authorizer callback is a copy of the third</span>
    2282. 

  2282. <a name="l02229"></a>02229 <span class="comment">** parameter to the sqlite3_set_authorizer() interface. ^The second parameter</span>
    2283. 

  2283. <a name="l02230"></a>02230 <span class="comment">** to the callback is an integer [SQLITE_COPY | action code] that specifies</span>
    2284. 

  2284. <a name="l02231"></a>02231 <span class="comment">** the particular action to be authorized. ^The third through sixth parameters</span>
    2285. 

  2285. <a name="l02232"></a>02232 <span class="comment">** to the callback are zero-terminated strings that contain additional</span>
    2286. 

  2286. <a name="l02233"></a>02233 <span class="comment">** details about the action to be authorized.</span>
    2287. 

  2287. <a name="l02234"></a>02234 <span class="comment">**</span>
    2288. 

  2288. <a name="l02235"></a>02235 <span class="comment">** ^If the action code is [SQLITE_READ]</span>
    2289. 

  2289. <a name="l02236"></a>02236 <span class="comment">** and the callback returns [SQLITE_IGNORE] then the</span>
    2290. 

  2290. <a name="l02237"></a>02237 <span class="comment">** [prepared statement] statement is constructed to substitute</span>
    2291. 

  2291. <a name="l02238"></a>02238 <span class="comment">** a NULL value in place of the table column that would have</span>
    2292. 

  2292. <a name="l02239"></a>02239 <span class="comment">** been read if [SQLITE_OK] had been returned.  The [SQLITE_IGNORE]</span>
    2293. 

  2293. <a name="l02240"></a>02240 <span class="comment">** return can be used to deny an untrusted user access to individual</span>
    2294. 

  2294. <a name="l02241"></a>02241 <span class="comment">** columns of a table.</span>
    2295. 

  2295. <a name="l02242"></a>02242 <span class="comment">** ^If the action code is [SQLITE_DELETE] and the callback returns</span>
    2296. 

  2296. <a name="l02243"></a>02243 <span class="comment">** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the</span>
    2297. 

  2297. <a name="l02244"></a>02244 <span class="comment">** [truncate optimization] is disabled and all rows are deleted individually.</span>
    2298. 

  2298. <a name="l02245"></a>02245 <span class="comment">**</span>
    2299. 

  2299. <a name="l02246"></a>02246 <span class="comment">** An authorizer is used when [sqlite3_prepare | preparing]</span>
    2300. 

  2300. <a name="l02247"></a>02247 <span class="comment">** SQL statements from an untrusted source, to ensure that the SQL statements</span>
    2301. 

  2301. <a name="l02248"></a>02248 <span class="comment">** do not try to access data they are not allowed to see, or that they do not</span>
    2302. 

  2302. <a name="l02249"></a>02249 <span class="comment">** try to execute malicious statements that damage the database.  For</span>
    2303. 

  2303. <a name="l02250"></a>02250 <span class="comment">** example, an application may allow a user to enter arbitrary</span>
    2304. 

  2304. <a name="l02251"></a>02251 <span class="comment">** SQL queries for evaluation by a database.  But the application does</span>
    2305. 

  2305. <a name="l02252"></a>02252 <span class="comment">** not want the user to be able to make arbitrary changes to the</span>
    2306. 

  2306. <a name="l02253"></a>02253 <span class="comment">** database.  An authorizer could then be put in place while the</span>
    2307. 

  2307. <a name="l02254"></a>02254 <span class="comment">** user-entered SQL is being [sqlite3_prepare | prepared] that</span>
    2308. 

  2308. <a name="l02255"></a>02255 <span class="comment">** disallows everything except [SELECT] statements.</span>
    2309. 

  2309. <a name="l02256"></a>02256 <span class="comment">**</span>
    2310. 

  2310. <a name="l02257"></a>02257 <span class="comment">** Applications that need to process SQL from untrusted sources</span>
    2311. 

  2311. <a name="l02258"></a>02258 <span class="comment">** might also consider lowering resource limits using [sqlite3_limit()]</span>
    2312. 

  2312. <a name="l02259"></a>02259 <span class="comment">** and limiting database size using the [max_page_count] [PRAGMA]</span>
    2313. 

  2313. <a name="l02260"></a>02260 <span class="comment">** in addition to using an authorizer.</span>
    2314. 

  2314. <a name="l02261"></a>02261 <span class="comment">**</span>
    2315. 

  2315. <a name="l02262"></a>02262 <span class="comment">** ^(Only a single authorizer can be in place on a database connection</span>
    2316. 

  2316. <a name="l02263"></a>02263 <span class="comment">** at a time.  Each call to sqlite3_set_authorizer overrides the</span>
    2317. 

  2317. <a name="l02264"></a>02264 <span class="comment">** previous call.)^  ^Disable the authorizer by installing a NULL callback.</span>
    2318. 

  2318. <a name="l02265"></a>02265 <span class="comment">** The authorizer is disabled by default.</span>
    2319. 

  2319. <a name="l02266"></a>02266 <span class="comment">**</span>
    2320. 

  2320. <a name="l02267"></a>02267 <span class="comment">** The authorizer callback must not do anything that will modify</span>
    2321. 

  2321. <a name="l02268"></a>02268 <span class="comment">** the database connection that invoked the authorizer callback.</span>
    2322. 

  2322. <a name="l02269"></a>02269 <span class="comment">** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their</span>
    2323. 

  2323. <a name="l02270"></a>02270 <span class="comment">** database connections for the meaning of &quot;modify&quot; in this paragraph.</span>
    2324. 

  2324. <a name="l02271"></a>02271 <span class="comment">**</span>
    2325. 

  2325. <a name="l02272"></a>02272 <span class="comment">** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the</span>
    2326. 

  2326. <a name="l02273"></a>02273 <span class="comment">** statement might be re-prepared during [sqlite3_step()] due to a </span>
    2327. 

  2327. <a name="l02274"></a>02274 <span class="comment">** schema change.  Hence, the application should ensure that the</span>
    2328. 

  2328. <a name="l02275"></a>02275 <span class="comment">** correct authorizer callback remains in place during the [sqlite3_step()].</span>
    2329. 

  2329. <a name="l02276"></a>02276 <span class="comment">**</span>
    2330. 

  2330. <a name="l02277"></a>02277 <span class="comment">** ^Note that the authorizer callback is invoked only during</span>
    2331. 

  2331. <a name="l02278"></a>02278 <span class="comment">** [sqlite3_prepare()] or its variants.  Authorization is not</span>
    2332. 

  2332. <a name="l02279"></a>02279 <span class="comment">** performed during statement evaluation in [sqlite3_step()], unless</span>
    2333. 

  2333. <a name="l02280"></a>02280 <span class="comment">** as stated in the previous paragraph, sqlite3_step() invokes</span>
    2334. 

  2334. <a name="l02281"></a>02281 <span class="comment">** sqlite3_prepare_v2() to reprepare a statement after a schema change.</span>
    2335. 

  2335. <a name="l02282"></a>02282 <span class="comment">*/</span>
    2336. 

  2336. <a name="l02283"></a>02283 SQLITE_API <span class="keywordtype">int</span> sqlite3_set_authorizer(
    2337. 

  2337. <a name="l02284"></a>02284   <a class="code" href="structsqlite3.html">sqlite3</a>*,
    2338. 

  2338. <a name="l02285"></a>02285   <span class="keywordtype">int</span> (*xAuth)(<span class="keywordtype">void</span>*,<span class="keywordtype">int</span>,<span class="keyword">const</span> <span class="keywordtype">char</span>*,<span class="keyword">const</span> <span class="keywordtype">char</span>*,<span class="keyword">const</span> <span class="keywordtype">char</span>*,<span class="keyword">const</span> <span class="keywordtype">char</span>*),
    2339. 

  2339. <a name="l02286"></a>02286   <span class="keywordtype">void</span> *pUserData
    2340. 

  2340. <a name="l02287"></a>02287 );
    2341. 

  2341. <a name="l02288"></a>02288 
    2342. 

  2342. <a name="l02289"></a>02289 <span class="comment">/*</span>
    2343. 

  2343. <a name="l02290"></a>02290 <span class="comment">** CAPI3REF: Authorizer Return Codes</span>
    2344. 

  2344. <a name="l02291"></a>02291 <span class="comment">**</span>
    2345. 

  2345. <a name="l02292"></a>02292 <span class="comment">** The [sqlite3_set_authorizer | authorizer callback function] must</span>
    2346. 

  2346. <a name="l02293"></a>02293 <span class="comment">** return either [SQLITE_OK] or one of these two constants in order</span>
    2347. 

  2347. <a name="l02294"></a>02294 <span class="comment">** to signal SQLite whether or not the action is permitted.  See the</span>
    2348. 

  2348. <a name="l02295"></a>02295 <span class="comment">** [sqlite3_set_authorizer | authorizer documentation] for additional</span>
    2349. 

  2349. <a name="l02296"></a>02296 <span class="comment">** information.</span>
    2350. 

  2350. <a name="l02297"></a>02297 <span class="comment">**</span>
    2351. 

  2351. <a name="l02298"></a>02298 <span class="comment">** Note that SQLITE_IGNORE is also used as a [SQLITE_ROLLBACK | return code]</span>
    2352. 

  2352. <a name="l02299"></a>02299 <span class="comment">** from the [sqlite3_vtab_on_conflict()] interface.</span>
    2353. 

  2353. <a name="l02300"></a>02300 <span class="comment">*/</span>
    2354. 

  2354. <a name="l02301"></a>02301 <span class="preprocessor">#define SQLITE_DENY   1   </span><span class="comment">/* Abort the SQL statement with an error */</span>
    2355. 

  2355. <a name="l02302"></a>02302 <span class="preprocessor">#define SQLITE_IGNORE 2   </span><span class="comment">/* Don&#39;t allow access, but don&#39;t generate an error */</span>
    2356. 

  2356. <a name="l02303"></a>02303 
    2357. 

  2357. <a name="l02304"></a>02304 <span class="comment">/*</span>
    2358. 

  2358. <a name="l02305"></a>02305 <span class="comment">** CAPI3REF: Authorizer Action Codes</span>
    2359. 

  2359. <a name="l02306"></a>02306 <span class="comment">**</span>
    2360. 

  2360. <a name="l02307"></a>02307 <span class="comment">** The [sqlite3_set_authorizer()] interface registers a callback function</span>
    2361. 

  2361. <a name="l02308"></a>02308 <span class="comment">** that is invoked to authorize certain SQL statement actions.  The</span>
    2362. 

  2362. <a name="l02309"></a>02309 <span class="comment">** second parameter to the callback is an integer code that specifies</span>
    2363. 

  2363. <a name="l02310"></a>02310 <span class="comment">** what action is being authorized.  These are the integer action codes that</span>
    2364. 

  2364. <a name="l02311"></a>02311 <span class="comment">** the authorizer callback may be passed.</span>
    2365. 

  2365. <a name="l02312"></a>02312 <span class="comment">**</span>
    2366. 

  2366. <a name="l02313"></a>02313 <span class="comment">** These action code values signify what kind of operation is to be</span>
    2367. 

  2367. <a name="l02314"></a>02314 <span class="comment">** authorized.  The 3rd and 4th parameters to the authorization</span>
    2368. 

  2368. <a name="l02315"></a>02315 <span class="comment">** callback function will be parameters or NULL depending on which of these</span>
    2369. 

  2369. <a name="l02316"></a>02316 <span class="comment">** codes is used as the second parameter.  ^(The 5th parameter to the</span>
    2370. 

  2370. <a name="l02317"></a>02317 <span class="comment">** authorizer callback is the name of the database (&quot;main&quot;, &quot;temp&quot;,</span>
    2371. 

  2371. <a name="l02318"></a>02318 <span class="comment">** etc.) if applicable.)^  ^The 6th parameter to the authorizer callback</span>
    2372. 

  2372. <a name="l02319"></a>02319 <span class="comment">** is the name of the inner-most trigger or view that is responsible for</span>
    2373. 

  2373. <a name="l02320"></a>02320 <span class="comment">** the access attempt or NULL if this access attempt is directly from</span>
    2374. 

  2374. <a name="l02321"></a>02321 <span class="comment">** top-level SQL code.</span>
    2375. 

  2375. <a name="l02322"></a>02322 <span class="comment">*/</span>
    2376. 

  2376. <a name="l02323"></a>02323 <span class="comment">/******************************************* 3rd ************ 4th ***********/</span>
    2377. 

  2377. <a name="l02324"></a>02324 <span class="preprocessor">#define SQLITE_CREATE_INDEX          1   </span><span class="comment">/* Index Name      Table Name      */</span>
    2378. 

  2378. <a name="l02325"></a>02325 <span class="preprocessor">#define SQLITE_CREATE_TABLE          2   </span><span class="comment">/* Table Name      NULL            */</span>
    2379. 

  2379. <a name="l02326"></a>02326 <span class="preprocessor">#define SQLITE_CREATE_TEMP_INDEX     3   </span><span class="comment">/* Index Name      Table Name      */</span>
    2380. 

  2380. <a name="l02327"></a>02327 <span class="preprocessor">#define SQLITE_CREATE_TEMP_TABLE     4   </span><span class="comment">/* Table Name      NULL            */</span>
    2381. 

  2381. <a name="l02328"></a>02328 <span class="preprocessor">#define SQLITE_CREATE_TEMP_TRIGGER   5   </span><span class="comment">/* Trigger Name    Table Name      */</span>
    2382. 

  2382. <a name="l02329"></a>02329 <span class="preprocessor">#define SQLITE_CREATE_TEMP_VIEW      6   </span><span class="comment">/* View Name       NULL            */</span>
    2383. 

  2383. <a name="l02330"></a>02330 <span class="preprocessor">#define SQLITE_CREATE_TRIGGER        7   </span><span class="comment">/* Trigger Name    Table Name      */</span>
    2384. 

  2384. <a name="l02331"></a>02331 <span class="preprocessor">#define SQLITE_CREATE_VIEW           8   </span><span class="comment">/* View Name       NULL            */</span>
    2385. 

  2385. <a name="l02332"></a>02332 <span class="preprocessor">#define SQLITE_DELETE                9   </span><span class="comment">/* Table Name      NULL            */</span>
    2386. 

  2386. <a name="l02333"></a>02333 <span class="preprocessor">#define SQLITE_DROP_INDEX           10   </span><span class="comment">/* Index Name      Table Name      */</span>
    2387. 

  2387. <a name="l02334"></a>02334 <span class="preprocessor">#define SQLITE_DROP_TABLE           11   </span><span class="comment">/* Table Name      NULL            */</span>
    2388. 

  2388. <a name="l02335"></a>02335 <span class="preprocessor">#define SQLITE_DROP_TEMP_INDEX      12   </span><span class="comment">/* Index Name      Table Name      */</span>
    2389. 

  2389. <a name="l02336"></a>02336 <span class="preprocessor">#define SQLITE_DROP_TEMP_TABLE      13   </span><span class="comment">/* Table Name      NULL            */</span>
    2390. 

  2390. <a name="l02337"></a>02337 <span class="preprocessor">#define SQLITE_DROP_TEMP_TRIGGER    14   </span><span class="comment">/* Trigger Name    Table Name      */</span>
    2391. 

  2391. <a name="l02338"></a>02338 <span class="preprocessor">#define SQLITE_DROP_TEMP_VIEW       15   </span><span class="comment">/* View Name       NULL            */</span>
    2392. 

  2392. <a name="l02339"></a>02339 <span class="preprocessor">#define SQLITE_DROP_TRIGGER         16   </span><span class="comment">/* Trigger Name    Table Name      */</span>
    2393. 

  2393. <a name="l02340"></a>02340 <span class="preprocessor">#define SQLITE_DROP_VIEW            17   </span><span class="comment">/* View Name       NULL            */</span>
    2394. 

  2394. <a name="l02341"></a>02341 <span class="preprocessor">#define SQLITE_INSERT               18   </span><span class="comment">/* Table Name      NULL            */</span>
    2395. 

  2395. <a name="l02342"></a>02342 <span class="preprocessor">#define SQLITE_PRAGMA               19   </span><span class="comment">/* Pragma Name     1st arg or NULL */</span>
    2396. 

  2396. <a name="l02343"></a>02343 <span class="preprocessor">#define SQLITE_READ                 20   </span><span class="comment">/* Table Name      Column Name     */</span>
    2397. 

  2397. <a name="l02344"></a>02344 <span class="preprocessor">#define SQLITE_SELECT               21   </span><span class="comment">/* NULL            NULL            */</span>
    2398. 

  2398. <a name="l02345"></a>02345 <span class="preprocessor">#define SQLITE_TRANSACTION          22   </span><span class="comment">/* Operation       NULL            */</span>
    2399. 

  2399. <a name="l02346"></a>02346 <span class="preprocessor">#define SQLITE_UPDATE               23   </span><span class="comment">/* Table Name      Column Name     */</span>
    2400. 

  2400. <a name="l02347"></a>02347 <span class="preprocessor">#define SQLITE_ATTACH               24   </span><span class="comment">/* Filename        NULL            */</span>
    2401. 

  2401. <a name="l02348"></a>02348 <span class="preprocessor">#define SQLITE_DETACH               25   </span><span class="comment">/* Database Name   NULL            */</span>
    2402. 

  2402. <a name="l02349"></a>02349 <span class="preprocessor">#define SQLITE_ALTER_TABLE          26   </span><span class="comment">/* Database Name   Table Name      */</span>
    2403. 

  2403. <a name="l02350"></a>02350 <span class="preprocessor">#define SQLITE_REINDEX              27   </span><span class="comment">/* Index Name      NULL            */</span>
    2404. 

  2404. <a name="l02351"></a>02351 <span class="preprocessor">#define SQLITE_ANALYZE              28   </span><span class="comment">/* Table Name      NULL            */</span>
    2405. 

  2405. <a name="l02352"></a>02352 <span class="preprocessor">#define SQLITE_CREATE_VTABLE        29   </span><span class="comment">/* Table Name      Module Name     */</span>
    2406. 

  2406. <a name="l02353"></a>02353 <span class="preprocessor">#define SQLITE_DROP_VTABLE          30   </span><span class="comment">/* Table Name      Module Name     */</span>
    2407. 

  2407. <a name="l02354"></a>02354 <span class="preprocessor">#define SQLITE_FUNCTION             31   </span><span class="comment">/* NULL            Function Name   */</span>
    2408. 

  2408. <a name="l02355"></a>02355 <span class="preprocessor">#define SQLITE_SAVEPOINT            32   </span><span class="comment">/* Operation       Savepoint Name  */</span>
    2409. 

  2409. <a name="l02356"></a>02356 <span class="preprocessor">#define SQLITE_COPY                  0   </span><span class="comment">/* No longer used */</span>
    2410. 

  2410. <a name="l02357"></a>02357 
    2411. 

  2411. <a name="l02358"></a>02358 <span class="comment">/*</span>
    2412. 

  2412. <a name="l02359"></a>02359 <span class="comment">** CAPI3REF: Tracing And Profiling Functions</span>
    2413. 

  2413. <a name="l02360"></a>02360 <span class="comment">**</span>
    2414. 

  2414. <a name="l02361"></a>02361 <span class="comment">** These routines register callback functions that can be used for</span>
    2415. 

  2415. <a name="l02362"></a>02362 <span class="comment">** tracing and profiling the execution of SQL statements.</span>
    2416. 

  2416. <a name="l02363"></a>02363 <span class="comment">**</span>
    2417. 

  2417. <a name="l02364"></a>02364 <span class="comment">** ^The callback function registered by sqlite3_trace() is invoked at</span>
    2418. 

  2418. <a name="l02365"></a>02365 <span class="comment">** various times when an SQL statement is being run by [sqlite3_step()].</span>
    2419. 

  2419. <a name="l02366"></a>02366 <span class="comment">** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the</span>
    2420. 

  2420. <a name="l02367"></a>02367 <span class="comment">** SQL statement text as the statement first begins executing.</span>
    2421. 

  2421. <a name="l02368"></a>02368 <span class="comment">** ^(Additional sqlite3_trace() callbacks might occur</span>
    2422. 

  2422. <a name="l02369"></a>02369 <span class="comment">** as each triggered subprogram is entered.  The callbacks for triggers</span>
    2423. 

  2423. <a name="l02370"></a>02370 <span class="comment">** contain a UTF-8 SQL comment that identifies the trigger.)^</span>
    2424. 

  2424. <a name="l02371"></a>02371 <span class="comment">**</span>
    2425. 

  2425. <a name="l02372"></a>02372 <span class="comment">** ^The callback function registered by sqlite3_profile() is invoked</span>
    2426. 

  2426. <a name="l02373"></a>02373 <span class="comment">** as each SQL statement finishes.  ^The profile callback contains</span>
    2427. 

  2427. <a name="l02374"></a>02374 <span class="comment">** the original statement text and an estimate of wall-clock time</span>
    2428. 

  2428. <a name="l02375"></a>02375 <span class="comment">** of how long that statement took to run.  ^The profile callback</span>
    2429. 

  2429. <a name="l02376"></a>02376 <span class="comment">** time is in units of nanoseconds, however the current implementation</span>
    2430. 

  2430. <a name="l02377"></a>02377 <span class="comment">** is only capable of millisecond resolution so the six least significant</span>
    2431. 

  2431. <a name="l02378"></a>02378 <span class="comment">** digits in the time are meaningless.  Future versions of SQLite</span>
    2432. 

  2432. <a name="l02379"></a>02379 <span class="comment">** might provide greater resolution on the profiler callback.  The</span>
    2433. 

  2433. <a name="l02380"></a>02380 <span class="comment">** sqlite3_profile() function is considered experimental and is</span>
    2434. 

  2434. <a name="l02381"></a>02381 <span class="comment">** subject to change in future versions of SQLite.</span>
    2435. 

  2435. <a name="l02382"></a>02382 <span class="comment">*/</span>
    2436. 

  2436. <a name="l02383"></a>02383 SQLITE_API <span class="keywordtype">void</span> *sqlite3_trace(<a class="code" href="structsqlite3.html">sqlite3</a>*, <span class="keywordtype">void</span>(*xTrace)(<span class="keywordtype">void</span>*,<span class="keyword">const</span> <span class="keywordtype">char</span>*), <span class="keywordtype">void</span>*);
    2437. 

  2437. <a name="l02384"></a>02384 SQLITE_API SQLITE_EXPERIMENTAL <span class="keywordtype">void</span> *sqlite3_profile(<a class="code" href="structsqlite3.html">sqlite3</a>*,
    2438. 

  2438. <a name="l02385"></a>02385    <span class="keywordtype">void</span>(*xProfile)(<span class="keywordtype">void</span>*,<span class="keyword">const</span> <span class="keywordtype">char</span>*,sqlite3_uint64), <span class="keywordtype">void</span>*);
    2439. 

  2439. <a name="l02386"></a>02386 
    2440. 

  2440. <a name="l02387"></a>02387 <span class="comment">/*</span>
    2441. 

  2441. <a name="l02388"></a>02388 <span class="comment">** CAPI3REF: Query Progress Callbacks</span>
    2442. 

  2442. <a name="l02389"></a>02389 <span class="comment">**</span>
    2443. 

  2443. <a name="l02390"></a>02390 <span class="comment">** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback</span>
    2444. 

  2444. <a name="l02391"></a>02391 <span class="comment">** function X to be invoked periodically during long running calls to</span>
    2445. 

  2445. <a name="l02392"></a>02392 <span class="comment">** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for</span>
    2446. 

  2446. <a name="l02393"></a>02393 <span class="comment">** database connection D.  An example use for this</span>
    2447. 

  2447. <a name="l02394"></a>02394 <span class="comment">** interface is to keep a GUI updated during a large query.</span>
    2448. 

  2448. <a name="l02395"></a>02395 <span class="comment">**</span>
    2449. 

  2449. <a name="l02396"></a>02396 <span class="comment">** ^The parameter P is passed through as the only parameter to the </span>
    2450. 

  2450. <a name="l02397"></a>02397 <span class="comment">** callback function X.  ^The parameter N is the number of </span>
    2451. 

  2451. <a name="l02398"></a>02398 <span class="comment">** [virtual machine instructions] that are evaluated between successive</span>
    2452. 

  2452. <a name="l02399"></a>02399 <span class="comment">** invocations of the callback X.</span>
    2453. 

  2453. <a name="l02400"></a>02400 <span class="comment">**</span>
    2454. 

  2454. <a name="l02401"></a>02401 <span class="comment">** ^Only a single progress handler may be defined at one time per</span>
    2455. 

  2455. <a name="l02402"></a>02402 <span class="comment">** [database connection]; setting a new progress handler cancels the</span>
    2456. 

  2456. <a name="l02403"></a>02403 <span class="comment">** old one.  ^Setting parameter X to NULL disables the progress handler.</span>
    2457. 

  2457. <a name="l02404"></a>02404 <span class="comment">** ^The progress handler is also disabled by setting N to a value less</span>
    2458. 

  2458. <a name="l02405"></a>02405 <span class="comment">** than 1.</span>
    2459. 

  2459. <a name="l02406"></a>02406 <span class="comment">**</span>
    2460. 

  2460. <a name="l02407"></a>02407 <span class="comment">** ^If the progress callback returns non-zero, the operation is</span>
    2461. 

  2461. <a name="l02408"></a>02408 <span class="comment">** interrupted.  This feature can be used to implement a</span>
    2462. 

  2462. <a name="l02409"></a>02409 <span class="comment">** &quot;Cancel&quot; button on a GUI progress dialog box.</span>
    2463. 

  2463. <a name="l02410"></a>02410 <span class="comment">**</span>
    2464. 

  2464. <a name="l02411"></a>02411 <span class="comment">** The progress handler callback must not do anything that will modify</span>
    2465. 

  2465. <a name="l02412"></a>02412 <span class="comment">** the database connection that invoked the progress handler.</span>
    2466. 

  2466. <a name="l02413"></a>02413 <span class="comment">** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their</span>
    2467. 

  2467. <a name="l02414"></a>02414 <span class="comment">** database connections for the meaning of &quot;modify&quot; in this paragraph.</span>
    2468. 

  2468. <a name="l02415"></a>02415 <span class="comment">**</span>
    2469. 

  2469. <a name="l02416"></a>02416 <span class="comment">*/</span>
    2470. 

  2470. <a name="l02417"></a>02417 SQLITE_API <span class="keywordtype">void</span> sqlite3_progress_handler(<a class="code" href="structsqlite3.html">sqlite3</a>*, <span class="keywordtype">int</span>, <span class="keywordtype">int</span>(*)(<span class="keywordtype">void</span>*), <span class="keywordtype">void</span>*);
    2471. 

  2471. <a name="l02418"></a>02418 
    2472. 

  2472. <a name="l02419"></a>02419 <span class="comment">/*</span>
    2473. 

  2473. <a name="l02420"></a>02420 <span class="comment">** CAPI3REF: Opening A New Database Connection</span>
    2474. 

  2474. <a name="l02421"></a>02421 <span class="comment">**</span>
    2475. 

  2475. <a name="l02422"></a>02422 <span class="comment">** ^These routines open an SQLite database file as specified by the </span>
    2476. 

  2476. <a name="l02423"></a>02423 <span class="comment">** filename argument. ^The filename argument is interpreted as UTF-8 for</span>
    2477. 

  2477. <a name="l02424"></a>02424 <span class="comment">** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte</span>
    2478. 

  2478. <a name="l02425"></a>02425 <span class="comment">** order for sqlite3_open16(). ^(A [database connection] handle is usually</span>
    2479. 

  2479. <a name="l02426"></a>02426 <span class="comment">** returned in *ppDb, even if an error occurs.  The only exception is that</span>
    2480. 

  2480. <a name="l02427"></a>02427 <span class="comment">** if SQLite is unable to allocate memory to hold the [sqlite3] object,</span>
    2481. 

  2481. <a name="l02428"></a>02428 <span class="comment">** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]</span>
    2482. 

  2482. <a name="l02429"></a>02429 <span class="comment">** object.)^ ^(If the database is opened (and/or created) successfully, then</span>
    2483. 

  2483. <a name="l02430"></a>02430 <span class="comment">** [SQLITE_OK] is returned.  Otherwise an [error code] is returned.)^ ^The</span>
    2484. 

  2484. <a name="l02431"></a>02431 <span class="comment">** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain</span>
    2485. 

  2485. <a name="l02432"></a>02432 <span class="comment">** an English language description of the error following a failure of any</span>
    2486. 

  2486. <a name="l02433"></a>02433 <span class="comment">** of the sqlite3_open() routines.</span>
    2487. 

  2487. <a name="l02434"></a>02434 <span class="comment">**</span>
    2488. 

  2488. <a name="l02435"></a>02435 <span class="comment">** ^The default encoding for the database will be UTF-8 if</span>
    2489. 

  2489. <a name="l02436"></a>02436 <span class="comment">** sqlite3_open() or sqlite3_open_v2() is called and</span>
    2490. 

  2490. <a name="l02437"></a>02437 <span class="comment">** UTF-16 in the native byte order if sqlite3_open16() is used.</span>
    2491. 

  2491. <a name="l02438"></a>02438 <span class="comment">**</span>
    2492. 

  2492. <a name="l02439"></a>02439 <span class="comment">** Whether or not an error occurs when it is opened, resources</span>
    2493. 

  2493. <a name="l02440"></a>02440 <span class="comment">** associated with the [database connection] handle should be released by</span>
    2494. 

  2494. <a name="l02441"></a>02441 <span class="comment">** passing it to [sqlite3_close()] when it is no longer required.</span>
    2495. 

  2495. <a name="l02442"></a>02442 <span class="comment">**</span>
    2496. 

  2496. <a name="l02443"></a>02443 <span class="comment">** The sqlite3_open_v2() interface works like sqlite3_open()</span>
    2497. 

  2497. <a name="l02444"></a>02444 <span class="comment">** except that it accepts two additional parameters for additional control</span>
    2498. 

  2498. <a name="l02445"></a>02445 <span class="comment">** over the new database connection.  ^(The flags parameter to</span>
    2499. 

  2499. <a name="l02446"></a>02446 <span class="comment">** sqlite3_open_v2() can take one of</span>
    2500. 

  2500. <a name="l02447"></a>02447 <span class="comment">** the following three values, optionally combined with the </span>
    2501. 

  2501. <a name="l02448"></a>02448 <span class="comment">** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],</span>
    2502. 

  2502. <a name="l02449"></a>02449 <span class="comment">** [SQLITE_OPEN_PRIVATECACHE], and/or [SQLITE_OPEN_URI] flags:)^</span>
    2503. 

  2503. <a name="l02450"></a>02450 <span class="comment">**</span>
    2504. 

  2504. <a name="l02451"></a>02451 <span class="comment">** &lt;dl&gt;</span>
    2505. 

  2505. <a name="l02452"></a>02452 <span class="comment">** ^(&lt;dt&gt;[SQLITE_OPEN_READONLY]&lt;/dt&gt;</span>
    2506. 

  2506. <a name="l02453"></a>02453 <span class="comment">** &lt;dd&gt;The database is opened in read-only mode.  If the database does not</span>
    2507. 

  2507. <a name="l02454"></a>02454 <span class="comment">** already exist, an error is returned.&lt;/dd&gt;)^</span>
    2508. 

  2508. <a name="l02455"></a>02455 <span class="comment">**</span>
    2509. 

  2509. <a name="l02456"></a>02456 <span class="comment">** ^(&lt;dt&gt;[SQLITE_OPEN_READWRITE]&lt;/dt&gt;</span>
    2510. 

  2510. <a name="l02457"></a>02457 <span class="comment">** &lt;dd&gt;The database is opened for reading and writing if possible, or reading</span>
    2511. 

  2511. <a name="l02458"></a>02458 <span class="comment">** only if the file is write protected by the operating system.  In either</span>
    2512. 

  2512. <a name="l02459"></a>02459 <span class="comment">** case the database must already exist, otherwise an error is returned.&lt;/dd&gt;)^</span>
    2513. 

  2513. <a name="l02460"></a>02460 <span class="comment">**</span>
    2514. 

  2514. <a name="l02461"></a>02461 <span class="comment">** ^(&lt;dt&gt;[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]&lt;/dt&gt;</span>
    2515. 

  2515. <a name="l02462"></a>02462 <span class="comment">** &lt;dd&gt;The database is opened for reading and writing, and is created if</span>
    2516. 

  2516. <a name="l02463"></a>02463 <span class="comment">** it does not already exist. This is the behavior that is always used for</span>
    2517. 

  2517. <a name="l02464"></a>02464 <span class="comment">** sqlite3_open() and sqlite3_open16().&lt;/dd&gt;)^</span>
    2518. 

  2518. <a name="l02465"></a>02465 <span class="comment">** &lt;/dl&gt;</span>
    2519. 

  2519. <a name="l02466"></a>02466 <span class="comment">**</span>
    2520. 

  2520. <a name="l02467"></a>02467 <span class="comment">** If the 3rd parameter to sqlite3_open_v2() is not one of the</span>
    2521. 

  2521. <a name="l02468"></a>02468 <span class="comment">** combinations shown above optionally combined with other</span>
    2522. 

  2522. <a name="l02469"></a>02469 <span class="comment">** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]</span>
    2523. 

  2523. <a name="l02470"></a>02470 <span class="comment">** then the behavior is undefined.</span>
    2524. 

  2524. <a name="l02471"></a>02471 <span class="comment">**</span>
    2525. 

  2525. <a name="l02472"></a>02472 <span class="comment">** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection</span>
    2526. 

  2526. <a name="l02473"></a>02473 <span class="comment">** opens in the multi-thread [threading mode] as long as the single-thread</span>
    2527. 

  2527. <a name="l02474"></a>02474 <span class="comment">** mode has not been set at compile-time or start-time.  ^If the</span>
    2528. 

  2528. <a name="l02475"></a>02475 <span class="comment">** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens</span>
    2529. 

  2529. <a name="l02476"></a>02476 <span class="comment">** in the serialized [threading mode] unless single-thread was</span>
    2530. 

  2530. <a name="l02477"></a>02477 <span class="comment">** previously selected at compile-time or start-time.</span>
    2531. 

  2531. <a name="l02478"></a>02478 <span class="comment">** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be</span>
    2532. 

  2532. <a name="l02479"></a>02479 <span class="comment">** eligible to use [shared cache mode], regardless of whether or not shared</span>
    2533. 

  2533. <a name="l02480"></a>02480 <span class="comment">** cache is enabled using [sqlite3_enable_shared_cache()].  ^The</span>
    2534. 

  2534. <a name="l02481"></a>02481 <span class="comment">** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not</span>
    2535. 

  2535. <a name="l02482"></a>02482 <span class="comment">** participate in [shared cache mode] even if it is enabled.</span>
    2536. 

  2536. <a name="l02483"></a>02483 <span class="comment">**</span>
    2537. 

  2537. <a name="l02484"></a>02484 <span class="comment">** ^The fourth parameter to sqlite3_open_v2() is the name of the</span>
    2538. 

  2538. <a name="l02485"></a>02485 <span class="comment">** [sqlite3_vfs] object that defines the operating system interface that</span>
    2539. 

  2539. <a name="l02486"></a>02486 <span class="comment">** the new database connection should use.  ^If the fourth parameter is</span>
    2540. 

  2540. <a name="l02487"></a>02487 <span class="comment">** a NULL pointer then the default [sqlite3_vfs] object is used.</span>
    2541. 

  2541. <a name="l02488"></a>02488 <span class="comment">**</span>
    2542. 

  2542. <a name="l02489"></a>02489 <span class="comment">** ^If the filename is &quot;:memory:&quot;, then a private, temporary in-memory database</span>
    2543. 

  2543. <a name="l02490"></a>02490 <span class="comment">** is created for the connection.  ^This in-memory database will vanish when</span>
    2544. 

  2544. <a name="l02491"></a>02491 <span class="comment">** the database connection is closed.  Future versions of SQLite might</span>
    2545. 

  2545. <a name="l02492"></a>02492 <span class="comment">** make use of additional special filenames that begin with the &quot;:&quot; character.</span>
    2546. 

  2546. <a name="l02493"></a>02493 <span class="comment">** It is recommended that when a database filename actually does begin with</span>
    2547. 

  2547. <a name="l02494"></a>02494 <span class="comment">** a &quot;:&quot; character you should prefix the filename with a pathname such as</span>
    2548. 

  2548. <a name="l02495"></a>02495 <span class="comment">** &quot;./&quot; to avoid ambiguity.</span>
    2549. 

  2549. <a name="l02496"></a>02496 <span class="comment">**</span>
    2550. 

  2550. <a name="l02497"></a>02497 <span class="comment">** ^If the filename is an empty string, then a private, temporary</span>
    2551. 

  2551. <a name="l02498"></a>02498 <span class="comment">** on-disk database will be created.  ^This private database will be</span>
    2552. 

  2552. <a name="l02499"></a>02499 <span class="comment">** automatically deleted as soon as the database connection is closed.</span>
    2553. 

  2553. <a name="l02500"></a>02500 <span class="comment">**</span>
    2554. 

  2554. <a name="l02501"></a>02501 <span class="comment">** [[URI filenames in sqlite3_open()]] &lt;h3&gt;URI Filenames&lt;/h3&gt;</span>
    2555. 

  2555. <a name="l02502"></a>02502 <span class="comment">**</span>
    2556. 

  2556. <a name="l02503"></a>02503 <span class="comment">** ^If [URI filename] interpretation is enabled, and the filename argument</span>
    2557. 

  2557. <a name="l02504"></a>02504 <span class="comment">** begins with &quot;file:&quot;, then the filename is interpreted as a URI. ^URI</span>
    2558. 

  2558. <a name="l02505"></a>02505 <span class="comment">** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is</span>
    2559. 

  2559. <a name="l02506"></a>02506 <span class="comment">** set in the fourth argument to sqlite3_open_v2(), or if it has</span>
    2560. 

  2560. <a name="l02507"></a>02507 <span class="comment">** been enabled globally using the [SQLITE_CONFIG_URI] option with the</span>
    2561. 

  2561. <a name="l02508"></a>02508 <span class="comment">** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.</span>
    2562. 

  2562. <a name="l02509"></a>02509 <span class="comment">** As of SQLite version 3.7.7, URI filename interpretation is turned off</span>
    2563. 

  2563. <a name="l02510"></a>02510 <span class="comment">** by default, but future releases of SQLite might enable URI filename</span>
    2564. 

  2564. <a name="l02511"></a>02511 <span class="comment">** interpretation by default.  See &quot;[URI filenames]&quot; for additional</span>
    2565. 

  2565. <a name="l02512"></a>02512 <span class="comment">** information.</span>
    2566. 

  2566. <a name="l02513"></a>02513 <span class="comment">**</span>
    2567. 

  2567. <a name="l02514"></a>02514 <span class="comment">** URI filenames are parsed according to RFC 3986. ^If the URI contains an</span>
    2568. 

  2568. <a name="l02515"></a>02515 <span class="comment">** authority, then it must be either an empty string or the string </span>
    2569. 

  2569. <a name="l02516"></a>02516 <span class="comment">** &quot;localhost&quot;. ^If the authority is not an empty string or &quot;localhost&quot;, an </span>
    2570. 

  2570. <a name="l02517"></a>02517 <span class="comment">** error is returned to the caller. ^The fragment component of a URI, if </span>
    2571. 

  2571. <a name="l02518"></a>02518 <span class="comment">** present, is ignored.</span>
    2572. 

  2572. <a name="l02519"></a>02519 <span class="comment">**</span>
    2573. 

  2573. <a name="l02520"></a>02520 <span class="comment">** ^SQLite uses the path component of the URI as the name of the disk file</span>
    2574. 

  2574. <a name="l02521"></a>02521 <span class="comment">** which contains the database. ^If the path begins with a &#39;/&#39; character, </span>
    2575. 

  2575. <a name="l02522"></a>02522 <span class="comment">** then it is interpreted as an absolute path. ^If the path does not begin </span>
    2576. 

  2576. <a name="l02523"></a>02523 <span class="comment">** with a &#39;/&#39; (meaning that the authority section is omitted from the URI)</span>
    2577. 

  2577. <a name="l02524"></a>02524 <span class="comment">** then the path is interpreted as a relative path. </span>
    2578. 

  2578. <a name="l02525"></a>02525 <span class="comment">** ^On windows, the first component of an absolute path </span>
    2579. 

  2579. <a name="l02526"></a>02526 <span class="comment">** is a drive specification (e.g. &quot;C:&quot;).</span>
    2580. 

  2580. <a name="l02527"></a>02527 <span class="comment">**</span>
    2581. 

  2581. <a name="l02528"></a>02528 <span class="comment">** [[core URI query parameters]]</span>
    2582. 

  2582. <a name="l02529"></a>02529 <span class="comment">** The query component of a URI may contain parameters that are interpreted</span>
    2583. 

  2583. <a name="l02530"></a>02530 <span class="comment">** either by SQLite itself, or by a [VFS | custom VFS implementation].</span>
    2584. 

  2584. <a name="l02531"></a>02531 <span class="comment">** SQLite interprets the following three query parameters:</span>
    2585. 

  2585. <a name="l02532"></a>02532 <span class="comment">**</span>
    2586. 

  2586. <a name="l02533"></a>02533 <span class="comment">** &lt;ul&gt;</span>
    2587. 

  2587. <a name="l02534"></a>02534 <span class="comment">**   &lt;li&gt; &lt;b&gt;vfs&lt;/b&gt;: ^The &quot;vfs&quot; parameter may be used to specify the name of</span>
    2588. 

  2588. <a name="l02535"></a>02535 <span class="comment">**     a VFS object that provides the operating system interface that should</span>
    2589. 

  2589. <a name="l02536"></a>02536 <span class="comment">**     be used to access the database file on disk. ^If this option is set to</span>
    2590. 

  2590. <a name="l02537"></a>02537 <span class="comment">**     an empty string the default VFS object is used. ^Specifying an unknown</span>
    2591. 

  2591. <a name="l02538"></a>02538 <span class="comment">**     VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is</span>
    2592. 

  2592. <a name="l02539"></a>02539 <span class="comment">**     present, then the VFS specified by the option takes precedence over</span>
    2593. 

  2593. <a name="l02540"></a>02540 <span class="comment">**     the value passed as the fourth parameter to sqlite3_open_v2().</span>
    2594. 

  2594. <a name="l02541"></a>02541 <span class="comment">**</span>
    2595. 

  2595. <a name="l02542"></a>02542 <span class="comment">**   &lt;li&gt; &lt;b&gt;mode&lt;/b&gt;: ^(The mode parameter may be set to either &quot;ro&quot;, &quot;rw&quot; or</span>
    2596. 

  2596. <a name="l02543"></a>02543 <span class="comment">**     &quot;rwc&quot;. Attempting to set it to any other value is an error)^. </span>
    2597. 

  2597. <a name="l02544"></a>02544 <span class="comment">**     ^If &quot;ro&quot; is specified, then the database is opened for read-only </span>
    2598. 

  2598. <a name="l02545"></a>02545 <span class="comment">**     access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the </span>
    2599. 

  2599. <a name="l02546"></a>02546 <span class="comment">**     third argument to sqlite3_prepare_v2(). ^If the mode option is set to </span>
    2600. 

  2600. <a name="l02547"></a>02547 <span class="comment">**     &quot;rw&quot;, then the database is opened for read-write (but not create) </span>
    2601. 

  2601. <a name="l02548"></a>02548 <span class="comment">**     access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had </span>
    2602. 

  2602. <a name="l02549"></a>02549 <span class="comment">**     been set. ^Value &quot;rwc&quot; is equivalent to setting both </span>
    2603. 

  2603. <a name="l02550"></a>02550 <span class="comment">**     SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If sqlite3_open_v2() is </span>
    2604. 

  2604. <a name="l02551"></a>02551 <span class="comment">**     used, it is an error to specify a value for the mode parameter that is </span>
    2605. 

  2605. <a name="l02552"></a>02552 <span class="comment">**     less restrictive than that specified by the flags passed as the third </span>
    2606. 

  2606. <a name="l02553"></a>02553 <span class="comment">**     parameter.</span>
    2607. 

  2607. <a name="l02554"></a>02554 <span class="comment">**</span>
    2608. 

  2608. <a name="l02555"></a>02555 <span class="comment">**   &lt;li&gt; &lt;b&gt;cache&lt;/b&gt;: ^The cache parameter may be set to either &quot;shared&quot; or</span>
    2609. 

  2609. <a name="l02556"></a>02556 <span class="comment">**     &quot;private&quot;. ^Setting it to &quot;shared&quot; is equivalent to setting the</span>
    2610. 

  2610. <a name="l02557"></a>02557 <span class="comment">**     SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to</span>
    2611. 

  2611. <a name="l02558"></a>02558 <span class="comment">**     sqlite3_open_v2(). ^Setting the cache parameter to &quot;private&quot; is </span>
    2612. 

  2612. <a name="l02559"></a>02559 <span class="comment">**     equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.</span>
    2613. 

  2613. <a name="l02560"></a>02560 <span class="comment">**     ^If sqlite3_open_v2() is used and the &quot;cache&quot; parameter is present in</span>
    2614. 

  2614. <a name="l02561"></a>02561 <span class="comment">**     a URI filename, its value overrides any behaviour requested by setting</span>
    2615. 

  2615. <a name="l02562"></a>02562 <span class="comment">**     SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.</span>
    2616. 

  2616. <a name="l02563"></a>02563 <span class="comment">** &lt;/ul&gt;</span>
    2617. 

  2617. <a name="l02564"></a>02564 <span class="comment">**</span>
    2618. 

  2618. <a name="l02565"></a>02565 <span class="comment">** ^Specifying an unknown parameter in the query component of a URI is not an</span>
    2619. 

  2619. <a name="l02566"></a>02566 <span class="comment">** error.  Future versions of SQLite might understand additional query</span>
    2620. 

  2620. <a name="l02567"></a>02567 <span class="comment">** parameters.  See &quot;[query parameters with special meaning to SQLite]&quot; for</span>
    2621. 

  2621. <a name="l02568"></a>02568 <span class="comment">** additional information.</span>
    2622. 

  2622. <a name="l02569"></a>02569 <span class="comment">**</span>
    2623. 

  2623. <a name="l02570"></a>02570 <span class="comment">** [[URI filename examples]] &lt;h3&gt;URI filename examples&lt;/h3&gt;</span>
    2624. 

  2624. <a name="l02571"></a>02571 <span class="comment">**</span>
    2625. 

  2625. <a name="l02572"></a>02572 <span class="comment">** &lt;table border=&quot;1&quot; align=center cellpadding=5&gt;</span>
    2626. 

  2626. <a name="l02573"></a>02573 <span class="comment">** &lt;tr&gt;&lt;th&gt; URI filenames &lt;th&gt; Results</span>
    2627. 

  2627. <a name="l02574"></a>02574 <span class="comment">** &lt;tr&gt;&lt;td&gt; file:data.db &lt;td&gt; </span>
    2628. 

  2628. <a name="l02575"></a>02575 <span class="comment">**          Open the file &quot;data.db&quot; in the current directory.</span>
    2629. 

  2629. <a name="l02576"></a>02576 <span class="comment">** &lt;tr&gt;&lt;td&gt; file:/home/fred/data.db&lt;br&gt;</span>
    2630. 

  2630. <a name="l02577"></a>02577 <span class="comment">**          file:///home/fred/data.db &lt;br&gt; </span>
    2631. 

  2631. <a name="l02578"></a>02578 <span class="comment">**          file://localhost/home/fred/data.db &lt;br&gt; &lt;td&gt; </span>
    2632. 

  2632. <a name="l02579"></a>02579 <span class="comment">**          Open the database file &quot;/home/fred/data.db&quot;.</span>
    2633. 

  2633. <a name="l02580"></a>02580 <span class="comment">** &lt;tr&gt;&lt;td&gt; file://darkstar/home/fred/data.db &lt;td&gt; </span>
    2634. 

  2634. <a name="l02581"></a>02581 <span class="comment">**          An error. &quot;darkstar&quot; is not a recognized authority.</span>
    2635. 

  2635. <a name="l02582"></a>02582 <span class="comment">** &lt;tr&gt;&lt;td style=&quot;white-space:nowrap&quot;&gt; </span>
    2636. 

  2636. <a name="l02583"></a>02583 <span class="comment">**          file:///C:/Documents%20and%20Settings/fred/Desktop/data.db</span>
    2637. 

  2637. <a name="l02584"></a>02584 <span class="comment">**     &lt;td&gt; Windows only: Open the file &quot;data.db&quot; on fred&#39;s desktop on drive</span>
    2638. 

  2638. <a name="l02585"></a>02585 <span class="comment">**          C:. Note that the %20 escaping in this example is not strictly </span>
    2639. 

  2639. <a name="l02586"></a>02586 <span class="comment">**          necessary - space characters can be used literally</span>
    2640. 

  2640. <a name="l02587"></a>02587 <span class="comment">**          in URI filenames.</span>
    2641. 

  2641. <a name="l02588"></a>02588 <span class="comment">** &lt;tr&gt;&lt;td&gt; file:data.db?mode=ro&amp;cache=private &lt;td&gt; </span>
    2642. 

  2642. <a name="l02589"></a>02589 <span class="comment">**          Open file &quot;data.db&quot; in the current directory for read-only access.</span>
    2643. 

  2643. <a name="l02590"></a>02590 <span class="comment">**          Regardless of whether or not shared-cache mode is enabled by</span>
    2644. 

  2644. <a name="l02591"></a>02591 <span class="comment">**          default, use a private cache.</span>
    2645. 

  2645. <a name="l02592"></a>02592 <span class="comment">** &lt;tr&gt;&lt;td&gt; file:/home/fred/data.db?vfs=unix-nolock &lt;td&gt;</span>
    2646. 

  2646. <a name="l02593"></a>02593 <span class="comment">**          Open file &quot;/home/fred/data.db&quot;. Use the special VFS &quot;unix-nolock&quot;.</span>
    2647. 

  2647. <a name="l02594"></a>02594 <span class="comment">** &lt;tr&gt;&lt;td&gt; file:data.db?mode=readonly &lt;td&gt; </span>
    2648. 

  2648. <a name="l02595"></a>02595 <span class="comment">**          An error. &quot;readonly&quot; is not a valid option for the &quot;mode&quot; parameter.</span>
    2649. 

  2649. <a name="l02596"></a>02596 <span class="comment">** &lt;/table&gt;</span>
    2650. 

  2650. <a name="l02597"></a>02597 <span class="comment">**</span>
    2651. 

  2651. <a name="l02598"></a>02598 <span class="comment">** ^URI hexadecimal escape sequences (%HH) are supported within the path and</span>
    2652. 

  2652. <a name="l02599"></a>02599 <span class="comment">** query components of a URI. A hexadecimal escape sequence consists of a</span>
    2653. 

  2653. <a name="l02600"></a>02600 <span class="comment">** percent sign - &quot;%&quot; - followed by exactly two hexadecimal digits </span>
    2654. 

  2654. <a name="l02601"></a>02601 <span class="comment">** specifying an octet value. ^Before the path or query components of a</span>
    2655. 

  2655. <a name="l02602"></a>02602 <span class="comment">** URI filename are interpreted, they are encoded using UTF-8 and all </span>
    2656. 

  2656. <a name="l02603"></a>02603 <span class="comment">** hexadecimal escape sequences replaced by a single byte containing the</span>
    2657. 

  2657. <a name="l02604"></a>02604 <span class="comment">** corresponding octet. If this process generates an invalid UTF-8 encoding,</span>
    2658. 

  2658. <a name="l02605"></a>02605 <span class="comment">** the results are undefined.</span>
    2659. 

  2659. <a name="l02606"></a>02606 <span class="comment">**</span>
    2660. 

  2660. <a name="l02607"></a>02607 <span class="comment">** &lt;b&gt;Note to Windows users:&lt;/b&gt;  The encoding used for the filename argument</span>
    2661. 

  2661. <a name="l02608"></a>02608 <span class="comment">** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever</span>
    2662. 

  2662. <a name="l02609"></a>02609 <span class="comment">** codepage is currently defined.  Filenames containing international</span>
    2663. 

  2663. <a name="l02610"></a>02610 <span class="comment">** characters must be converted to UTF-8 prior to passing them into</span>
    2664. 

  2664. <a name="l02611"></a>02611 <span class="comment">** sqlite3_open() or sqlite3_open_v2().</span>
    2665. 

  2665. <a name="l02612"></a>02612 <span class="comment">*/</span>
    2666. 

  2666. <a name="l02613"></a>02613 SQLITE_API <span class="keywordtype">int</span> sqlite3_open(
    2667. 

  2667. <a name="l02614"></a>02614   <span class="keyword">const</span> <span class="keywordtype">char</span> *filename,   <span class="comment">/* Database filename (UTF-8) */</span>
    2668. 

  2668. <a name="l02615"></a>02615   <a class="code" href="structsqlite3.html">sqlite3</a> **ppDb          <span class="comment">/* OUT: SQLite db handle */</span>
    2669. 

  2669. <a name="l02616"></a>02616 );
    2670. 

  2670. <a name="l02617"></a>02617 SQLITE_API <span class="keywordtype">int</span> sqlite3_open16(
    2671. 

  2671. <a name="l02618"></a>02618   <span class="keyword">const</span> <span class="keywordtype">void</span> *filename,   <span class="comment">/* Database filename (UTF-16) */</span>
    2672. 

  2672. <a name="l02619"></a>02619   <a class="code" href="structsqlite3.html">sqlite3</a> **ppDb          <span class="comment">/* OUT: SQLite db handle */</span>
    2673. 

  2673. <a name="l02620"></a>02620 );
    2674. 

  2674. <a name="l02621"></a>02621 SQLITE_API <span class="keywordtype">int</span> sqlite3_open_v2(
    2675. 

  2675. <a name="l02622"></a>02622   <span class="keyword">const</span> <span class="keywordtype">char</span> *filename,   <span class="comment">/* Database filename (UTF-8) */</span>
    2676. 

  2676. <a name="l02623"></a>02623   <a class="code" href="structsqlite3.html">sqlite3</a> **ppDb,         <span class="comment">/* OUT: SQLite db handle */</span>
    2677. 

  2677. <a name="l02624"></a>02624   <span class="keywordtype">int</span> flags,              <span class="comment">/* Flags */</span>
    2678. 

  2678. <a name="l02625"></a>02625   <span class="keyword">const</span> <span class="keywordtype">char</span> *zVfs        <span class="comment">/* Name of VFS module to use */</span>
    2679. 

  2679. <a name="l02626"></a>02626 );
    2680. 

  2680. <a name="l02627"></a>02627 
    2681. 

  2681. <a name="l02628"></a>02628 <span class="comment">/*</span>
    2682. 

  2682. <a name="l02629"></a>02629 <span class="comment">** CAPI3REF: Obtain Values For URI Parameters</span>
    2683. 

  2683. <a name="l02630"></a>02630 <span class="comment">**</span>
    2684. 

  2684. <a name="l02631"></a>02631 <span class="comment">** These are utility routines, useful to VFS implementations, that check</span>
    2685. 

  2685. <a name="l02632"></a>02632 <span class="comment">** to see if a database file was a URI that contained a specific query </span>
    2686. 

  2686. <a name="l02633"></a>02633 <span class="comment">** parameter, and if so obtains the value of that query parameter.</span>
    2687. 

  2687. <a name="l02634"></a>02634 <span class="comment">**</span>
    2688. 

  2688. <a name="l02635"></a>02635 <span class="comment">** If F is the database filename pointer passed into the xOpen() method of </span>
    2689. 

  2689. <a name="l02636"></a>02636 <span class="comment">** a VFS implementation when the flags parameter to xOpen() has one or </span>
    2690. 

  2690. <a name="l02637"></a>02637 <span class="comment">** more of the [SQLITE_OPEN_URI] or [SQLITE_OPEN_MAIN_DB] bits set and</span>
    2691. 

  2691. <a name="l02638"></a>02638 <span class="comment">** P is the name of the query parameter, then</span>
    2692. 

  2692. <a name="l02639"></a>02639 <span class="comment">** sqlite3_uri_parameter(F,P) returns the value of the P</span>
    2693. 

  2693. <a name="l02640"></a>02640 <span class="comment">** parameter if it exists or a NULL pointer if P does not appear as a </span>
    2694. 

  2694. <a name="l02641"></a>02641 <span class="comment">** query parameter on F.  If P is a query parameter of F</span>
    2695. 

  2695. <a name="l02642"></a>02642 <span class="comment">** has no explicit value, then sqlite3_uri_parameter(F,P) returns</span>
    2696. 

  2696. <a name="l02643"></a>02643 <span class="comment">** a pointer to an empty string.</span>
    2697. 

  2697. <a name="l02644"></a>02644 <span class="comment">**</span>
    2698. 

  2698. <a name="l02645"></a>02645 <span class="comment">** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean</span>
    2699. 

  2699. <a name="l02646"></a>02646 <span class="comment">** parameter and returns true (1) or false (0) according to the value</span>
    2700. 

  2700. <a name="l02647"></a>02647 <span class="comment">** of P.  The value of P is true if it is &quot;yes&quot; or &quot;true&quot; or &quot;on&quot; or </span>
    2701. 

  2701. <a name="l02648"></a>02648 <span class="comment">** a non-zero number and is false otherwise.  If P is not a query parameter</span>
    2702. 

  2702. <a name="l02649"></a>02649 <span class="comment">** on F then sqlite3_uri_boolean(F,P,B) returns (B!=0).</span>
    2703. 

  2703. <a name="l02650"></a>02650 <span class="comment">**</span>
    2704. 

  2704. <a name="l02651"></a>02651 <span class="comment">** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a</span>
    2705. 

  2705. <a name="l02652"></a>02652 <span class="comment">** 64-bit signed integer and returns that integer, or D if P does not</span>
    2706. 

  2706. <a name="l02653"></a>02653 <span class="comment">** exist.  If the value of P is something other than an integer, then</span>
    2707. 

  2707. <a name="l02654"></a>02654 <span class="comment">** zero is returned.</span>
    2708. 

  2708. <a name="l02655"></a>02655 <span class="comment">** </span>
    2709. 

  2709. <a name="l02656"></a>02656 <span class="comment">** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and</span>
    2710. 

  2710. <a name="l02657"></a>02657 <span class="comment">** sqlite3_uri_boolean(F,P,B) returns B.  If F is not a NULL pointer and</span>
    2711. 

  2711. <a name="l02658"></a>02658 <span class="comment">** is not a database file pathname pointer that SQLite passed into the xOpen</span>
    2712. 

  2712. <a name="l02659"></a>02659 <span class="comment">** VFS method, then the behavior of this routine is undefined and probably</span>
    2713. 

  2713. <a name="l02660"></a>02660 <span class="comment">** undesirable.</span>
    2714. 

  2714. <a name="l02661"></a>02661 <span class="comment">*/</span>
    2715. 

  2715. <a name="l02662"></a>02662 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">char</span> *sqlite3_uri_parameter(<span class="keyword">const</span> <span class="keywordtype">char</span> *zFilename, <span class="keyword">const</span> <span class="keywordtype">char</span> *zParam);
    2716. 

  2716. <a name="l02663"></a>02663 SQLITE_API <span class="keywordtype">int</span> sqlite3_uri_boolean(<span class="keyword">const</span> <span class="keywordtype">char</span> *zFile, <span class="keyword">const</span> <span class="keywordtype">char</span> *zParam, <span class="keywordtype">int</span> bDefault);
    2717. 

  2717. <a name="l02664"></a>02664 SQLITE_API sqlite3_int64 sqlite3_uri_int64(<span class="keyword">const</span> <span class="keywordtype">char</span>*, <span class="keyword">const</span> <span class="keywordtype">char</span>*, sqlite3_int64);
    2718. 

  2718. <a name="l02665"></a>02665 
    2719. 

  2719. <a name="l02666"></a>02666 
    2720. 

  2720. <a name="l02667"></a>02667 <span class="comment">/*</span>
    2721. 

  2721. <a name="l02668"></a>02668 <span class="comment">** CAPI3REF: Error Codes And Messages</span>
    2722. 

  2722. <a name="l02669"></a>02669 <span class="comment">**</span>
    2723. 

  2723. <a name="l02670"></a>02670 <span class="comment">** ^The sqlite3_errcode() interface returns the numeric [result code] or</span>
    2724. 

  2724. <a name="l02671"></a>02671 <span class="comment">** [extended result code] for the most recent failed sqlite3_* API call</span>
    2725. 

  2725. <a name="l02672"></a>02672 <span class="comment">** associated with a [database connection]. If a prior API call failed</span>
    2726. 

  2726. <a name="l02673"></a>02673 <span class="comment">** but the most recent API call succeeded, the return value from</span>
    2727. 

  2727. <a name="l02674"></a>02674 <span class="comment">** sqlite3_errcode() is undefined.  ^The sqlite3_extended_errcode()</span>
    2728. 

  2728. <a name="l02675"></a>02675 <span class="comment">** interface is the same except that it always returns the </span>
    2729. 

  2729. <a name="l02676"></a>02676 <span class="comment">** [extended result code] even when extended result codes are</span>
    2730. 

  2730. <a name="l02677"></a>02677 <span class="comment">** disabled.</span>
    2731. 

  2731. <a name="l02678"></a>02678 <span class="comment">**</span>
    2732. 

  2732. <a name="l02679"></a>02679 <span class="comment">** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language</span>
    2733. 

  2733. <a name="l02680"></a>02680 <span class="comment">** text that describes the error, as either UTF-8 or UTF-16 respectively.</span>
    2734. 

  2734. <a name="l02681"></a>02681 <span class="comment">** ^(Memory to hold the error message string is managed internally.</span>
    2735. 

  2735. <a name="l02682"></a>02682 <span class="comment">** The application does not need to worry about freeing the result.</span>
    2736. 

  2736. <a name="l02683"></a>02683 <span class="comment">** However, the error string might be overwritten or deallocated by</span>
    2737. 

  2737. <a name="l02684"></a>02684 <span class="comment">** subsequent calls to other SQLite interface functions.)^</span>
    2738. 

  2738. <a name="l02685"></a>02685 <span class="comment">**</span>
    2739. 

  2739. <a name="l02686"></a>02686 <span class="comment">** When the serialized [threading mode] is in use, it might be the</span>
    2740. 

  2740. <a name="l02687"></a>02687 <span class="comment">** case that a second error occurs on a separate thread in between</span>
    2741. 

  2741. <a name="l02688"></a>02688 <span class="comment">** the time of the first error and the call to these interfaces.</span>
    2742. 

  2742. <a name="l02689"></a>02689 <span class="comment">** When that happens, the second error will be reported since these</span>
    2743. 

  2743. <a name="l02690"></a>02690 <span class="comment">** interfaces always report the most recent result.  To avoid</span>
    2744. 

  2744. <a name="l02691"></a>02691 <span class="comment">** this, each thread can obtain exclusive use of the [database connection] D</span>
    2745. 

  2745. <a name="l02692"></a>02692 <span class="comment">** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning</span>
    2746. 

  2746. <a name="l02693"></a>02693 <span class="comment">** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after</span>
    2747. 

  2747. <a name="l02694"></a>02694 <span class="comment">** all calls to the interfaces listed here are completed.</span>
    2748. 

  2748. <a name="l02695"></a>02695 <span class="comment">**</span>
    2749. 

  2749. <a name="l02696"></a>02696 <span class="comment">** If an interface fails with SQLITE_MISUSE, that means the interface</span>
    2750. 

  2750. <a name="l02697"></a>02697 <span class="comment">** was invoked incorrectly by the application.  In that case, the</span>
    2751. 

  2751. <a name="l02698"></a>02698 <span class="comment">** error code and message may or may not be set.</span>
    2752. 

  2752. <a name="l02699"></a>02699 <span class="comment">*/</span>
    2753. 

  2753. <a name="l02700"></a>02700 SQLITE_API <span class="keywordtype">int</span> sqlite3_errcode(<a class="code" href="structsqlite3.html">sqlite3</a> *db);
    2754. 

  2754. <a name="l02701"></a>02701 SQLITE_API <span class="keywordtype">int</span> sqlite3_extended_errcode(<a class="code" href="structsqlite3.html">sqlite3</a> *db);
    2755. 

  2755. <a name="l02702"></a>02702 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">char</span> *sqlite3_errmsg(<a class="code" href="structsqlite3.html">sqlite3</a>*);
    2756. 

  2756. <a name="l02703"></a>02703 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">void</span> *sqlite3_errmsg16(<a class="code" href="structsqlite3.html">sqlite3</a>*);
    2757. 

  2757. <a name="l02704"></a>02704 
    2758. 

  2758. <a name="l02705"></a>02705 <span class="comment">/*</span>
    2759. 

  2759. <a name="l02706"></a>02706 <span class="comment">** CAPI3REF: SQL Statement Object</span>
    2760. 

  2760. <a name="l02707"></a>02707 <span class="comment">** KEYWORDS: {prepared statement} {prepared statements}</span>
    2761. 

  2761. <a name="l02708"></a>02708 <span class="comment">**</span>
    2762. 

  2762. <a name="l02709"></a>02709 <span class="comment">** An instance of this object represents a single SQL statement.</span>
    2763. 

  2763. <a name="l02710"></a>02710 <span class="comment">** This object is variously known as a &quot;prepared statement&quot; or a</span>
    2764. 

  2764. <a name="l02711"></a>02711 <span class="comment">** &quot;compiled SQL statement&quot; or simply as a &quot;statement&quot;.</span>
    2765. 

  2765. <a name="l02712"></a>02712 <span class="comment">**</span>
    2766. 

  2766. <a name="l02713"></a>02713 <span class="comment">** The life of a statement object goes something like this:</span>
    2767. 

  2767. <a name="l02714"></a>02714 <span class="comment">**</span>
    2768. 

  2768. <a name="l02715"></a>02715 <span class="comment">** &lt;ol&gt;</span>
    2769. 

  2769. <a name="l02716"></a>02716 <span class="comment">** &lt;li&gt; Create the object using [sqlite3_prepare_v2()] or a related</span>
    2770. 

  2770. <a name="l02717"></a>02717 <span class="comment">**      function.</span>
    2771. 

  2771. <a name="l02718"></a>02718 <span class="comment">** &lt;li&gt; Bind values to [host parameters] using the sqlite3_bind_*()</span>
    2772. 

  2772. <a name="l02719"></a>02719 <span class="comment">**      interfaces.</span>
    2773. 

  2773. <a name="l02720"></a>02720 <span class="comment">** &lt;li&gt; Run the SQL by calling [sqlite3_step()] one or more times.</span>
    2774. 

  2774. <a name="l02721"></a>02721 <span class="comment">** &lt;li&gt; Reset the statement using [sqlite3_reset()] then go back</span>
    2775. 

  2775. <a name="l02722"></a>02722 <span class="comment">**      to step 2.  Do this zero or more times.</span>
    2776. 

  2776. <a name="l02723"></a>02723 <span class="comment">** &lt;li&gt; Destroy the object using [sqlite3_finalize()].</span>
    2777. 

  2777. <a name="l02724"></a>02724 <span class="comment">** &lt;/ol&gt;</span>
    2778. 

  2778. <a name="l02725"></a>02725 <span class="comment">**</span>
    2779. 

  2779. <a name="l02726"></a>02726 <span class="comment">** Refer to documentation on individual methods above for additional</span>
    2780. 

  2780. <a name="l02727"></a>02727 <span class="comment">** information.</span>
    2781. 

  2781. <a name="l02728"></a>02728 <span class="comment">*/</span>
    2782. 

  2782. <a name="l02729"></a>02729 <span class="keyword">typedef</span> <span class="keyword">struct </span>sqlite3_stmt sqlite3_stmt;
    2783. 

  2783. <a name="l02730"></a>02730 
    2784. 

  2784. <a name="l02731"></a>02731 <span class="comment">/*</span>
    2785. 

  2785. <a name="l02732"></a>02732 <span class="comment">** CAPI3REF: Run-time Limits</span>
    2786. 

  2786. <a name="l02733"></a>02733 <span class="comment">**</span>
    2787. 

  2787. <a name="l02734"></a>02734 <span class="comment">** ^(This interface allows the size of various constructs to be limited</span>
    2788. 

  2788. <a name="l02735"></a>02735 <span class="comment">** on a connection by connection basis.  The first parameter is the</span>
    2789. 

  2789. <a name="l02736"></a>02736 <span class="comment">** [database connection] whose limit is to be set or queried.  The</span>
    2790. 

  2790. <a name="l02737"></a>02737 <span class="comment">** second parameter is one of the [limit categories] that define a</span>
    2791. 

  2791. <a name="l02738"></a>02738 <span class="comment">** class of constructs to be size limited.  The third parameter is the</span>
    2792. 

  2792. <a name="l02739"></a>02739 <span class="comment">** new limit for that construct.)^</span>
    2793. 

  2793. <a name="l02740"></a>02740 <span class="comment">**</span>
    2794. 

  2794. <a name="l02741"></a>02741 <span class="comment">** ^If the new limit is a negative number, the limit is unchanged.</span>
    2795. 

  2795. <a name="l02742"></a>02742 <span class="comment">** ^(For each limit category SQLITE_LIMIT_&lt;i&gt;NAME&lt;/i&gt; there is a </span>
    2796. 

  2796. <a name="l02743"></a>02743 <span class="comment">** [limits | hard upper bound]</span>
    2797. 

  2797. <a name="l02744"></a>02744 <span class="comment">** set at compile-time by a C preprocessor macro called</span>
    2798. 

  2798. <a name="l02745"></a>02745 <span class="comment">** [limits | SQLITE_MAX_&lt;i&gt;NAME&lt;/i&gt;].</span>
    2799. 

  2799. <a name="l02746"></a>02746 <span class="comment">** (The &quot;_LIMIT_&quot; in the name is changed to &quot;_MAX_&quot;.))^</span>
    2800. 

  2800. <a name="l02747"></a>02747 <span class="comment">** ^Attempts to increase a limit above its hard upper bound are</span>
    2801. 

  2801. <a name="l02748"></a>02748 <span class="comment">** silently truncated to the hard upper bound.</span>
    2802. 

  2802. <a name="l02749"></a>02749 <span class="comment">**</span>
    2803. 

  2803. <a name="l02750"></a>02750 <span class="comment">** ^Regardless of whether or not the limit was changed, the </span>
    2804. 

  2804. <a name="l02751"></a>02751 <span class="comment">** [sqlite3_limit()] interface returns the prior value of the limit.</span>
    2805. 

  2805. <a name="l02752"></a>02752 <span class="comment">** ^Hence, to find the current value of a limit without changing it,</span>
    2806. 

  2806. <a name="l02753"></a>02753 <span class="comment">** simply invoke this interface with the third parameter set to -1.</span>
    2807. 

  2807. <a name="l02754"></a>02754 <span class="comment">**</span>
    2808. 

  2808. <a name="l02755"></a>02755 <span class="comment">** Run-time limits are intended for use in applications that manage</span>
    2809. 

  2809. <a name="l02756"></a>02756 <span class="comment">** both their own internal database and also databases that are controlled</span>
    2810. 

  2810. <a name="l02757"></a>02757 <span class="comment">** by untrusted external sources.  An example application might be a</span>
    2811. 

  2811. <a name="l02758"></a>02758 <span class="comment">** web browser that has its own databases for storing history and</span>
    2812. 

  2812. <a name="l02759"></a>02759 <span class="comment">** separate databases controlled by JavaScript applications downloaded</span>
    2813. 

  2813. <a name="l02760"></a>02760 <span class="comment">** off the Internet.  The internal databases can be given the</span>
    2814. 

  2814. <a name="l02761"></a>02761 <span class="comment">** large, default limits.  Databases managed by external sources can</span>
    2815. 

  2815. <a name="l02762"></a>02762 <span class="comment">** be given much smaller limits designed to prevent a denial of service</span>
    2816. 

  2816. <a name="l02763"></a>02763 <span class="comment">** attack.  Developers might also want to use the [sqlite3_set_authorizer()]</span>
    2817. 

  2817. <a name="l02764"></a>02764 <span class="comment">** interface to further control untrusted SQL.  The size of the database</span>
    2818. 

  2818. <a name="l02765"></a>02765 <span class="comment">** created by an untrusted script can be contained using the</span>
    2819. 

  2819. <a name="l02766"></a>02766 <span class="comment">** [max_page_count] [PRAGMA].</span>
    2820. 

  2820. <a name="l02767"></a>02767 <span class="comment">**</span>
    2821. 

  2821. <a name="l02768"></a>02768 <span class="comment">** New run-time limit categories may be added in future releases.</span>
    2822. 

  2822. <a name="l02769"></a>02769 <span class="comment">*/</span>
    2823. 

  2823. <a name="l02770"></a>02770 SQLITE_API <span class="keywordtype">int</span> sqlite3_limit(<a class="code" href="structsqlite3.html">sqlite3</a>*, <span class="keywordtype">int</span> <span class="keywordtype">id</span>, <span class="keywordtype">int</span> newVal);
    2824. 

  2824. <a name="l02771"></a>02771 
    2825. 

  2825. <a name="l02772"></a>02772 <span class="comment">/*</span>
    2826. 

  2826. <a name="l02773"></a>02773 <span class="comment">** CAPI3REF: Run-Time Limit Categories</span>
    2827. 

  2827. <a name="l02774"></a>02774 <span class="comment">** KEYWORDS: {limit category} {*limit categories}</span>
    2828. 

  2828. <a name="l02775"></a>02775 <span class="comment">**</span>
    2829. 

  2829. <a name="l02776"></a>02776 <span class="comment">** These constants define various performance limits</span>
    2830. 

  2830. <a name="l02777"></a>02777 <span class="comment">** that can be lowered at run-time using [sqlite3_limit()].</span>
    2831. 

  2831. <a name="l02778"></a>02778 <span class="comment">** The synopsis of the meanings of the various limits is shown below.</span>
    2832. 

  2832. <a name="l02779"></a>02779 <span class="comment">** Additional information is available at [limits | Limits in SQLite].</span>
    2833. 

  2833. <a name="l02780"></a>02780 <span class="comment">**</span>
    2834. 

  2834. <a name="l02781"></a>02781 <span class="comment">** &lt;dl&gt;</span>
    2835. 

  2835. <a name="l02782"></a>02782 <span class="comment">** [[SQLITE_LIMIT_LENGTH]] ^(&lt;dt&gt;SQLITE_LIMIT_LENGTH&lt;/dt&gt;</span>
    2836. 

  2836. <a name="l02783"></a>02783 <span class="comment">** &lt;dd&gt;The maximum size of any string or BLOB or table row, in bytes.&lt;dd&gt;)^</span>
    2837. 

  2837. <a name="l02784"></a>02784 <span class="comment">**</span>
    2838. 

  2838. <a name="l02785"></a>02785 <span class="comment">** [[SQLITE_LIMIT_SQL_LENGTH]] ^(&lt;dt&gt;SQLITE_LIMIT_SQL_LENGTH&lt;/dt&gt;</span>
    2839. 

  2839. <a name="l02786"></a>02786 <span class="comment">** &lt;dd&gt;The maximum length of an SQL statement, in bytes.&lt;/dd&gt;)^</span>
    2840. 

  2840. <a name="l02787"></a>02787 <span class="comment">**</span>
    2841. 

  2841. <a name="l02788"></a>02788 <span class="comment">** [[SQLITE_LIMIT_COLUMN]] ^(&lt;dt&gt;SQLITE_LIMIT_COLUMN&lt;/dt&gt;</span>
    2842. 

  2842. <a name="l02789"></a>02789 <span class="comment">** &lt;dd&gt;The maximum number of columns in a table definition or in the</span>
    2843. 

  2843. <a name="l02790"></a>02790 <span class="comment">** result set of a [SELECT] or the maximum number of columns in an index</span>
    2844. 

  2844. <a name="l02791"></a>02791 <span class="comment">** or in an ORDER BY or GROUP BY clause.&lt;/dd&gt;)^</span>
    2845. 

  2845. <a name="l02792"></a>02792 <span class="comment">**</span>
    2846. 

  2846. <a name="l02793"></a>02793 <span class="comment">** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(&lt;dt&gt;SQLITE_LIMIT_EXPR_DEPTH&lt;/dt&gt;</span>
    2847. 

  2847. <a name="l02794"></a>02794 <span class="comment">** &lt;dd&gt;The maximum depth of the parse tree on any expression.&lt;/dd&gt;)^</span>
    2848. 

  2848. <a name="l02795"></a>02795 <span class="comment">**</span>
    2849. 

  2849. <a name="l02796"></a>02796 <span class="comment">** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(&lt;dt&gt;SQLITE_LIMIT_COMPOUND_SELECT&lt;/dt&gt;</span>
    2850. 

  2850. <a name="l02797"></a>02797 <span class="comment">** &lt;dd&gt;The maximum number of terms in a compound SELECT statement.&lt;/dd&gt;)^</span>
    2851. 

  2851. <a name="l02798"></a>02798 <span class="comment">**</span>
    2852. 

  2852. <a name="l02799"></a>02799 <span class="comment">** [[SQLITE_LIMIT_VDBE_OP]] ^(&lt;dt&gt;SQLITE_LIMIT_VDBE_OP&lt;/dt&gt;</span>
    2853. 

  2853. <a name="l02800"></a>02800 <span class="comment">** &lt;dd&gt;The maximum number of instructions in a virtual machine program</span>
    2854. 

  2854. <a name="l02801"></a>02801 <span class="comment">** used to implement an SQL statement.  This limit is not currently</span>
    2855. 

  2855. <a name="l02802"></a>02802 <span class="comment">** enforced, though that might be added in some future release of</span>
    2856. 

  2856. <a name="l02803"></a>02803 <span class="comment">** SQLite.&lt;/dd&gt;)^</span>
    2857. 

  2857. <a name="l02804"></a>02804 <span class="comment">**</span>
    2858. 

  2858. <a name="l02805"></a>02805 <span class="comment">** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(&lt;dt&gt;SQLITE_LIMIT_FUNCTION_ARG&lt;/dt&gt;</span>
    2859. 

  2859. <a name="l02806"></a>02806 <span class="comment">** &lt;dd&gt;The maximum number of arguments on a function.&lt;/dd&gt;)^</span>
    2860. 

  2860. <a name="l02807"></a>02807 <span class="comment">**</span>
    2861. 

  2861. <a name="l02808"></a>02808 <span class="comment">** [[SQLITE_LIMIT_ATTACHED]] ^(&lt;dt&gt;SQLITE_LIMIT_ATTACHED&lt;/dt&gt;</span>
    2862. 

  2862. <a name="l02809"></a>02809 <span class="comment">** &lt;dd&gt;The maximum number of [ATTACH | attached databases].)^&lt;/dd&gt;</span>
    2863. 

  2863. <a name="l02810"></a>02810 <span class="comment">**</span>
    2864. 

  2864. <a name="l02811"></a>02811 <span class="comment">** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]</span>
    2865. 

  2865. <a name="l02812"></a>02812 <span class="comment">** ^(&lt;dt&gt;SQLITE_LIMIT_LIKE_PATTERN_LENGTH&lt;/dt&gt;</span>
    2866. 

  2866. <a name="l02813"></a>02813 <span class="comment">** &lt;dd&gt;The maximum length of the pattern argument to the [LIKE] or</span>
    2867. 

  2867. <a name="l02814"></a>02814 <span class="comment">** [GLOB] operators.&lt;/dd&gt;)^</span>
    2868. 

  2868. <a name="l02815"></a>02815 <span class="comment">**</span>
    2869. 

  2869. <a name="l02816"></a>02816 <span class="comment">** [[SQLITE_LIMIT_VARIABLE_NUMBER]]</span>
    2870. 

  2870. <a name="l02817"></a>02817 <span class="comment">** ^(&lt;dt&gt;SQLITE_LIMIT_VARIABLE_NUMBER&lt;/dt&gt;</span>
    2871. 

  2871. <a name="l02818"></a>02818 <span class="comment">** &lt;dd&gt;The maximum index number of any [parameter] in an SQL statement.)^</span>
    2872. 

  2872. <a name="l02819"></a>02819 <span class="comment">**</span>
    2873. 

  2873. <a name="l02820"></a>02820 <span class="comment">** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(&lt;dt&gt;SQLITE_LIMIT_TRIGGER_DEPTH&lt;/dt&gt;</span>
    2874. 

  2874. <a name="l02821"></a>02821 <span class="comment">** &lt;dd&gt;The maximum depth of recursion for triggers.&lt;/dd&gt;)^</span>
    2875. 

  2875. <a name="l02822"></a>02822 <span class="comment">** &lt;/dl&gt;</span>
    2876. 

  2876. <a name="l02823"></a>02823 <span class="comment">*/</span>
    2877. 

  2877. <a name="l02824"></a>02824 <span class="preprocessor">#define SQLITE_LIMIT_LENGTH                    0</span>
    2878. 

  2878. <a name="l02825"></a>02825 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LIMIT_SQL_LENGTH                1</span>
    2879. 

  2879. <a name="l02826"></a>02826 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LIMIT_COLUMN                    2</span>
    2880. 

  2880. <a name="l02827"></a>02827 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LIMIT_EXPR_DEPTH                3</span>
    2881. 

  2881. <a name="l02828"></a>02828 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LIMIT_COMPOUND_SELECT           4</span>
    2882. 

  2882. <a name="l02829"></a>02829 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LIMIT_VDBE_OP                   5</span>
    2883. 

  2883. <a name="l02830"></a>02830 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LIMIT_FUNCTION_ARG              6</span>
    2884. 

  2884. <a name="l02831"></a>02831 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LIMIT_ATTACHED                  7</span>
    2885. 

  2885. <a name="l02832"></a>02832 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH       8</span>
    2886. 

  2886. <a name="l02833"></a>02833 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LIMIT_VARIABLE_NUMBER           9</span>
    2887. 

  2887. <a name="l02834"></a>02834 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_LIMIT_TRIGGER_DEPTH            10</span>
    2888. 

  2888. <a name="l02835"></a>02835 <span class="preprocessor"></span>
    2889. 

  2889. <a name="l02836"></a>02836 <span class="comment">/*</span>
    2890. 

  2890. <a name="l02837"></a>02837 <span class="comment">** CAPI3REF: Compiling An SQL Statement</span>
    2891. 

  2891. <a name="l02838"></a>02838 <span class="comment">** KEYWORDS: {SQL statement compiler}</span>
    2892. 

  2892. <a name="l02839"></a>02839 <span class="comment">**</span>
    2893. 

  2893. <a name="l02840"></a>02840 <span class="comment">** To execute an SQL query, it must first be compiled into a byte-code</span>
    2894. 

  2894. <a name="l02841"></a>02841 <span class="comment">** program using one of these routines.</span>
    2895. 

  2895. <a name="l02842"></a>02842 <span class="comment">**</span>
    2896. 

  2896. <a name="l02843"></a>02843 <span class="comment">** The first argument, &quot;db&quot;, is a [database connection] obtained from a</span>
    2897. 

  2897. <a name="l02844"></a>02844 <span class="comment">** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or</span>
    2898. 

  2898. <a name="l02845"></a>02845 <span class="comment">** [sqlite3_open16()].  The database connection must not have been closed.</span>
    2899. 

  2899. <a name="l02846"></a>02846 <span class="comment">**</span>
    2900. 

  2900. <a name="l02847"></a>02847 <span class="comment">** The second argument, &quot;zSql&quot;, is the statement to be compiled, encoded</span>
    2901. 

  2901. <a name="l02848"></a>02848 <span class="comment">** as either UTF-8 or UTF-16.  The sqlite3_prepare() and sqlite3_prepare_v2()</span>
    2902. 

  2902. <a name="l02849"></a>02849 <span class="comment">** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()</span>
    2903. 

  2903. <a name="l02850"></a>02850 <span class="comment">** use UTF-16.</span>
    2904. 

  2904. <a name="l02851"></a>02851 <span class="comment">**</span>
    2905. 

  2905. <a name="l02852"></a>02852 <span class="comment">** ^If the nByte argument is less than zero, then zSql is read up to the</span>
    2906. 

  2906. <a name="l02853"></a>02853 <span class="comment">** first zero terminator. ^If nByte is non-negative, then it is the maximum</span>
    2907. 

  2907. <a name="l02854"></a>02854 <span class="comment">** number of  bytes read from zSql.  ^When nByte is non-negative, the</span>
    2908. 

  2908. <a name="l02855"></a>02855 <span class="comment">** zSql string ends at either the first &#39;\000&#39; or &#39;\u0000&#39; character or</span>
    2909. 

  2909. <a name="l02856"></a>02856 <span class="comment">** the nByte-th byte, whichever comes first. If the caller knows</span>
    2910. 

  2910. <a name="l02857"></a>02857 <span class="comment">** that the supplied string is nul-terminated, then there is a small</span>
    2911. 

  2911. <a name="l02858"></a>02858 <span class="comment">** performance advantage to be gained by passing an nByte parameter that</span>
    2912. 

  2912. <a name="l02859"></a>02859 <span class="comment">** is equal to the number of bytes in the input string &lt;i&gt;including&lt;/i&gt;</span>
    2913. 

  2913. <a name="l02860"></a>02860 <span class="comment">** the nul-terminator bytes as this saves SQLite from having to</span>
    2914. 

  2914. <a name="l02861"></a>02861 <span class="comment">** make a copy of the input string.</span>
    2915. 

  2915. <a name="l02862"></a>02862 <span class="comment">**</span>
    2916. 

  2916. <a name="l02863"></a>02863 <span class="comment">** ^If pzTail is not NULL then *pzTail is made to point to the first byte</span>
    2917. 

  2917. <a name="l02864"></a>02864 <span class="comment">** past the end of the first SQL statement in zSql.  These routines only</span>
    2918. 

  2918. <a name="l02865"></a>02865 <span class="comment">** compile the first statement in zSql, so *pzTail is left pointing to</span>
    2919. 

  2919. <a name="l02866"></a>02866 <span class="comment">** what remains uncompiled.</span>
    2920. 

  2920. <a name="l02867"></a>02867 <span class="comment">**</span>
    2921. 

  2921. <a name="l02868"></a>02868 <span class="comment">** ^*ppStmt is left pointing to a compiled [prepared statement] that can be</span>
    2922. 

  2922. <a name="l02869"></a>02869 <span class="comment">** executed using [sqlite3_step()].  ^If there is an error, *ppStmt is set</span>
    2923. 

  2923. <a name="l02870"></a>02870 <span class="comment">** to NULL.  ^If the input text contains no SQL (if the input is an empty</span>
    2924. 

  2924. <a name="l02871"></a>02871 <span class="comment">** string or a comment) then *ppStmt is set to NULL.</span>
    2925. 

  2925. <a name="l02872"></a>02872 <span class="comment">** The calling procedure is responsible for deleting the compiled</span>
    2926. 

  2926. <a name="l02873"></a>02873 <span class="comment">** SQL statement using [sqlite3_finalize()] after it has finished with it.</span>
    2927. 

  2927. <a name="l02874"></a>02874 <span class="comment">** ppStmt may not be NULL.</span>
    2928. 

  2928. <a name="l02875"></a>02875 <span class="comment">**</span>
    2929. 

  2929. <a name="l02876"></a>02876 <span class="comment">** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];</span>
    2930. 

  2930. <a name="l02877"></a>02877 <span class="comment">** otherwise an [error code] is returned.</span>
    2931. 

  2931. <a name="l02878"></a>02878 <span class="comment">**</span>
    2932. 

  2932. <a name="l02879"></a>02879 <span class="comment">** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are</span>
    2933. 

  2933. <a name="l02880"></a>02880 <span class="comment">** recommended for all new programs. The two older interfaces are retained</span>
    2934. 

  2934. <a name="l02881"></a>02881 <span class="comment">** for backwards compatibility, but their use is discouraged.</span>
    2935. 

  2935. <a name="l02882"></a>02882 <span class="comment">** ^In the &quot;v2&quot; interfaces, the prepared statement</span>
    2936. 

  2936. <a name="l02883"></a>02883 <span class="comment">** that is returned (the [sqlite3_stmt] object) contains a copy of the</span>
    2937. 

  2937. <a name="l02884"></a>02884 <span class="comment">** original SQL text. This causes the [sqlite3_step()] interface to</span>
    2938. 

  2938. <a name="l02885"></a>02885 <span class="comment">** behave differently in three ways:</span>
    2939. 

  2939. <a name="l02886"></a>02886 <span class="comment">**</span>
    2940. 

  2940. <a name="l02887"></a>02887 <span class="comment">** &lt;ol&gt;</span>
    2941. 

  2941. <a name="l02888"></a>02888 <span class="comment">** &lt;li&gt;</span>
    2942. 

  2942. <a name="l02889"></a>02889 <span class="comment">** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it</span>
    2943. 

  2943. <a name="l02890"></a>02890 <span class="comment">** always used to do, [sqlite3_step()] will automatically recompile the SQL</span>
    2944. 

  2944. <a name="l02891"></a>02891 <span class="comment">** statement and try to run it again.</span>
    2945. 

  2945. <a name="l02892"></a>02892 <span class="comment">** &lt;/li&gt;</span>
    2946. 

  2946. <a name="l02893"></a>02893 <span class="comment">**</span>
    2947. 

  2947. <a name="l02894"></a>02894 <span class="comment">** &lt;li&gt;</span>
    2948. 

  2948. <a name="l02895"></a>02895 <span class="comment">** ^When an error occurs, [sqlite3_step()] will return one of the detailed</span>
    2949. 

  2949. <a name="l02896"></a>02896 <span class="comment">** [error codes] or [extended error codes].  ^The legacy behavior was that</span>
    2950. 

  2950. <a name="l02897"></a>02897 <span class="comment">** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code</span>
    2951. 

  2951. <a name="l02898"></a>02898 <span class="comment">** and the application would have to make a second call to [sqlite3_reset()]</span>
    2952. 

  2952. <a name="l02899"></a>02899 <span class="comment">** in order to find the underlying cause of the problem. With the &quot;v2&quot; prepare</span>
    2953. 

  2953. <a name="l02900"></a>02900 <span class="comment">** interfaces, the underlying reason for the error is returned immediately.</span>
    2954. 

  2954. <a name="l02901"></a>02901 <span class="comment">** &lt;/li&gt;</span>
    2955. 

  2955. <a name="l02902"></a>02902 <span class="comment">**</span>
    2956. 

  2956. <a name="l02903"></a>02903 <span class="comment">** &lt;li&gt;</span>
    2957. 

  2957. <a name="l02904"></a>02904 <span class="comment">** ^If the specific value bound to [parameter | host parameter] in the </span>
    2958. 

  2958. <a name="l02905"></a>02905 <span class="comment">** WHERE clause might influence the choice of query plan for a statement,</span>
    2959. 

  2959. <a name="l02906"></a>02906 <span class="comment">** then the statement will be automatically recompiled, as if there had been </span>
    2960. 

  2960. <a name="l02907"></a>02907 <span class="comment">** a schema change, on the first  [sqlite3_step()] call following any change</span>
    2961. 

  2961. <a name="l02908"></a>02908 <span class="comment">** to the [sqlite3_bind_text | bindings] of that [parameter]. </span>
    2962. 

  2962. <a name="l02909"></a>02909 <span class="comment">** ^The specific value of WHERE-clause [parameter] might influence the </span>
    2963. 

  2963. <a name="l02910"></a>02910 <span class="comment">** choice of query plan if the parameter is the left-hand side of a [LIKE]</span>
    2964. 

  2964. <a name="l02911"></a>02911 <span class="comment">** or [GLOB] operator or if the parameter is compared to an indexed column</span>
    2965. 

  2965. <a name="l02912"></a>02912 <span class="comment">** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled.</span>
    2966. 

  2966. <a name="l02913"></a>02913 <span class="comment">** the </span>
    2967. 

  2967. <a name="l02914"></a>02914 <span class="comment">** &lt;/li&gt;</span>
    2968. 

  2968. <a name="l02915"></a>02915 <span class="comment">** &lt;/ol&gt;</span>
    2969. 

  2969. <a name="l02916"></a>02916 <span class="comment">*/</span>
    2970. 

  2970. <a name="l02917"></a>02917 SQLITE_API <span class="keywordtype">int</span> sqlite3_prepare(
    2971. 

  2971. <a name="l02918"></a>02918   <a class="code" href="structsqlite3.html">sqlite3</a> *db,            <span class="comment">/* Database handle */</span>
    2972. 

  2972. <a name="l02919"></a>02919   <span class="keyword">const</span> <span class="keywordtype">char</span> *zSql,       <span class="comment">/* SQL statement, UTF-8 encoded */</span>
    2973. 

  2973. <a name="l02920"></a>02920   <span class="keywordtype">int</span> nByte,              <span class="comment">/* Maximum length of zSql in bytes. */</span>
    2974. 

  2974. <a name="l02921"></a>02921   sqlite3_stmt **ppStmt,  <span class="comment">/* OUT: Statement handle */</span>
    2975. 

  2975. <a name="l02922"></a>02922   <span class="keyword">const</span> <span class="keywordtype">char</span> **pzTail     <span class="comment">/* OUT: Pointer to unused portion of zSql */</span>
    2976. 

  2976. <a name="l02923"></a>02923 );
    2977. 

  2977. <a name="l02924"></a>02924 SQLITE_API <span class="keywordtype">int</span> sqlite3_prepare_v2(
    2978. 

  2978. <a name="l02925"></a>02925   <a class="code" href="structsqlite3.html">sqlite3</a> *db,            <span class="comment">/* Database handle */</span>
    2979. 

  2979. <a name="l02926"></a>02926   <span class="keyword">const</span> <span class="keywordtype">char</span> *zSql,       <span class="comment">/* SQL statement, UTF-8 encoded */</span>
    2980. 

  2980. <a name="l02927"></a>02927   <span class="keywordtype">int</span> nByte,              <span class="comment">/* Maximum length of zSql in bytes. */</span>
    2981. 

  2981. <a name="l02928"></a>02928   sqlite3_stmt **ppStmt,  <span class="comment">/* OUT: Statement handle */</span>
    2982. 

  2982. <a name="l02929"></a>02929   <span class="keyword">const</span> <span class="keywordtype">char</span> **pzTail     <span class="comment">/* OUT: Pointer to unused portion of zSql */</span>
    2983. 

  2983. <a name="l02930"></a>02930 );
    2984. 

  2984. <a name="l02931"></a>02931 SQLITE_API <span class="keywordtype">int</span> sqlite3_prepare16(
    2985. 

  2985. <a name="l02932"></a>02932   <a class="code" href="structsqlite3.html">sqlite3</a> *db,            <span class="comment">/* Database handle */</span>
    2986. 

  2986. <a name="l02933"></a>02933   <span class="keyword">const</span> <span class="keywordtype">void</span> *zSql,       <span class="comment">/* SQL statement, UTF-16 encoded */</span>
    2987. 

  2987. <a name="l02934"></a>02934   <span class="keywordtype">int</span> nByte,              <span class="comment">/* Maximum length of zSql in bytes. */</span>
    2988. 

  2988. <a name="l02935"></a>02935   sqlite3_stmt **ppStmt,  <span class="comment">/* OUT: Statement handle */</span>
    2989. 

  2989. <a name="l02936"></a>02936   <span class="keyword">const</span> <span class="keywordtype">void</span> **pzTail     <span class="comment">/* OUT: Pointer to unused portion of zSql */</span>
    2990. 

  2990. <a name="l02937"></a>02937 );
    2991. 

  2991. <a name="l02938"></a>02938 SQLITE_API <span class="keywordtype">int</span> sqlite3_prepare16_v2(
    2992. 

  2992. <a name="l02939"></a>02939   <a class="code" href="structsqlite3.html">sqlite3</a> *db,            <span class="comment">/* Database handle */</span>
    2993. 

  2993. <a name="l02940"></a>02940   <span class="keyword">const</span> <span class="keywordtype">void</span> *zSql,       <span class="comment">/* SQL statement, UTF-16 encoded */</span>
    2994. 

  2994. <a name="l02941"></a>02941   <span class="keywordtype">int</span> nByte,              <span class="comment">/* Maximum length of zSql in bytes. */</span>
    2995. 

  2995. <a name="l02942"></a>02942   sqlite3_stmt **ppStmt,  <span class="comment">/* OUT: Statement handle */</span>
    2996. 

  2996. <a name="l02943"></a>02943   <span class="keyword">const</span> <span class="keywordtype">void</span> **pzTail     <span class="comment">/* OUT: Pointer to unused portion of zSql */</span>
    2997. 

  2997. <a name="l02944"></a>02944 );
    2998. 

  2998. <a name="l02945"></a>02945 
    2999. 

  2999. <a name="l02946"></a>02946 <span class="comment">/*</span>
    3000. 

  3000. <a name="l02947"></a>02947 <span class="comment">** CAPI3REF: Retrieving Statement SQL</span>
    3001. 

  3001. <a name="l02948"></a>02948 <span class="comment">**</span>
    3002. 

  3002. <a name="l02949"></a>02949 <span class="comment">** ^This interface can be used to retrieve a saved copy of the original</span>
    3003. 

  3003. <a name="l02950"></a>02950 <span class="comment">** SQL text used to create a [prepared statement] if that statement was</span>
    3004. 

  3004. <a name="l02951"></a>02951 <span class="comment">** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].</span>
    3005. 

  3005. <a name="l02952"></a>02952 <span class="comment">*/</span>
    3006. 

  3006. <a name="l02953"></a>02953 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">char</span> *sqlite3_sql(sqlite3_stmt *pStmt);
    3007. 

  3007. <a name="l02954"></a>02954 
    3008. 

  3008. <a name="l02955"></a>02955 <span class="comment">/*</span>
    3009. 

  3009. <a name="l02956"></a>02956 <span class="comment">** CAPI3REF: Determine If An SQL Statement Writes The Database</span>
    3010. 

  3010. <a name="l02957"></a>02957 <span class="comment">**</span>
    3011. 

  3011. <a name="l02958"></a>02958 <span class="comment">** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if</span>
    3012. 

  3012. <a name="l02959"></a>02959 <span class="comment">** and only if the [prepared statement] X makes no direct changes to</span>
    3013. 

  3013. <a name="l02960"></a>02960 <span class="comment">** the content of the database file.</span>
    3014. 

  3014. <a name="l02961"></a>02961 <span class="comment">**</span>
    3015. 

  3015. <a name="l02962"></a>02962 <span class="comment">** Note that [application-defined SQL functions] or</span>
    3016. 

  3016. <a name="l02963"></a>02963 <span class="comment">** [virtual tables] might change the database indirectly as a side effect.  </span>
    3017. 

  3017. <a name="l02964"></a>02964 <span class="comment">** ^(For example, if an application defines a function &quot;eval()&quot; that </span>
    3018. 

  3018. <a name="l02965"></a>02965 <span class="comment">** calls [sqlite3_exec()], then the following SQL statement would</span>
    3019. 

  3019. <a name="l02966"></a>02966 <span class="comment">** change the database file through side-effects:</span>
    3020. 

  3020. <a name="l02967"></a>02967 <span class="comment">**</span>
    3021. 

  3021. <a name="l02968"></a>02968 <span class="comment">** &lt;blockquote&gt;&lt;pre&gt;</span>
    3022. 

  3022. <a name="l02969"></a>02969 <span class="comment">**    SELECT eval(&#39;DELETE FROM t1&#39;) FROM t2;</span>
    3023. 

  3023. <a name="l02970"></a>02970 <span class="comment">** &lt;/pre&gt;&lt;/blockquote&gt;</span>
    3024. 

  3024. <a name="l02971"></a>02971 <span class="comment">**</span>
    3025. 

  3025. <a name="l02972"></a>02972 <span class="comment">** But because the [SELECT] statement does not change the database file</span>
    3026. 

  3026. <a name="l02973"></a>02973 <span class="comment">** directly, sqlite3_stmt_readonly() would still return true.)^</span>
    3027. 

  3027. <a name="l02974"></a>02974 <span class="comment">**</span>
    3028. 

  3028. <a name="l02975"></a>02975 <span class="comment">** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],</span>
    3029. 

  3029. <a name="l02976"></a>02976 <span class="comment">** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,</span>
    3030. 

  3030. <a name="l02977"></a>02977 <span class="comment">** since the statements themselves do not actually modify the database but</span>
    3031. 

  3031. <a name="l02978"></a>02978 <span class="comment">** rather they control the timing of when other statements modify the </span>
    3032. 

  3032. <a name="l02979"></a>02979 <span class="comment">** database.  ^The [ATTACH] and [DETACH] statements also cause</span>
    3033. 

  3033. <a name="l02980"></a>02980 <span class="comment">** sqlite3_stmt_readonly() to return true since, while those statements</span>
    3034. 

  3034. <a name="l02981"></a>02981 <span class="comment">** change the configuration of a database connection, they do not make </span>
    3035. 

  3035. <a name="l02982"></a>02982 <span class="comment">** changes to the content of the database files on disk.</span>
    3036. 

  3036. <a name="l02983"></a>02983 <span class="comment">*/</span>
    3037. 

  3037. <a name="l02984"></a>02984 SQLITE_API <span class="keywordtype">int</span> sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
    3038. 

  3038. <a name="l02985"></a>02985 
    3039. 

  3039. <a name="l02986"></a>02986 <span class="comment">/*</span>
    3040. 

  3040. <a name="l02987"></a>02987 <span class="comment">** CAPI3REF: Determine If A Prepared Statement Has Been Reset</span>
    3041. 

  3041. <a name="l02988"></a>02988 <span class="comment">**</span>
    3042. 

  3042. <a name="l02989"></a>02989 <span class="comment">** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the</span>
    3043. 

  3043. <a name="l02990"></a>02990 <span class="comment">** [prepared statement] S has been stepped at least once using </span>
    3044. 

  3044. <a name="l02991"></a>02991 <span class="comment">** [sqlite3_step(S)] but has not run to completion and/or has not </span>
    3045. 

  3045. <a name="l02992"></a>02992 <span class="comment">** been reset using [sqlite3_reset(S)].  ^The sqlite3_stmt_busy(S)</span>
    3046. 

  3046. <a name="l02993"></a>02993 <span class="comment">** interface returns false if S is a NULL pointer.  If S is not a </span>
    3047. 

  3047. <a name="l02994"></a>02994 <span class="comment">** NULL pointer and is not a pointer to a valid [prepared statement]</span>
    3048. 

  3048. <a name="l02995"></a>02995 <span class="comment">** object, then the behavior is undefined and probably undesirable.</span>
    3049. 

  3049. <a name="l02996"></a>02996 <span class="comment">**</span>
    3050. 

  3050. <a name="l02997"></a>02997 <span class="comment">** This interface can be used in combination [sqlite3_next_stmt()]</span>
    3051. 

  3051. <a name="l02998"></a>02998 <span class="comment">** to locate all prepared statements associated with a database </span>
    3052. 

  3052. <a name="l02999"></a>02999 <span class="comment">** connection that are in need of being reset.  This can be used,</span>
    3053. 

  3053. <a name="l03000"></a>03000 <span class="comment">** for example, in diagnostic routines to search for prepared </span>
    3054. 

  3054. <a name="l03001"></a>03001 <span class="comment">** statements that are holding a transaction open.</span>
    3055. 

  3055. <a name="l03002"></a>03002 <span class="comment">*/</span>
    3056. 

  3056. <a name="l03003"></a>03003 SQLITE_API <span class="keywordtype">int</span> sqlite3_stmt_busy(sqlite3_stmt*);
    3057. 

  3057. <a name="l03004"></a>03004 
    3058. 

  3058. <a name="l03005"></a>03005 <span class="comment">/*</span>
    3059. 

  3059. <a name="l03006"></a>03006 <span class="comment">** CAPI3REF: Dynamically Typed Value Object</span>
    3060. 

  3060. <a name="l03007"></a>03007 <span class="comment">** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}</span>
    3061. 

  3061. <a name="l03008"></a>03008 <span class="comment">**</span>
    3062. 

  3062. <a name="l03009"></a>03009 <span class="comment">** SQLite uses the sqlite3_value object to represent all values</span>
    3063. 

  3063. <a name="l03010"></a>03010 <span class="comment">** that can be stored in a database table. SQLite uses dynamic typing</span>
    3064. 

  3064. <a name="l03011"></a>03011 <span class="comment">** for the values it stores.  ^Values stored in sqlite3_value objects</span>
    3065. 

  3065. <a name="l03012"></a>03012 <span class="comment">** can be integers, floating point values, strings, BLOBs, or NULL.</span>
    3066. 

  3066. <a name="l03013"></a>03013 <span class="comment">**</span>
    3067. 

  3067. <a name="l03014"></a>03014 <span class="comment">** An sqlite3_value object may be either &quot;protected&quot; or &quot;unprotected&quot;.</span>
    3068. 

  3068. <a name="l03015"></a>03015 <span class="comment">** Some interfaces require a protected sqlite3_value.  Other interfaces</span>
    3069. 

  3069. <a name="l03016"></a>03016 <span class="comment">** will accept either a protected or an unprotected sqlite3_value.</span>
    3070. 

  3070. <a name="l03017"></a>03017 <span class="comment">** Every interface that accepts sqlite3_value arguments specifies</span>
    3071. 

  3071. <a name="l03018"></a>03018 <span class="comment">** whether or not it requires a protected sqlite3_value.</span>
    3072. 

  3072. <a name="l03019"></a>03019 <span class="comment">**</span>
    3073. 

  3073. <a name="l03020"></a>03020 <span class="comment">** The terms &quot;protected&quot; and &quot;unprotected&quot; refer to whether or not</span>
    3074. 

  3074. <a name="l03021"></a>03021 <span class="comment">** a mutex is held.  An internal mutex is held for a protected</span>
    3075. 

  3075. <a name="l03022"></a>03022 <span class="comment">** sqlite3_value object but no mutex is held for an unprotected</span>
    3076. 

  3076. <a name="l03023"></a>03023 <span class="comment">** sqlite3_value object.  If SQLite is compiled to be single-threaded</span>
    3077. 

  3077. <a name="l03024"></a>03024 <span class="comment">** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)</span>
    3078. 

  3078. <a name="l03025"></a>03025 <span class="comment">** or if SQLite is run in one of reduced mutex modes </span>
    3079. 

  3079. <a name="l03026"></a>03026 <span class="comment">** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]</span>
    3080. 

  3080. <a name="l03027"></a>03027 <span class="comment">** then there is no distinction between protected and unprotected</span>
    3081. 

  3081. <a name="l03028"></a>03028 <span class="comment">** sqlite3_value objects and they can be used interchangeably.  However,</span>
    3082. 

  3082. <a name="l03029"></a>03029 <span class="comment">** for maximum code portability it is recommended that applications</span>
    3083. 

  3083. <a name="l03030"></a>03030 <span class="comment">** still make the distinction between protected and unprotected</span>
    3084. 

  3084. <a name="l03031"></a>03031 <span class="comment">** sqlite3_value objects even when not strictly required.</span>
    3085. 

  3085. <a name="l03032"></a>03032 <span class="comment">**</span>
    3086. 

  3086. <a name="l03033"></a>03033 <span class="comment">** ^The sqlite3_value objects that are passed as parameters into the</span>
    3087. 

  3087. <a name="l03034"></a>03034 <span class="comment">** implementation of [application-defined SQL functions] are protected.</span>
    3088. 

  3088. <a name="l03035"></a>03035 <span class="comment">** ^The sqlite3_value object returned by</span>
    3089. 

  3089. <a name="l03036"></a>03036 <span class="comment">** [sqlite3_column_value()] is unprotected.</span>
    3090. 

  3090. <a name="l03037"></a>03037 <span class="comment">** Unprotected sqlite3_value objects may only be used with</span>
    3091. 

  3091. <a name="l03038"></a>03038 <span class="comment">** [sqlite3_result_value()] and [sqlite3_bind_value()].</span>
    3092. 

  3092. <a name="l03039"></a>03039 <span class="comment">** The [sqlite3_value_blob | sqlite3_value_type()] family of</span>
    3093. 

  3093. <a name="l03040"></a>03040 <span class="comment">** interfaces require protected sqlite3_value objects.</span>
    3094. 

  3094. <a name="l03041"></a>03041 <span class="comment">*/</span>
    3095. 

  3095. <a name="l03042"></a>03042 <span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="structMem.html">Mem</a> <a class="code" href="structMem.html">sqlite3_value</a>;
    3096. 

  3096. <a name="l03043"></a>03043 
    3097. 

  3097. <a name="l03044"></a>03044 <span class="comment">/*</span>
    3098. 

  3098. <a name="l03045"></a>03045 <span class="comment">** CAPI3REF: SQL Function Context Object</span>
    3099. 

  3099. <a name="l03046"></a>03046 <span class="comment">**</span>
    3100. 

  3100. <a name="l03047"></a>03047 <span class="comment">** The context in which an SQL function executes is stored in an</span>
    3101. 

  3101. <a name="l03048"></a>03048 <span class="comment">** sqlite3_context object.  ^A pointer to an sqlite3_context object</span>
    3102. 

  3102. <a name="l03049"></a>03049 <span class="comment">** is always first parameter to [application-defined SQL functions].</span>
    3103. 

  3103. <a name="l03050"></a>03050 <span class="comment">** The application-defined SQL function implementation will pass this</span>
    3104. 

  3104. <a name="l03051"></a>03051 <span class="comment">** pointer through into calls to [sqlite3_result_int | sqlite3_result()],</span>
    3105. 

  3105. <a name="l03052"></a>03052 <span class="comment">** [sqlite3_aggregate_context()], [sqlite3_user_data()],</span>
    3106. 

  3106. <a name="l03053"></a>03053 <span class="comment">** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],</span>
    3107. 

  3107. <a name="l03054"></a>03054 <span class="comment">** and/or [sqlite3_set_auxdata()].</span>
    3108. 

  3108. <a name="l03055"></a>03055 <span class="comment">*/</span>
    3109. 

  3109. <a name="l03056"></a>03056 <span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="structsqlite3__context.html">sqlite3_context</a> <a class="code" href="structsqlite3__context.html">sqlite3_context</a>;
    3110. 

  3110. <a name="l03057"></a>03057 
    3111. 

  3111. <a name="l03058"></a>03058 <span class="comment">/*</span>
    3112. 

  3112. <a name="l03059"></a>03059 <span class="comment">** CAPI3REF: Binding Values To Prepared Statements</span>
    3113. 

  3113. <a name="l03060"></a>03060 <span class="comment">** KEYWORDS: {host parameter} {host parameters} {host parameter name}</span>
    3114. 

  3114. <a name="l03061"></a>03061 <span class="comment">** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}</span>
    3115. 

  3115. <a name="l03062"></a>03062 <span class="comment">**</span>
    3116. 

  3116. <a name="l03063"></a>03063 <span class="comment">** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,</span>
    3117. 

  3117. <a name="l03064"></a>03064 <span class="comment">** literals may be replaced by a [parameter] that matches one of following</span>
    3118. 

  3118. <a name="l03065"></a>03065 <span class="comment">** templates:</span>
    3119. 

  3119. <a name="l03066"></a>03066 <span class="comment">**</span>
    3120. 

  3120. <a name="l03067"></a>03067 <span class="comment">** &lt;ul&gt;</span>
    3121. 

  3121. <a name="l03068"></a>03068 <span class="comment">** &lt;li&gt;  ?</span>
    3122. 

  3122. <a name="l03069"></a>03069 <span class="comment">** &lt;li&gt;  ?NNN</span>
    3123. 

  3123. <a name="l03070"></a>03070 <span class="comment">** &lt;li&gt;  :VVV</span>
    3124. 

  3124. <a name="l03071"></a>03071 <span class="comment">** &lt;li&gt;  @VVV</span>
    3125. 

  3125. <a name="l03072"></a>03072 <span class="comment">** &lt;li&gt;  $VVV</span>
    3126. 

  3126. <a name="l03073"></a>03073 <span class="comment">** &lt;/ul&gt;</span>
    3127. 

  3127. <a name="l03074"></a>03074 <span class="comment">**</span>
    3128. 

  3128. <a name="l03075"></a>03075 <span class="comment">** In the templates above, NNN represents an integer literal,</span>
    3129. 

  3129. <a name="l03076"></a>03076 <span class="comment">** and VVV represents an alphanumeric identifier.)^  ^The values of these</span>
    3130. 

  3130. <a name="l03077"></a>03077 <span class="comment">** parameters (also called &quot;host parameter names&quot; or &quot;SQL parameters&quot;)</span>
    3131. 

  3131. <a name="l03078"></a>03078 <span class="comment">** can be set using the sqlite3_bind_*() routines defined here.</span>
    3132. 

  3132. <a name="l03079"></a>03079 <span class="comment">**</span>
    3133. 

  3133. <a name="l03080"></a>03080 <span class="comment">** ^The first argument to the sqlite3_bind_*() routines is always</span>
    3134. 

  3134. <a name="l03081"></a>03081 <span class="comment">** a pointer to the [sqlite3_stmt] object returned from</span>
    3135. 

  3135. <a name="l03082"></a>03082 <span class="comment">** [sqlite3_prepare_v2()] or its variants.</span>
    3136. 

  3136. <a name="l03083"></a>03083 <span class="comment">**</span>
    3137. 

  3137. <a name="l03084"></a>03084 <span class="comment">** ^The second argument is the index of the SQL parameter to be set.</span>
    3138. 

  3138. <a name="l03085"></a>03085 <span class="comment">** ^The leftmost SQL parameter has an index of 1.  ^When the same named</span>
    3139. 

  3139. <a name="l03086"></a>03086 <span class="comment">** SQL parameter is used more than once, second and subsequent</span>
    3140. 

  3140. <a name="l03087"></a>03087 <span class="comment">** occurrences have the same index as the first occurrence.</span>
    3141. 

  3141. <a name="l03088"></a>03088 <span class="comment">** ^The index for named parameters can be looked up using the</span>
    3142. 

  3142. <a name="l03089"></a>03089 <span class="comment">** [sqlite3_bind_parameter_index()] API if desired.  ^The index</span>
    3143. 

  3143. <a name="l03090"></a>03090 <span class="comment">** for &quot;?NNN&quot; parameters is the value of NNN.</span>
    3144. 

  3144. <a name="l03091"></a>03091 <span class="comment">** ^The NNN value must be between 1 and the [sqlite3_limit()]</span>
    3145. 

  3145. <a name="l03092"></a>03092 <span class="comment">** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).</span>
    3146. 

  3146. <a name="l03093"></a>03093 <span class="comment">**</span>
    3147. 

  3147. <a name="l03094"></a>03094 <span class="comment">** ^The third argument is the value to bind to the parameter.</span>
    3148. 

  3148. <a name="l03095"></a>03095 <span class="comment">**</span>
    3149. 

  3149. <a name="l03096"></a>03096 <span class="comment">** ^(In those routines that have a fourth argument, its value is the</span>
    3150. 

  3150. <a name="l03097"></a>03097 <span class="comment">** number of bytes in the parameter.  To be clear: the value is the</span>
    3151. 

  3151. <a name="l03098"></a>03098 <span class="comment">** number of &lt;u&gt;bytes&lt;/u&gt; in the value, not the number of characters.)^</span>
    3152. 

  3152. <a name="l03099"></a>03099 <span class="comment">** ^If the fourth parameter is negative, the length of the string is</span>
    3153. 

  3153. <a name="l03100"></a>03100 <span class="comment">** the number of bytes up to the first zero terminator.</span>
    3154. 

  3154. <a name="l03101"></a>03101 <span class="comment">** If a non-negative fourth parameter is provided to sqlite3_bind_text()</span>
    3155. 

  3155. <a name="l03102"></a>03102 <span class="comment">** or sqlite3_bind_text16() then that parameter must be the byte offset</span>
    3156. 

  3156. <a name="l03103"></a>03103 <span class="comment">** where the NUL terminator would occur assuming the string were NUL</span>
    3157. 

  3157. <a name="l03104"></a>03104 <span class="comment">** terminated.  If any NUL characters occur at byte offsets less than </span>
    3158. 

  3158. <a name="l03105"></a>03105 <span class="comment">** the value of the fourth parameter then the resulting string value will</span>
    3159. 

  3159. <a name="l03106"></a>03106 <span class="comment">** contain embedded NULs.  The result of expressions involving strings</span>
    3160. 

  3160. <a name="l03107"></a>03107 <span class="comment">** with embedded NULs is undefined.</span>
    3161. 

  3161. <a name="l03108"></a>03108 <span class="comment">**</span>
    3162. 

  3162. <a name="l03109"></a>03109 <span class="comment">** ^The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and</span>
    3163. 

  3163. <a name="l03110"></a>03110 <span class="comment">** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or</span>
    3164. 

  3164. <a name="l03111"></a>03111 <span class="comment">** string after SQLite has finished with it.  ^The destructor is called</span>
    3165. 

  3165. <a name="l03112"></a>03112 <span class="comment">** to dispose of the BLOB or string even if the call to sqlite3_bind_blob(),</span>
    3166. 

  3166. <a name="l03113"></a>03113 <span class="comment">** sqlite3_bind_text(), or sqlite3_bind_text16() fails.  </span>
    3167. 

  3167. <a name="l03114"></a>03114 <span class="comment">** ^If the fifth argument is</span>
    3168. 

  3168. <a name="l03115"></a>03115 <span class="comment">** the special value [SQLITE_STATIC], then SQLite assumes that the</span>
    3169. 

  3169. <a name="l03116"></a>03116 <span class="comment">** information is in static, unmanaged space and does not need to be freed.</span>
    3170. 

  3170. <a name="l03117"></a>03117 <span class="comment">** ^If the fifth argument has the value [SQLITE_TRANSIENT], then</span>
    3171. 

  3171. <a name="l03118"></a>03118 <span class="comment">** SQLite makes its own private copy of the data immediately, before</span>
    3172. 

  3172. <a name="l03119"></a>03119 <span class="comment">** the sqlite3_bind_*() routine returns.</span>
    3173. 

  3173. <a name="l03120"></a>03120 <span class="comment">**</span>
    3174. 

  3174. <a name="l03121"></a>03121 <span class="comment">** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that</span>
    3175. 

  3175. <a name="l03122"></a>03122 <span class="comment">** is filled with zeroes.  ^A zeroblob uses a fixed amount of memory</span>
    3176. 

  3176. <a name="l03123"></a>03123 <span class="comment">** (just an integer to hold its size) while it is being processed.</span>
    3177. 

  3177. <a name="l03124"></a>03124 <span class="comment">** Zeroblobs are intended to serve as placeholders for BLOBs whose</span>
    3178. 

  3178. <a name="l03125"></a>03125 <span class="comment">** content is later written using</span>
    3179. 

  3179. <a name="l03126"></a>03126 <span class="comment">** [sqlite3_blob_open | incremental BLOB I/O] routines.</span>
    3180. 

  3180. <a name="l03127"></a>03127 <span class="comment">** ^A negative value for the zeroblob results in a zero-length BLOB.</span>
    3181. 

  3181. <a name="l03128"></a>03128 <span class="comment">**</span>
    3182. 

  3182. <a name="l03129"></a>03129 <span class="comment">** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer</span>
    3183. 

  3183. <a name="l03130"></a>03130 <span class="comment">** for the [prepared statement] or with a prepared statement for which</span>
    3184. 

  3184. <a name="l03131"></a>03131 <span class="comment">** [sqlite3_step()] has been called more recently than [sqlite3_reset()],</span>
    3185. 

  3185. <a name="l03132"></a>03132 <span class="comment">** then the call will return [SQLITE_MISUSE].  If any sqlite3_bind_()</span>
    3186. 

  3186. <a name="l03133"></a>03133 <span class="comment">** routine is passed a [prepared statement] that has been finalized, the</span>
    3187. 

  3187. <a name="l03134"></a>03134 <span class="comment">** result is undefined and probably harmful.</span>
    3188. 

  3188. <a name="l03135"></a>03135 <span class="comment">**</span>
    3189. 

  3189. <a name="l03136"></a>03136 <span class="comment">** ^Bindings are not cleared by the [sqlite3_reset()] routine.</span>
    3190. 

  3190. <a name="l03137"></a>03137 <span class="comment">** ^Unbound parameters are interpreted as NULL.</span>
    3191. 

  3191. <a name="l03138"></a>03138 <span class="comment">**</span>
    3192. 

  3192. <a name="l03139"></a>03139 <span class="comment">** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an</span>
    3193. 

  3193. <a name="l03140"></a>03140 <span class="comment">** [error code] if anything goes wrong.</span>
    3194. 

  3194. <a name="l03141"></a>03141 <span class="comment">** ^[SQLITE_RANGE] is returned if the parameter</span>
    3195. 

  3195. <a name="l03142"></a>03142 <span class="comment">** index is out of range.  ^[SQLITE_NOMEM] is returned if malloc() fails.</span>
    3196. 

  3196. <a name="l03143"></a>03143 <span class="comment">**</span>
    3197. 

  3197. <a name="l03144"></a>03144 <span class="comment">** See also: [sqlite3_bind_parameter_count()],</span>
    3198. 

  3198. <a name="l03145"></a>03145 <span class="comment">** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].</span>
    3199. 

  3199. <a name="l03146"></a>03146 <span class="comment">*/</span>
    3200. 

  3200. <a name="l03147"></a>03147 SQLITE_API <span class="keywordtype">int</span> sqlite3_bind_blob(sqlite3_stmt*, <span class="keywordtype">int</span>, <span class="keyword">const</span> <span class="keywordtype">void</span>*, <span class="keywordtype">int</span> n, <span class="keywordtype">void</span>(*)(<span class="keywordtype">void</span>*));
    3201. 

  3201. <a name="l03148"></a>03148 SQLITE_API <span class="keywordtype">int</span> sqlite3_bind_double(sqlite3_stmt*, <span class="keywordtype">int</span>, <span class="keywordtype">double</span>);
    3202. 

  3202. <a name="l03149"></a>03149 SQLITE_API <span class="keywordtype">int</span> sqlite3_bind_int(sqlite3_stmt*, <span class="keywordtype">int</span>, <span class="keywordtype">int</span>);
    3203. 

  3203. <a name="l03150"></a>03150 SQLITE_API <span class="keywordtype">int</span> sqlite3_bind_int64(sqlite3_stmt*, <span class="keywordtype">int</span>, sqlite3_int64);
    3204. 

  3204. <a name="l03151"></a>03151 SQLITE_API <span class="keywordtype">int</span> sqlite3_bind_null(sqlite3_stmt*, <span class="keywordtype">int</span>);
    3205. 

  3205. <a name="l03152"></a>03152 SQLITE_API <span class="keywordtype">int</span> sqlite3_bind_text(sqlite3_stmt*, <span class="keywordtype">int</span>, <span class="keyword">const</span> <span class="keywordtype">char</span>*, <span class="keywordtype">int</span> n, <span class="keywordtype">void</span>(*)(<span class="keywordtype">void</span>*));
    3206. 

  3206. <a name="l03153"></a>03153 SQLITE_API <span class="keywordtype">int</span> sqlite3_bind_text16(sqlite3_stmt*, <span class="keywordtype">int</span>, <span class="keyword">const</span> <span class="keywordtype">void</span>*, <span class="keywordtype">int</span>, <span class="keywordtype">void</span>(*)(<span class="keywordtype">void</span>*));
    3207. 

  3207. <a name="l03154"></a>03154 SQLITE_API <span class="keywordtype">int</span> sqlite3_bind_value(sqlite3_stmt*, <span class="keywordtype">int</span>, <span class="keyword">const</span> <a class="code" href="structMem.html">sqlite3_value</a>*);
    3208. 

  3208. <a name="l03155"></a>03155 SQLITE_API <span class="keywordtype">int</span> sqlite3_bind_zeroblob(sqlite3_stmt*, <span class="keywordtype">int</span>, <span class="keywordtype">int</span> n);
    3209. 

  3209. <a name="l03156"></a>03156 
    3210. 

  3210. <a name="l03157"></a>03157 <span class="comment">/*</span>
    3211. 

  3211. <a name="l03158"></a>03158 <span class="comment">** CAPI3REF: Number Of SQL Parameters</span>
    3212. 

  3212. <a name="l03159"></a>03159 <span class="comment">**</span>
    3213. 

  3213. <a name="l03160"></a>03160 <span class="comment">** ^This routine can be used to find the number of [SQL parameters]</span>
    3214. 

  3214. <a name="l03161"></a>03161 <span class="comment">** in a [prepared statement].  SQL parameters are tokens of the</span>
    3215. 

  3215. <a name="l03162"></a>03162 <span class="comment">** form &quot;?&quot;, &quot;?NNN&quot;, &quot;:AAA&quot;, &quot;$AAA&quot;, or &quot;@AAA&quot; that serve as</span>
    3216. 

  3216. <a name="l03163"></a>03163 <span class="comment">** placeholders for values that are [sqlite3_bind_blob | bound]</span>
    3217. 

  3217. <a name="l03164"></a>03164 <span class="comment">** to the parameters at a later time.</span>
    3218. 

  3218. <a name="l03165"></a>03165 <span class="comment">**</span>
    3219. 

  3219. <a name="l03166"></a>03166 <span class="comment">** ^(This routine actually returns the index of the largest (rightmost)</span>
    3220. 

  3220. <a name="l03167"></a>03167 <span class="comment">** parameter. For all forms except ?NNN, this will correspond to the</span>
    3221. 

  3221. <a name="l03168"></a>03168 <span class="comment">** number of unique parameters.  If parameters of the ?NNN form are used,</span>
    3222. 

  3222. <a name="l03169"></a>03169 <span class="comment">** there may be gaps in the list.)^</span>
    3223. 

  3223. <a name="l03170"></a>03170 <span class="comment">**</span>
    3224. 

  3224. <a name="l03171"></a>03171 <span class="comment">** See also: [sqlite3_bind_blob|sqlite3_bind()],</span>
    3225. 

  3225. <a name="l03172"></a>03172 <span class="comment">** [sqlite3_bind_parameter_name()], and</span>
    3226. 

  3226. <a name="l03173"></a>03173 <span class="comment">** [sqlite3_bind_parameter_index()].</span>
    3227. 

  3227. <a name="l03174"></a>03174 <span class="comment">*/</span>
    3228. 

  3228. <a name="l03175"></a>03175 SQLITE_API <span class="keywordtype">int</span> sqlite3_bind_parameter_count(sqlite3_stmt*);
    3229. 

  3229. <a name="l03176"></a>03176 
    3230. 

  3230. <a name="l03177"></a>03177 <span class="comment">/*</span>
    3231. 

  3231. <a name="l03178"></a>03178 <span class="comment">** CAPI3REF: Name Of A Host Parameter</span>
    3232. 

  3232. <a name="l03179"></a>03179 <span class="comment">**</span>
    3233. 

  3233. <a name="l03180"></a>03180 <span class="comment">** ^The sqlite3_bind_parameter_name(P,N) interface returns</span>
    3234. 

  3234. <a name="l03181"></a>03181 <span class="comment">** the name of the N-th [SQL parameter] in the [prepared statement] P.</span>
    3235. 

  3235. <a name="l03182"></a>03182 <span class="comment">** ^(SQL parameters of the form &quot;?NNN&quot; or &quot;:AAA&quot; or &quot;@AAA&quot; or &quot;$AAA&quot;</span>
    3236. 

  3236. <a name="l03183"></a>03183 <span class="comment">** have a name which is the string &quot;?NNN&quot; or &quot;:AAA&quot; or &quot;@AAA&quot; or &quot;$AAA&quot;</span>
    3237. 

  3237. <a name="l03184"></a>03184 <span class="comment">** respectively.</span>
    3238. 

  3238. <a name="l03185"></a>03185 <span class="comment">** In other words, the initial &quot;:&quot; or &quot;$&quot; or &quot;@&quot; or &quot;?&quot;</span>
    3239. 

  3239. <a name="l03186"></a>03186 <span class="comment">** is included as part of the name.)^</span>
    3240. 

  3240. <a name="l03187"></a>03187 <span class="comment">** ^Parameters of the form &quot;?&quot; without a following integer have no name</span>
    3241. 

  3241. <a name="l03188"></a>03188 <span class="comment">** and are referred to as &quot;nameless&quot; or &quot;anonymous parameters&quot;.</span>
    3242. 

  3242. <a name="l03189"></a>03189 <span class="comment">**</span>
    3243. 

  3243. <a name="l03190"></a>03190 <span class="comment">** ^The first host parameter has an index of 1, not 0.</span>
    3244. 

  3244. <a name="l03191"></a>03191 <span class="comment">**</span>
    3245. 

  3245. <a name="l03192"></a>03192 <span class="comment">** ^If the value N is out of range or if the N-th parameter is</span>
    3246. 

  3246. <a name="l03193"></a>03193 <span class="comment">** nameless, then NULL is returned.  ^The returned string is</span>
    3247. 

  3247. <a name="l03194"></a>03194 <span class="comment">** always in UTF-8 encoding even if the named parameter was</span>
    3248. 

  3248. <a name="l03195"></a>03195 <span class="comment">** originally specified as UTF-16 in [sqlite3_prepare16()] or</span>
    3249. 

  3249. <a name="l03196"></a>03196 <span class="comment">** [sqlite3_prepare16_v2()].</span>
    3250. 

  3250. <a name="l03197"></a>03197 <span class="comment">**</span>
    3251. 

  3251. <a name="l03198"></a>03198 <span class="comment">** See also: [sqlite3_bind_blob|sqlite3_bind()],</span>
    3252. 

  3252. <a name="l03199"></a>03199 <span class="comment">** [sqlite3_bind_parameter_count()], and</span>
    3253. 

  3253. <a name="l03200"></a>03200 <span class="comment">** [sqlite3_bind_parameter_index()].</span>
    3254. 

  3254. <a name="l03201"></a>03201 <span class="comment">*/</span>
    3255. 

  3255. <a name="l03202"></a>03202 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">char</span> *sqlite3_bind_parameter_name(sqlite3_stmt*, <span class="keywordtype">int</span>);
    3256. 

  3256. <a name="l03203"></a>03203 
    3257. 

  3257. <a name="l03204"></a>03204 <span class="comment">/*</span>
    3258. 

  3258. <a name="l03205"></a>03205 <span class="comment">** CAPI3REF: Index Of A Parameter With A Given Name</span>
    3259. 

  3259. <a name="l03206"></a>03206 <span class="comment">**</span>
    3260. 

  3260. <a name="l03207"></a>03207 <span class="comment">** ^Return the index of an SQL parameter given its name.  ^The</span>
    3261. 

  3261. <a name="l03208"></a>03208 <span class="comment">** index value returned is suitable for use as the second</span>
    3262. 

  3262. <a name="l03209"></a>03209 <span class="comment">** parameter to [sqlite3_bind_blob|sqlite3_bind()].  ^A zero</span>
    3263. 

  3263. <a name="l03210"></a>03210 <span class="comment">** is returned if no matching parameter is found.  ^The parameter</span>
    3264. 

  3264. <a name="l03211"></a>03211 <span class="comment">** name must be given in UTF-8 even if the original statement</span>
    3265. 

  3265. <a name="l03212"></a>03212 <span class="comment">** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].</span>
    3266. 

  3266. <a name="l03213"></a>03213 <span class="comment">**</span>
    3267. 

  3267. <a name="l03214"></a>03214 <span class="comment">** See also: [sqlite3_bind_blob|sqlite3_bind()],</span>
    3268. 

  3268. <a name="l03215"></a>03215 <span class="comment">** [sqlite3_bind_parameter_count()], and</span>
    3269. 

  3269. <a name="l03216"></a>03216 <span class="comment">** [sqlite3_bind_parameter_index()].</span>
    3270. 

  3270. <a name="l03217"></a>03217 <span class="comment">*/</span>
    3271. 

  3271. <a name="l03218"></a>03218 SQLITE_API <span class="keywordtype">int</span> sqlite3_bind_parameter_index(sqlite3_stmt*, <span class="keyword">const</span> <span class="keywordtype">char</span> *zName);
    3272. 

  3272. <a name="l03219"></a>03219 
    3273. 

  3273. <a name="l03220"></a>03220 <span class="comment">/*</span>
    3274. 

  3274. <a name="l03221"></a>03221 <span class="comment">** CAPI3REF: Reset All Bindings On A Prepared Statement</span>
    3275. 

  3275. <a name="l03222"></a>03222 <span class="comment">**</span>
    3276. 

  3276. <a name="l03223"></a>03223 <span class="comment">** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset</span>
    3277. 

  3277. <a name="l03224"></a>03224 <span class="comment">** the [sqlite3_bind_blob | bindings] on a [prepared statement].</span>
    3278. 

  3278. <a name="l03225"></a>03225 <span class="comment">** ^Use this routine to reset all host parameters to NULL.</span>
    3279. 

  3279. <a name="l03226"></a>03226 <span class="comment">*/</span>
    3280. 

  3280. <a name="l03227"></a>03227 SQLITE_API <span class="keywordtype">int</span> sqlite3_clear_bindings(sqlite3_stmt*);
    3281. 

  3281. <a name="l03228"></a>03228 
    3282. 

  3282. <a name="l03229"></a>03229 <span class="comment">/*</span>
    3283. 

  3283. <a name="l03230"></a>03230 <span class="comment">** CAPI3REF: Number Of Columns In A Result Set</span>
    3284. 

  3284. <a name="l03231"></a>03231 <span class="comment">**</span>
    3285. 

  3285. <a name="l03232"></a>03232 <span class="comment">** ^Return the number of columns in the result set returned by the</span>
    3286. 

  3286. <a name="l03233"></a>03233 <span class="comment">** [prepared statement]. ^This routine returns 0 if pStmt is an SQL</span>
    3287. 

  3287. <a name="l03234"></a>03234 <span class="comment">** statement that does not return data (for example an [UPDATE]).</span>
    3288. 

  3288. <a name="l03235"></a>03235 <span class="comment">**</span>
    3289. 

  3289. <a name="l03236"></a>03236 <span class="comment">** See also: [sqlite3_data_count()]</span>
    3290. 

  3290. <a name="l03237"></a>03237 <span class="comment">*/</span>
    3291. 

  3291. <a name="l03238"></a>03238 SQLITE_API <span class="keywordtype">int</span> sqlite3_column_count(sqlite3_stmt *pStmt);
    3292. 

  3292. <a name="l03239"></a>03239 
    3293. 

  3293. <a name="l03240"></a>03240 <span class="comment">/*</span>
    3294. 

  3294. <a name="l03241"></a>03241 <span class="comment">** CAPI3REF: Column Names In A Result Set</span>
    3295. 

  3295. <a name="l03242"></a>03242 <span class="comment">**</span>
    3296. 

  3296. <a name="l03243"></a>03243 <span class="comment">** ^These routines return the name assigned to a particular column</span>
    3297. 

  3297. <a name="l03244"></a>03244 <span class="comment">** in the result set of a [SELECT] statement.  ^The sqlite3_column_name()</span>
    3298. 

  3298. <a name="l03245"></a>03245 <span class="comment">** interface returns a pointer to a zero-terminated UTF-8 string</span>
    3299. 

  3299. <a name="l03246"></a>03246 <span class="comment">** and sqlite3_column_name16() returns a pointer to a zero-terminated</span>
    3300. 

  3300. <a name="l03247"></a>03247 <span class="comment">** UTF-16 string.  ^The first parameter is the [prepared statement]</span>
    3301. 

  3301. <a name="l03248"></a>03248 <span class="comment">** that implements the [SELECT] statement. ^The second parameter is the</span>
    3302. 

  3302. <a name="l03249"></a>03249 <span class="comment">** column number.  ^The leftmost column is number 0.</span>
    3303. 

  3303. <a name="l03250"></a>03250 <span class="comment">**</span>
    3304. 

  3304. <a name="l03251"></a>03251 <span class="comment">** ^The returned string pointer is valid until either the [prepared statement]</span>
    3305. 

  3305. <a name="l03252"></a>03252 <span class="comment">** is destroyed by [sqlite3_finalize()] or until the statement is automatically</span>
    3306. 

  3306. <a name="l03253"></a>03253 <span class="comment">** reprepared by the first call to [sqlite3_step()] for a particular run</span>
    3307. 

  3307. <a name="l03254"></a>03254 <span class="comment">** or until the next call to</span>
    3308. 

  3308. <a name="l03255"></a>03255 <span class="comment">** sqlite3_column_name() or sqlite3_column_name16() on the same column.</span>
    3309. 

  3309. <a name="l03256"></a>03256 <span class="comment">**</span>
    3310. 

  3310. <a name="l03257"></a>03257 <span class="comment">** ^If sqlite3_malloc() fails during the processing of either routine</span>
    3311. 

  3311. <a name="l03258"></a>03258 <span class="comment">** (for example during a conversion from UTF-8 to UTF-16) then a</span>
    3312. 

  3312. <a name="l03259"></a>03259 <span class="comment">** NULL pointer is returned.</span>
    3313. 

  3313. <a name="l03260"></a>03260 <span class="comment">**</span>
    3314. 

  3314. <a name="l03261"></a>03261 <span class="comment">** ^The name of a result column is the value of the &quot;AS&quot; clause for</span>
    3315. 

  3315. <a name="l03262"></a>03262 <span class="comment">** that column, if there is an AS clause.  If there is no AS clause</span>
    3316. 

  3316. <a name="l03263"></a>03263 <span class="comment">** then the name of the column is unspecified and may change from</span>
    3317. 

  3317. <a name="l03264"></a>03264 <span class="comment">** one release of SQLite to the next.</span>
    3318. 

  3318. <a name="l03265"></a>03265 <span class="comment">*/</span>
    3319. 

  3319. <a name="l03266"></a>03266 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">char</span> *sqlite3_column_name(sqlite3_stmt*, <span class="keywordtype">int</span> N);
    3320. 

  3320. <a name="l03267"></a>03267 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">void</span> *sqlite3_column_name16(sqlite3_stmt*, <span class="keywordtype">int</span> N);
    3321. 

  3321. <a name="l03268"></a>03268 
    3322. 

  3322. <a name="l03269"></a>03269 <span class="comment">/*</span>
    3323. 

  3323. <a name="l03270"></a>03270 <span class="comment">** CAPI3REF: Source Of Data In A Query Result</span>
    3324. 

  3324. <a name="l03271"></a>03271 <span class="comment">**</span>
    3325. 

  3325. <a name="l03272"></a>03272 <span class="comment">** ^These routines provide a means to determine the database, table, and</span>
    3326. 

  3326. <a name="l03273"></a>03273 <span class="comment">** table column that is the origin of a particular result column in</span>
    3327. 

  3327. <a name="l03274"></a>03274 <span class="comment">** [SELECT] statement.</span>
    3328. 

  3328. <a name="l03275"></a>03275 <span class="comment">** ^The name of the database or table or column can be returned as</span>
    3329. 

  3329. <a name="l03276"></a>03276 <span class="comment">** either a UTF-8 or UTF-16 string.  ^The _database_ routines return</span>
    3330. 

  3330. <a name="l03277"></a>03277 <span class="comment">** the database name, the _table_ routines return the table name, and</span>
    3331. 

  3331. <a name="l03278"></a>03278 <span class="comment">** the origin_ routines return the column name.</span>
    3332. 

  3332. <a name="l03279"></a>03279 <span class="comment">** ^The returned string is valid until the [prepared statement] is destroyed</span>
    3333. 

  3333. <a name="l03280"></a>03280 <span class="comment">** using [sqlite3_finalize()] or until the statement is automatically</span>
    3334. 

  3334. <a name="l03281"></a>03281 <span class="comment">** reprepared by the first call to [sqlite3_step()] for a particular run</span>
    3335. 

  3335. <a name="l03282"></a>03282 <span class="comment">** or until the same information is requested</span>
    3336. 

  3336. <a name="l03283"></a>03283 <span class="comment">** again in a different encoding.</span>
    3337. 

  3337. <a name="l03284"></a>03284 <span class="comment">**</span>
    3338. 

  3338. <a name="l03285"></a>03285 <span class="comment">** ^The names returned are the original un-aliased names of the</span>
    3339. 

  3339. <a name="l03286"></a>03286 <span class="comment">** database, table, and column.</span>
    3340. 

  3340. <a name="l03287"></a>03287 <span class="comment">**</span>
    3341. 

  3341. <a name="l03288"></a>03288 <span class="comment">** ^The first argument to these interfaces is a [prepared statement].</span>
    3342. 

  3342. <a name="l03289"></a>03289 <span class="comment">** ^These functions return information about the Nth result column returned by</span>
    3343. 

  3343. <a name="l03290"></a>03290 <span class="comment">** the statement, where N is the second function argument.</span>
    3344. 

  3344. <a name="l03291"></a>03291 <span class="comment">** ^The left-most column is column 0 for these routines.</span>
    3345. 

  3345. <a name="l03292"></a>03292 <span class="comment">**</span>
    3346. 

  3346. <a name="l03293"></a>03293 <span class="comment">** ^If the Nth column returned by the statement is an expression or</span>
    3347. 

  3347. <a name="l03294"></a>03294 <span class="comment">** subquery and is not a column value, then all of these functions return</span>
    3348. 

  3348. <a name="l03295"></a>03295 <span class="comment">** NULL.  ^These routine might also return NULL if a memory allocation error</span>
    3349. 

  3349. <a name="l03296"></a>03296 <span class="comment">** occurs.  ^Otherwise, they return the name of the attached database, table,</span>
    3350. 

  3350. <a name="l03297"></a>03297 <span class="comment">** or column that query result column was extracted from.</span>
    3351. 

  3351. <a name="l03298"></a>03298 <span class="comment">**</span>
    3352. 

  3352. <a name="l03299"></a>03299 <span class="comment">** ^As with all other SQLite APIs, those whose names end with &quot;16&quot; return</span>
    3353. 

  3353. <a name="l03300"></a>03300 <span class="comment">** UTF-16 encoded strings and the other functions return UTF-8.</span>
    3354. 

  3354. <a name="l03301"></a>03301 <span class="comment">**</span>
    3355. 

  3355. <a name="l03302"></a>03302 <span class="comment">** ^These APIs are only available if the library was compiled with the</span>
    3356. 

  3356. <a name="l03303"></a>03303 <span class="comment">** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.</span>
    3357. 

  3357. <a name="l03304"></a>03304 <span class="comment">**</span>
    3358. 

  3358. <a name="l03305"></a>03305 <span class="comment">** If two or more threads call one or more of these routines against the same</span>
    3359. 

  3359. <a name="l03306"></a>03306 <span class="comment">** prepared statement and column at the same time then the results are</span>
    3360. 

  3360. <a name="l03307"></a>03307 <span class="comment">** undefined.</span>
    3361. 

  3361. <a name="l03308"></a>03308 <span class="comment">**</span>
    3362. 

  3362. <a name="l03309"></a>03309 <span class="comment">** If two or more threads call one or more</span>
    3363. 

  3363. <a name="l03310"></a>03310 <span class="comment">** [sqlite3_column_database_name | column metadata interfaces]</span>
    3364. 

  3364. <a name="l03311"></a>03311 <span class="comment">** for the same [prepared statement] and result column</span>
    3365. 

  3365. <a name="l03312"></a>03312 <span class="comment">** at the same time then the results are undefined.</span>
    3366. 

  3366. <a name="l03313"></a>03313 <span class="comment">*/</span>
    3367. 

  3367. <a name="l03314"></a>03314 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">char</span> *sqlite3_column_database_name(sqlite3_stmt*,<span class="keywordtype">int</span>);
    3368. 

  3368. <a name="l03315"></a>03315 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">void</span> *sqlite3_column_database_name16(sqlite3_stmt*,<span class="keywordtype">int</span>);
    3369. 

  3369. <a name="l03316"></a>03316 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">char</span> *sqlite3_column_table_name(sqlite3_stmt*,<span class="keywordtype">int</span>);
    3370. 

  3370. <a name="l03317"></a>03317 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">void</span> *sqlite3_column_table_name16(sqlite3_stmt*,<span class="keywordtype">int</span>);
    3371. 

  3371. <a name="l03318"></a>03318 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">char</span> *sqlite3_column_origin_name(sqlite3_stmt*,<span class="keywordtype">int</span>);
    3372. 

  3372. <a name="l03319"></a>03319 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">void</span> *sqlite3_column_origin_name16(sqlite3_stmt*,<span class="keywordtype">int</span>);
    3373. 

  3373. <a name="l03320"></a>03320 
    3374. 

  3374. <a name="l03321"></a>03321 <span class="comment">/*</span>
    3375. 

  3375. <a name="l03322"></a>03322 <span class="comment">** CAPI3REF: Declared Datatype Of A Query Result</span>
    3376. 

  3376. <a name="l03323"></a>03323 <span class="comment">**</span>
    3377. 

  3377. <a name="l03324"></a>03324 <span class="comment">** ^(The first parameter is a [prepared statement].</span>
    3378. 

  3378. <a name="l03325"></a>03325 <span class="comment">** If this statement is a [SELECT] statement and the Nth column of the</span>
    3379. 

  3379. <a name="l03326"></a>03326 <span class="comment">** returned result set of that [SELECT] is a table column (not an</span>
    3380. 

  3380. <a name="l03327"></a>03327 <span class="comment">** expression or subquery) then the declared type of the table</span>
    3381. 

  3381. <a name="l03328"></a>03328 <span class="comment">** column is returned.)^  ^If the Nth column of the result set is an</span>
    3382. 

  3382. <a name="l03329"></a>03329 <span class="comment">** expression or subquery, then a NULL pointer is returned.</span>
    3383. 

  3383. <a name="l03330"></a>03330 <span class="comment">** ^The returned string is always UTF-8 encoded.</span>
    3384. 

  3384. <a name="l03331"></a>03331 <span class="comment">**</span>
    3385. 

  3385. <a name="l03332"></a>03332 <span class="comment">** ^(For example, given the database schema:</span>
    3386. 

  3386. <a name="l03333"></a>03333 <span class="comment">**</span>
    3387. 

  3387. <a name="l03334"></a>03334 <span class="comment">** CREATE TABLE t1(c1 VARIANT);</span>
    3388. 

  3388. <a name="l03335"></a>03335 <span class="comment">**</span>
    3389. 

  3389. <a name="l03336"></a>03336 <span class="comment">** and the following statement to be compiled:</span>
    3390. 

  3390. <a name="l03337"></a>03337 <span class="comment">**</span>
    3391. 

  3391. <a name="l03338"></a>03338 <span class="comment">** SELECT c1 + 1, c1 FROM t1;</span>
    3392. 

  3392. <a name="l03339"></a>03339 <span class="comment">**</span>
    3393. 

  3393. <a name="l03340"></a>03340 <span class="comment">** this routine would return the string &quot;VARIANT&quot; for the second result</span>
    3394. 

  3394. <a name="l03341"></a>03341 <span class="comment">** column (i==1), and a NULL pointer for the first result column (i==0).)^</span>
    3395. 

  3395. <a name="l03342"></a>03342 <span class="comment">**</span>
    3396. 

  3396. <a name="l03343"></a>03343 <span class="comment">** ^SQLite uses dynamic run-time typing.  ^So just because a column</span>
    3397. 

  3397. <a name="l03344"></a>03344 <span class="comment">** is declared to contain a particular type does not mean that the</span>
    3398. 

  3398. <a name="l03345"></a>03345 <span class="comment">** data stored in that column is of the declared type.  SQLite is</span>
    3399. 

  3399. <a name="l03346"></a>03346 <span class="comment">** strongly typed, but the typing is dynamic not static.  ^Type</span>
    3400. 

  3400. <a name="l03347"></a>03347 <span class="comment">** is associated with individual values, not with the containers</span>
    3401. 

  3401. <a name="l03348"></a>03348 <span class="comment">** used to hold those values.</span>
    3402. 

  3402. <a name="l03349"></a>03349 <span class="comment">*/</span>
    3403. 

  3403. <a name="l03350"></a>03350 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">char</span> *sqlite3_column_decltype(sqlite3_stmt*,<span class="keywordtype">int</span>);
    3404. 

  3404. <a name="l03351"></a>03351 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">void</span> *sqlite3_column_decltype16(sqlite3_stmt*,<span class="keywordtype">int</span>);
    3405. 

  3405. <a name="l03352"></a>03352 
    3406. 

  3406. <a name="l03353"></a>03353 <span class="comment">/*</span>
    3407. 

  3407. <a name="l03354"></a>03354 <span class="comment">** CAPI3REF: Evaluate An SQL Statement</span>
    3408. 

  3408. <a name="l03355"></a>03355 <span class="comment">**</span>
    3409. 

  3409. <a name="l03356"></a>03356 <span class="comment">** After a [prepared statement] has been prepared using either</span>
    3410. 

  3410. <a name="l03357"></a>03357 <span class="comment">** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy</span>
    3411. 

  3411. <a name="l03358"></a>03358 <span class="comment">** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function</span>
    3412. 

  3412. <a name="l03359"></a>03359 <span class="comment">** must be called one or more times to evaluate the statement.</span>
    3413. 

  3413. <a name="l03360"></a>03360 <span class="comment">**</span>
    3414. 

  3414. <a name="l03361"></a>03361 <span class="comment">** The details of the behavior of the sqlite3_step() interface depend</span>
    3415. 

  3415. <a name="l03362"></a>03362 <span class="comment">** on whether the statement was prepared using the newer &quot;v2&quot; interface</span>
    3416. 

  3416. <a name="l03363"></a>03363 <span class="comment">** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy</span>
    3417. 

  3417. <a name="l03364"></a>03364 <span class="comment">** interface [sqlite3_prepare()] and [sqlite3_prepare16()].  The use of the</span>
    3418. 

  3418. <a name="l03365"></a>03365 <span class="comment">** new &quot;v2&quot; interface is recommended for new applications but the legacy</span>
    3419. 

  3419. <a name="l03366"></a>03366 <span class="comment">** interface will continue to be supported.</span>
    3420. 

  3420. <a name="l03367"></a>03367 <span class="comment">**</span>
    3421. 

  3421. <a name="l03368"></a>03368 <span class="comment">** ^In the legacy interface, the return value will be either [SQLITE_BUSY],</span>
    3422. 

  3422. <a name="l03369"></a>03369 <span class="comment">** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].</span>
    3423. 

  3423. <a name="l03370"></a>03370 <span class="comment">** ^With the &quot;v2&quot; interface, any of the other [result codes] or</span>
    3424. 

  3424. <a name="l03371"></a>03371 <span class="comment">** [extended result codes] might be returned as well.</span>
    3425. 

  3425. <a name="l03372"></a>03372 <span class="comment">**</span>
    3426. 

  3426. <a name="l03373"></a>03373 <span class="comment">** ^[SQLITE_BUSY] means that the database engine was unable to acquire the</span>
    3427. 

  3427. <a name="l03374"></a>03374 <span class="comment">** database locks it needs to do its job.  ^If the statement is a [COMMIT]</span>
    3428. 

  3428. <a name="l03375"></a>03375 <span class="comment">** or occurs outside of an explicit transaction, then you can retry the</span>
    3429. 

  3429. <a name="l03376"></a>03376 <span class="comment">** statement.  If the statement is not a [COMMIT] and occurs within an</span>
    3430. 

  3430. <a name="l03377"></a>03377 <span class="comment">** explicit transaction then you should rollback the transaction before</span>
    3431. 

  3431. <a name="l03378"></a>03378 <span class="comment">** continuing.</span>
    3432. 

  3432. <a name="l03379"></a>03379 <span class="comment">**</span>
    3433. 

  3433. <a name="l03380"></a>03380 <span class="comment">** ^[SQLITE_DONE] means that the statement has finished executing</span>
    3434. 

  3434. <a name="l03381"></a>03381 <span class="comment">** successfully.  sqlite3_step() should not be called again on this virtual</span>
    3435. 

  3435. <a name="l03382"></a>03382 <span class="comment">** machine without first calling [sqlite3_reset()] to reset the virtual</span>
    3436. 

  3436. <a name="l03383"></a>03383 <span class="comment">** machine back to its initial state.</span>
    3437. 

  3437. <a name="l03384"></a>03384 <span class="comment">**</span>
    3438. 

  3438. <a name="l03385"></a>03385 <span class="comment">** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]</span>
    3439. 

  3439. <a name="l03386"></a>03386 <span class="comment">** is returned each time a new row of data is ready for processing by the</span>
    3440. 

  3440. <a name="l03387"></a>03387 <span class="comment">** caller. The values may be accessed using the [column access functions].</span>
    3441. 

  3441. <a name="l03388"></a>03388 <span class="comment">** sqlite3_step() is called again to retrieve the next row of data.</span>
    3442. 

  3442. <a name="l03389"></a>03389 <span class="comment">**</span>
    3443. 

  3443. <a name="l03390"></a>03390 <span class="comment">** ^[SQLITE_ERROR] means that a run-time error (such as a constraint</span>
    3444. 

  3444. <a name="l03391"></a>03391 <span class="comment">** violation) has occurred.  sqlite3_step() should not be called again on</span>
    3445. 

  3445. <a name="l03392"></a>03392 <span class="comment">** the VM. More information may be found by calling [sqlite3_errmsg()].</span>
    3446. 

  3446. <a name="l03393"></a>03393 <span class="comment">** ^With the legacy interface, a more specific error code (for example,</span>
    3447. 

  3447. <a name="l03394"></a>03394 <span class="comment">** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)</span>
    3448. 

  3448. <a name="l03395"></a>03395 <span class="comment">** can be obtained by calling [sqlite3_reset()] on the</span>
    3449. 

  3449. <a name="l03396"></a>03396 <span class="comment">** [prepared statement].  ^In the &quot;v2&quot; interface,</span>
    3450. 

  3450. <a name="l03397"></a>03397 <span class="comment">** the more specific error code is returned directly by sqlite3_step().</span>
    3451. 

  3451. <a name="l03398"></a>03398 <span class="comment">**</span>
    3452. 

  3452. <a name="l03399"></a>03399 <span class="comment">** [SQLITE_MISUSE] means that the this routine was called inappropriately.</span>
    3453. 

  3453. <a name="l03400"></a>03400 <span class="comment">** Perhaps it was called on a [prepared statement] that has</span>
    3454. 

  3454. <a name="l03401"></a>03401 <span class="comment">** already been [sqlite3_finalize | finalized] or on one that had</span>
    3455. 

  3455. <a name="l03402"></a>03402 <span class="comment">** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could</span>
    3456. 

  3456. <a name="l03403"></a>03403 <span class="comment">** be the case that the same database connection is being used by two or</span>
    3457. 

  3457. <a name="l03404"></a>03404 <span class="comment">** more threads at the same moment in time.</span>
    3458. 

  3458. <a name="l03405"></a>03405 <span class="comment">**</span>
    3459. 

  3459. <a name="l03406"></a>03406 <span class="comment">** For all versions of SQLite up to and including 3.6.23.1, a call to</span>
    3460. 

  3460. <a name="l03407"></a>03407 <span class="comment">** [sqlite3_reset()] was required after sqlite3_step() returned anything</span>
    3461. 

  3461. <a name="l03408"></a>03408 <span class="comment">** other than [SQLITE_ROW] before any subsequent invocation of</span>
    3462. 

  3462. <a name="l03409"></a>03409 <span class="comment">** sqlite3_step().  Failure to reset the prepared statement using </span>
    3463. 

  3463. <a name="l03410"></a>03410 <span class="comment">** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from</span>
    3464. 

  3464. <a name="l03411"></a>03411 <span class="comment">** sqlite3_step().  But after version 3.6.23.1, sqlite3_step() began</span>
    3465. 

  3465. <a name="l03412"></a>03412 <span class="comment">** calling [sqlite3_reset()] automatically in this circumstance rather</span>
    3466. 

  3466. <a name="l03413"></a>03413 <span class="comment">** than returning [SQLITE_MISUSE].  This is not considered a compatibility</span>
    3467. 

  3467. <a name="l03414"></a>03414 <span class="comment">** break because any application that ever receives an SQLITE_MISUSE error</span>
    3468. 

  3468. <a name="l03415"></a>03415 <span class="comment">** is broken by definition.  The [SQLITE_OMIT_AUTORESET] compile-time option</span>
    3469. 

  3469. <a name="l03416"></a>03416 <span class="comment">** can be used to restore the legacy behavior.</span>
    3470. 

  3470. <a name="l03417"></a>03417 <span class="comment">**</span>
    3471. 

  3471. <a name="l03418"></a>03418 <span class="comment">** &lt;b&gt;Goofy Interface Alert:&lt;/b&gt; In the legacy interface, the sqlite3_step()</span>
    3472. 

  3472. <a name="l03419"></a>03419 <span class="comment">** API always returns a generic error code, [SQLITE_ERROR], following any</span>
    3473. 

  3473. <a name="l03420"></a>03420 <span class="comment">** error other than [SQLITE_BUSY] and [SQLITE_MISUSE].  You must call</span>
    3474. 

  3474. <a name="l03421"></a>03421 <span class="comment">** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the</span>
    3475. 

  3475. <a name="l03422"></a>03422 <span class="comment">** specific [error codes] that better describes the error.</span>
    3476. 

  3476. <a name="l03423"></a>03423 <span class="comment">** We admit that this is a goofy design.  The problem has been fixed</span>
    3477. 

  3477. <a name="l03424"></a>03424 <span class="comment">** with the &quot;v2&quot; interface.  If you prepare all of your SQL statements</span>
    3478. 

  3478. <a name="l03425"></a>03425 <span class="comment">** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead</span>
    3479. 

  3479. <a name="l03426"></a>03426 <span class="comment">** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,</span>
    3480. 

  3480. <a name="l03427"></a>03427 <span class="comment">** then the more specific [error codes] are returned directly</span>
    3481. 

  3481. <a name="l03428"></a>03428 <span class="comment">** by sqlite3_step().  The use of the &quot;v2&quot; interface is recommended.</span>
    3482. 

  3482. <a name="l03429"></a>03429 <span class="comment">*/</span>
    3483. 

  3483. <a name="l03430"></a>03430 SQLITE_API <span class="keywordtype">int</span> sqlite3_step(sqlite3_stmt*);
    3484. 

  3484. <a name="l03431"></a>03431 
    3485. 

  3485. <a name="l03432"></a>03432 <span class="comment">/*</span>
    3486. 

  3486. <a name="l03433"></a>03433 <span class="comment">** CAPI3REF: Number of columns in a result set</span>
    3487. 

  3487. <a name="l03434"></a>03434 <span class="comment">**</span>
    3488. 

  3488. <a name="l03435"></a>03435 <span class="comment">** ^The sqlite3_data_count(P) interface returns the number of columns in the</span>
    3489. 

  3489. <a name="l03436"></a>03436 <span class="comment">** current row of the result set of [prepared statement] P.</span>
    3490. 

  3490. <a name="l03437"></a>03437 <span class="comment">** ^If prepared statement P does not have results ready to return</span>
    3491. 

  3491. <a name="l03438"></a>03438 <span class="comment">** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of</span>
    3492. 

  3492. <a name="l03439"></a>03439 <span class="comment">** interfaces) then sqlite3_data_count(P) returns 0.</span>
    3493. 

  3493. <a name="l03440"></a>03440 <span class="comment">** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.</span>
    3494. 

  3494. <a name="l03441"></a>03441 <span class="comment">** ^The sqlite3_data_count(P) routine returns 0 if the previous call to</span>
    3495. 

  3495. <a name="l03442"></a>03442 <span class="comment">** [sqlite3_step](P) returned [SQLITE_DONE].  ^The sqlite3_data_count(P)</span>
    3496. 

  3496. <a name="l03443"></a>03443 <span class="comment">** will return non-zero if previous call to [sqlite3_step](P) returned</span>
    3497. 

  3497. <a name="l03444"></a>03444 <span class="comment">** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum]</span>
    3498. 

  3498. <a name="l03445"></a>03445 <span class="comment">** where it always returns zero since each step of that multi-step</span>
    3499. 

  3499. <a name="l03446"></a>03446 <span class="comment">** pragma returns 0 columns of data.</span>
    3500. 

  3500. <a name="l03447"></a>03447 <span class="comment">**</span>
    3501. 

  3501. <a name="l03448"></a>03448 <span class="comment">** See also: [sqlite3_column_count()]</span>
    3502. 

  3502. <a name="l03449"></a>03449 <span class="comment">*/</span>
    3503. 

  3503. <a name="l03450"></a>03450 SQLITE_API <span class="keywordtype">int</span> sqlite3_data_count(sqlite3_stmt *pStmt);
    3504. 

  3504. <a name="l03451"></a>03451 
    3505. 

  3505. <a name="l03452"></a>03452 <span class="comment">/*</span>
    3506. 

  3506. <a name="l03453"></a>03453 <span class="comment">** CAPI3REF: Fundamental Datatypes</span>
    3507. 

  3507. <a name="l03454"></a>03454 <span class="comment">** KEYWORDS: SQLITE_TEXT</span>
    3508. 

  3508. <a name="l03455"></a>03455 <span class="comment">**</span>
    3509. 

  3509. <a name="l03456"></a>03456 <span class="comment">** ^(Every value in SQLite has one of five fundamental datatypes:</span>
    3510. 

  3510. <a name="l03457"></a>03457 <span class="comment">**</span>
    3511. 

  3511. <a name="l03458"></a>03458 <span class="comment">** &lt;ul&gt;</span>
    3512. 

  3512. <a name="l03459"></a>03459 <span class="comment">** &lt;li&gt; 64-bit signed integer</span>
    3513. 

  3513. <a name="l03460"></a>03460 <span class="comment">** &lt;li&gt; 64-bit IEEE floating point number</span>
    3514. 

  3514. <a name="l03461"></a>03461 <span class="comment">** &lt;li&gt; string</span>
    3515. 

  3515. <a name="l03462"></a>03462 <span class="comment">** &lt;li&gt; BLOB</span>
    3516. 

  3516. <a name="l03463"></a>03463 <span class="comment">** &lt;li&gt; NULL</span>
    3517. 

  3517. <a name="l03464"></a>03464 <span class="comment">** &lt;/ul&gt;)^</span>
    3518. 

  3518. <a name="l03465"></a>03465 <span class="comment">**</span>
    3519. 

  3519. <a name="l03466"></a>03466 <span class="comment">** These constants are codes for each of those types.</span>
    3520. 

  3520. <a name="l03467"></a>03467 <span class="comment">**</span>
    3521. 

  3521. <a name="l03468"></a>03468 <span class="comment">** Note that the SQLITE_TEXT constant was also used in SQLite version 2</span>
    3522. 

  3522. <a name="l03469"></a>03469 <span class="comment">** for a completely different meaning.  Software that links against both</span>
    3523. 

  3523. <a name="l03470"></a>03470 <span class="comment">** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not</span>
    3524. 

  3524. <a name="l03471"></a>03471 <span class="comment">** SQLITE_TEXT.</span>
    3525. 

  3525. <a name="l03472"></a>03472 <span class="comment">*/</span>
    3526. 

  3526. <a name="l03473"></a>03473 <span class="preprocessor">#define SQLITE_INTEGER  1</span>
    3527. 

  3527. <a name="l03474"></a>03474 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_FLOAT    2</span>
    3528. 

  3528. <a name="l03475"></a>03475 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_BLOB     4</span>
    3529. 

  3529. <a name="l03476"></a>03476 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_NULL     5</span>
    3530. 

  3530. <a name="l03477"></a>03477 <span class="preprocessor"></span><span class="preprocessor">#ifdef SQLITE_TEXT</span>
    3531. 

  3531. <a name="l03478"></a>03478 <span class="preprocessor"></span><span class="preprocessor"># undef SQLITE_TEXT</span>
    3532. 

  3532. <a name="l03479"></a>03479 <span class="preprocessor"></span><span class="preprocessor">#else</span>
    3533. 

  3533. <a name="l03480"></a>03480 <span class="preprocessor"></span><span class="preprocessor"># define SQLITE_TEXT     3</span>
    3534. 

  3534. <a name="l03481"></a>03481 <span class="preprocessor"></span><span class="preprocessor">#endif</span>
    3535. 

  3535. <a name="l03482"></a>03482 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE3_TEXT     3</span>
    3536. 

  3536. <a name="l03483"></a>03483 <span class="preprocessor"></span>
    3537. 

  3537. <a name="l03484"></a>03484 <span class="comment">/*</span>
    3538. 

  3538. <a name="l03485"></a>03485 <span class="comment">** CAPI3REF: Result Values From A Query</span>
    3539. 

  3539. <a name="l03486"></a>03486 <span class="comment">** KEYWORDS: {column access functions}</span>
    3540. 

  3540. <a name="l03487"></a>03487 <span class="comment">**</span>
    3541. 

  3541. <a name="l03488"></a>03488 <span class="comment">** These routines form the &quot;result set&quot; interface.</span>
    3542. 

  3542. <a name="l03489"></a>03489 <span class="comment">**</span>
    3543. 

  3543. <a name="l03490"></a>03490 <span class="comment">** ^These routines return information about a single column of the current</span>
    3544. 

  3544. <a name="l03491"></a>03491 <span class="comment">** result row of a query.  ^In every case the first argument is a pointer</span>
    3545. 

  3545. <a name="l03492"></a>03492 <span class="comment">** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]</span>
    3546. 

  3546. <a name="l03493"></a>03493 <span class="comment">** that was returned from [sqlite3_prepare_v2()] or one of its variants)</span>
    3547. 

  3547. <a name="l03494"></a>03494 <span class="comment">** and the second argument is the index of the column for which information</span>
    3548. 

  3548. <a name="l03495"></a>03495 <span class="comment">** should be returned. ^The leftmost column of the result set has the index 0.</span>
    3549. 

  3549. <a name="l03496"></a>03496 <span class="comment">** ^The number of columns in the result can be determined using</span>
    3550. 

  3550. <a name="l03497"></a>03497 <span class="comment">** [sqlite3_column_count()].</span>
    3551. 

  3551. <a name="l03498"></a>03498 <span class="comment">**</span>
    3552. 

  3552. <a name="l03499"></a>03499 <span class="comment">** If the SQL statement does not currently point to a valid row, or if the</span>
    3553. 

  3553. <a name="l03500"></a>03500 <span class="comment">** column index is out of range, the result is undefined.</span>
    3554. 

  3554. <a name="l03501"></a>03501 <span class="comment">** These routines may only be called when the most recent call to</span>
    3555. 

  3555. <a name="l03502"></a>03502 <span class="comment">** [sqlite3_step()] has returned [SQLITE_ROW] and neither</span>
    3556. 

  3556. <a name="l03503"></a>03503 <span class="comment">** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.</span>
    3557. 

  3557. <a name="l03504"></a>03504 <span class="comment">** If any of these routines are called after [sqlite3_reset()] or</span>
    3558. 

  3558. <a name="l03505"></a>03505 <span class="comment">** [sqlite3_finalize()] or after [sqlite3_step()] has returned</span>
    3559. 

  3559. <a name="l03506"></a>03506 <span class="comment">** something other than [SQLITE_ROW], the results are undefined.</span>
    3560. 

  3560. <a name="l03507"></a>03507 <span class="comment">** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]</span>
    3561. 

  3561. <a name="l03508"></a>03508 <span class="comment">** are called from a different thread while any of these routines</span>
    3562. 

  3562. <a name="l03509"></a>03509 <span class="comment">** are pending, then the results are undefined.</span>
    3563. 

  3563. <a name="l03510"></a>03510 <span class="comment">**</span>
    3564. 

  3564. <a name="l03511"></a>03511 <span class="comment">** ^The sqlite3_column_type() routine returns the</span>
    3565. 

  3565. <a name="l03512"></a>03512 <span class="comment">** [SQLITE_INTEGER | datatype code] for the initial data type</span>
    3566. 

  3566. <a name="l03513"></a>03513 <span class="comment">** of the result column.  ^The returned value is one of [SQLITE_INTEGER],</span>
    3567. 

  3567. <a name="l03514"></a>03514 <span class="comment">** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].  The value</span>
    3568. 

  3568. <a name="l03515"></a>03515 <span class="comment">** returned by sqlite3_column_type() is only meaningful if no type</span>
    3569. 

  3569. <a name="l03516"></a>03516 <span class="comment">** conversions have occurred as described below.  After a type conversion,</span>
    3570. 

  3570. <a name="l03517"></a>03517 <span class="comment">** the value returned by sqlite3_column_type() is undefined.  Future</span>
    3571. 

  3571. <a name="l03518"></a>03518 <span class="comment">** versions of SQLite may change the behavior of sqlite3_column_type()</span>
    3572. 

  3572. <a name="l03519"></a>03519 <span class="comment">** following a type conversion.</span>
    3573. 

  3573. <a name="l03520"></a>03520 <span class="comment">**</span>
    3574. 

  3574. <a name="l03521"></a>03521 <span class="comment">** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()</span>
    3575. 

  3575. <a name="l03522"></a>03522 <span class="comment">** routine returns the number of bytes in that BLOB or string.</span>
    3576. 

  3576. <a name="l03523"></a>03523 <span class="comment">** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts</span>
    3577. 

  3577. <a name="l03524"></a>03524 <span class="comment">** the string to UTF-8 and then returns the number of bytes.</span>
    3578. 

  3578. <a name="l03525"></a>03525 <span class="comment">** ^If the result is a numeric value then sqlite3_column_bytes() uses</span>
    3579. 

  3579. <a name="l03526"></a>03526 <span class="comment">** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns</span>
    3580. 

  3580. <a name="l03527"></a>03527 <span class="comment">** the number of bytes in that string.</span>
    3581. 

  3581. <a name="l03528"></a>03528 <span class="comment">** ^If the result is NULL, then sqlite3_column_bytes() returns zero.</span>
    3582. 

  3582. <a name="l03529"></a>03529 <span class="comment">**</span>
    3583. 

  3583. <a name="l03530"></a>03530 <span class="comment">** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()</span>
    3584. 

  3584. <a name="l03531"></a>03531 <span class="comment">** routine returns the number of bytes in that BLOB or string.</span>
    3585. 

  3585. <a name="l03532"></a>03532 <span class="comment">** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts</span>
    3586. 

  3586. <a name="l03533"></a>03533 <span class="comment">** the string to UTF-16 and then returns the number of bytes.</span>
    3587. 

  3587. <a name="l03534"></a>03534 <span class="comment">** ^If the result is a numeric value then sqlite3_column_bytes16() uses</span>
    3588. 

  3588. <a name="l03535"></a>03535 <span class="comment">** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns</span>
    3589. 

  3589. <a name="l03536"></a>03536 <span class="comment">** the number of bytes in that string.</span>
    3590. 

  3590. <a name="l03537"></a>03537 <span class="comment">** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.</span>
    3591. 

  3591. <a name="l03538"></a>03538 <span class="comment">**</span>
    3592. 

  3592. <a name="l03539"></a>03539 <span class="comment">** ^The values returned by [sqlite3_column_bytes()] and </span>
    3593. 

  3593. <a name="l03540"></a>03540 <span class="comment">** [sqlite3_column_bytes16()] do not include the zero terminators at the end</span>
    3594. 

  3594. <a name="l03541"></a>03541 <span class="comment">** of the string.  ^For clarity: the values returned by</span>
    3595. 

  3595. <a name="l03542"></a>03542 <span class="comment">** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of</span>
    3596. 

  3596. <a name="l03543"></a>03543 <span class="comment">** bytes in the string, not the number of characters.</span>
    3597. 

  3597. <a name="l03544"></a>03544 <span class="comment">**</span>
    3598. 

  3598. <a name="l03545"></a>03545 <span class="comment">** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),</span>
    3599. 

  3599. <a name="l03546"></a>03546 <span class="comment">** even empty strings, are always zero-terminated.  ^The return</span>
    3600. 

  3600. <a name="l03547"></a>03547 <span class="comment">** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.</span>
    3601. 

  3601. <a name="l03548"></a>03548 <span class="comment">**</span>
    3602. 

  3602. <a name="l03549"></a>03549 <span class="comment">** ^The object returned by [sqlite3_column_value()] is an</span>
    3603. 

  3603. <a name="l03550"></a>03550 <span class="comment">** [unprotected sqlite3_value] object.  An unprotected sqlite3_value object</span>
    3604. 

  3604. <a name="l03551"></a>03551 <span class="comment">** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].</span>
    3605. 

  3605. <a name="l03552"></a>03552 <span class="comment">** If the [unprotected sqlite3_value] object returned by</span>
    3606. 

  3606. <a name="l03553"></a>03553 <span class="comment">** [sqlite3_column_value()] is used in any other way, including calls</span>
    3607. 

  3607. <a name="l03554"></a>03554 <span class="comment">** to routines like [sqlite3_value_int()], [sqlite3_value_text()],</span>
    3608. 

  3608. <a name="l03555"></a>03555 <span class="comment">** or [sqlite3_value_bytes()], then the behavior is undefined.</span>
    3609. 

  3609. <a name="l03556"></a>03556 <span class="comment">**</span>
    3610. 

  3610. <a name="l03557"></a>03557 <span class="comment">** These routines attempt to convert the value where appropriate.  ^For</span>
    3611. 

  3611. <a name="l03558"></a>03558 <span class="comment">** example, if the internal representation is FLOAT and a text result</span>
    3612. 

  3612. <a name="l03559"></a>03559 <span class="comment">** is requested, [sqlite3_snprintf()] is used internally to perform the</span>
    3613. 

  3613. <a name="l03560"></a>03560 <span class="comment">** conversion automatically.  ^(The following table details the conversions</span>
    3614. 

  3614. <a name="l03561"></a>03561 <span class="comment">** that are applied:</span>
    3615. 

  3615. <a name="l03562"></a>03562 <span class="comment">**</span>
    3616. 

  3616. <a name="l03563"></a>03563 <span class="comment">** &lt;blockquote&gt;</span>
    3617. 

  3617. <a name="l03564"></a>03564 <span class="comment">** &lt;table border=&quot;1&quot;&gt;</span>
    3618. 

  3618. <a name="l03565"></a>03565 <span class="comment">** &lt;tr&gt;&lt;th&gt; Internal&lt;br&gt;Type &lt;th&gt; Requested&lt;br&gt;Type &lt;th&gt;  Conversion</span>
    3619. 

  3619. <a name="l03566"></a>03566 <span class="comment">**</span>
    3620. 

  3620. <a name="l03567"></a>03567 <span class="comment">** &lt;tr&gt;&lt;td&gt;  NULL    &lt;td&gt; INTEGER   &lt;td&gt; Result is 0</span>
    3621. 

  3621. <a name="l03568"></a>03568 <span class="comment">** &lt;tr&gt;&lt;td&gt;  NULL    &lt;td&gt;  FLOAT    &lt;td&gt; Result is 0.0</span>
    3622. 

  3622. <a name="l03569"></a>03569 <span class="comment">** &lt;tr&gt;&lt;td&gt;  NULL    &lt;td&gt;   TEXT    &lt;td&gt; Result is NULL pointer</span>
    3623. 

  3623. <a name="l03570"></a>03570 <span class="comment">** &lt;tr&gt;&lt;td&gt;  NULL    &lt;td&gt;   BLOB    &lt;td&gt; Result is NULL pointer</span>
    3624. 

  3624. <a name="l03571"></a>03571 <span class="comment">** &lt;tr&gt;&lt;td&gt; INTEGER  &lt;td&gt;  FLOAT    &lt;td&gt; Convert from integer to float</span>
    3625. 

  3625. <a name="l03572"></a>03572 <span class="comment">** &lt;tr&gt;&lt;td&gt; INTEGER  &lt;td&gt;   TEXT    &lt;td&gt; ASCII rendering of the integer</span>
    3626. 

  3626. <a name="l03573"></a>03573 <span class="comment">** &lt;tr&gt;&lt;td&gt; INTEGER  &lt;td&gt;   BLOB    &lt;td&gt; Same as INTEGER-&gt;TEXT</span>
    3627. 

  3627. <a name="l03574"></a>03574 <span class="comment">** &lt;tr&gt;&lt;td&gt;  FLOAT   &lt;td&gt; INTEGER   &lt;td&gt; Convert from float to integer</span>
    3628. 

  3628. <a name="l03575"></a>03575 <span class="comment">** &lt;tr&gt;&lt;td&gt;  FLOAT   &lt;td&gt;   TEXT    &lt;td&gt; ASCII rendering of the float</span>
    3629. 

  3629. <a name="l03576"></a>03576 <span class="comment">** &lt;tr&gt;&lt;td&gt;  FLOAT   &lt;td&gt;   BLOB    &lt;td&gt; Same as FLOAT-&gt;TEXT</span>
    3630. 

  3630. <a name="l03577"></a>03577 <span class="comment">** &lt;tr&gt;&lt;td&gt;  TEXT    &lt;td&gt; INTEGER   &lt;td&gt; Use atoi()</span>
    3631. 

  3631. <a name="l03578"></a>03578 <span class="comment">** &lt;tr&gt;&lt;td&gt;  TEXT    &lt;td&gt;  FLOAT    &lt;td&gt; Use atof()</span>
    3632. 

  3632. <a name="l03579"></a>03579 <span class="comment">** &lt;tr&gt;&lt;td&gt;  TEXT    &lt;td&gt;   BLOB    &lt;td&gt; No change</span>
    3633. 

  3633. <a name="l03580"></a>03580 <span class="comment">** &lt;tr&gt;&lt;td&gt;  BLOB    &lt;td&gt; INTEGER   &lt;td&gt; Convert to TEXT then use atoi()</span>
    3634. 

  3634. <a name="l03581"></a>03581 <span class="comment">** &lt;tr&gt;&lt;td&gt;  BLOB    &lt;td&gt;  FLOAT    &lt;td&gt; Convert to TEXT then use atof()</span>
    3635. 

  3635. <a name="l03582"></a>03582 <span class="comment">** &lt;tr&gt;&lt;td&gt;  BLOB    &lt;td&gt;   TEXT    &lt;td&gt; Add a zero terminator if needed</span>
    3636. 

  3636. <a name="l03583"></a>03583 <span class="comment">** &lt;/table&gt;</span>
    3637. 

  3637. <a name="l03584"></a>03584 <span class="comment">** &lt;/blockquote&gt;)^</span>
    3638. 

  3638. <a name="l03585"></a>03585 <span class="comment">**</span>
    3639. 

  3639. <a name="l03586"></a>03586 <span class="comment">** The table above makes reference to standard C library functions atoi()</span>
    3640. 

  3640. <a name="l03587"></a>03587 <span class="comment">** and atof().  SQLite does not really use these functions.  It has its</span>
    3641. 

  3641. <a name="l03588"></a>03588 <span class="comment">** own equivalent internal routines.  The atoi() and atof() names are</span>
    3642. 

  3642. <a name="l03589"></a>03589 <span class="comment">** used in the table for brevity and because they are familiar to most</span>
    3643. 

  3643. <a name="l03590"></a>03590 <span class="comment">** C programmers.</span>
    3644. 

  3644. <a name="l03591"></a>03591 <span class="comment">**</span>
    3645. 

  3645. <a name="l03592"></a>03592 <span class="comment">** Note that when type conversions occur, pointers returned by prior</span>
    3646. 

  3646. <a name="l03593"></a>03593 <span class="comment">** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or</span>
    3647. 

  3647. <a name="l03594"></a>03594 <span class="comment">** sqlite3_column_text16() may be invalidated.</span>
    3648. 

  3648. <a name="l03595"></a>03595 <span class="comment">** Type conversions and pointer invalidations might occur</span>
    3649. 

  3649. <a name="l03596"></a>03596 <span class="comment">** in the following cases:</span>
    3650. 

  3650. <a name="l03597"></a>03597 <span class="comment">**</span>
    3651. 

  3651. <a name="l03598"></a>03598 <span class="comment">** &lt;ul&gt;</span>
    3652. 

  3652. <a name="l03599"></a>03599 <span class="comment">** &lt;li&gt; The initial content is a BLOB and sqlite3_column_text() or</span>
    3653. 

  3653. <a name="l03600"></a>03600 <span class="comment">**      sqlite3_column_text16() is called.  A zero-terminator might</span>
    3654. 

  3654. <a name="l03601"></a>03601 <span class="comment">**      need to be added to the string.&lt;/li&gt;</span>
    3655. 

  3655. <a name="l03602"></a>03602 <span class="comment">** &lt;li&gt; The initial content is UTF-8 text and sqlite3_column_bytes16() or</span>
    3656. 

  3656. <a name="l03603"></a>03603 <span class="comment">**      sqlite3_column_text16() is called.  The content must be converted</span>
    3657. 

  3657. <a name="l03604"></a>03604 <span class="comment">**      to UTF-16.&lt;/li&gt;</span>
    3658. 

  3658. <a name="l03605"></a>03605 <span class="comment">** &lt;li&gt; The initial content is UTF-16 text and sqlite3_column_bytes() or</span>
    3659. 

  3659. <a name="l03606"></a>03606 <span class="comment">**      sqlite3_column_text() is called.  The content must be converted</span>
    3660. 

  3660. <a name="l03607"></a>03607 <span class="comment">**      to UTF-8.&lt;/li&gt;</span>
    3661. 

  3661. <a name="l03608"></a>03608 <span class="comment">** &lt;/ul&gt;</span>
    3662. 

  3662. <a name="l03609"></a>03609 <span class="comment">**</span>
    3663. 

  3663. <a name="l03610"></a>03610 <span class="comment">** ^Conversions between UTF-16be and UTF-16le are always done in place and do</span>
    3664. 

  3664. <a name="l03611"></a>03611 <span class="comment">** not invalidate a prior pointer, though of course the content of the buffer</span>
    3665. 

  3665. <a name="l03612"></a>03612 <span class="comment">** that the prior pointer references will have been modified.  Other kinds</span>
    3666. 

  3666. <a name="l03613"></a>03613 <span class="comment">** of conversion are done in place when it is possible, but sometimes they</span>
    3667. 

  3667. <a name="l03614"></a>03614 <span class="comment">** are not possible and in those cases prior pointers are invalidated.</span>
    3668. 

  3668. <a name="l03615"></a>03615 <span class="comment">**</span>
    3669. 

  3669. <a name="l03616"></a>03616 <span class="comment">** The safest and easiest to remember policy is to invoke these routines</span>
    3670. 

  3670. <a name="l03617"></a>03617 <span class="comment">** in one of the following ways:</span>
    3671. 

  3671. <a name="l03618"></a>03618 <span class="comment">**</span>
    3672. 

  3672. <a name="l03619"></a>03619 <span class="comment">** &lt;ul&gt;</span>
    3673. 

  3673. <a name="l03620"></a>03620 <span class="comment">**  &lt;li&gt;sqlite3_column_text() followed by sqlite3_column_bytes()&lt;/li&gt;</span>
    3674. 

  3674. <a name="l03621"></a>03621 <span class="comment">**  &lt;li&gt;sqlite3_column_blob() followed by sqlite3_column_bytes()&lt;/li&gt;</span>
    3675. 

  3675. <a name="l03622"></a>03622 <span class="comment">**  &lt;li&gt;sqlite3_column_text16() followed by sqlite3_column_bytes16()&lt;/li&gt;</span>
    3676. 

  3676. <a name="l03623"></a>03623 <span class="comment">** &lt;/ul&gt;</span>
    3677. 

  3677. <a name="l03624"></a>03624 <span class="comment">**</span>
    3678. 

  3678. <a name="l03625"></a>03625 <span class="comment">** In other words, you should call sqlite3_column_text(),</span>
    3679. 

  3679. <a name="l03626"></a>03626 <span class="comment">** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result</span>
    3680. 

  3680. <a name="l03627"></a>03627 <span class="comment">** into the desired format, then invoke sqlite3_column_bytes() or</span>
    3681. 

  3681. <a name="l03628"></a>03628 <span class="comment">** sqlite3_column_bytes16() to find the size of the result.  Do not mix calls</span>
    3682. 

  3682. <a name="l03629"></a>03629 <span class="comment">** to sqlite3_column_text() or sqlite3_column_blob() with calls to</span>
    3683. 

  3683. <a name="l03630"></a>03630 <span class="comment">** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()</span>
    3684. 

  3684. <a name="l03631"></a>03631 <span class="comment">** with calls to sqlite3_column_bytes().</span>
    3685. 

  3685. <a name="l03632"></a>03632 <span class="comment">**</span>
    3686. 

  3686. <a name="l03633"></a>03633 <span class="comment">** ^The pointers returned are valid until a type conversion occurs as</span>
    3687. 

  3687. <a name="l03634"></a>03634 <span class="comment">** described above, or until [sqlite3_step()] or [sqlite3_reset()] or</span>
    3688. 

  3688. <a name="l03635"></a>03635 <span class="comment">** [sqlite3_finalize()] is called.  ^The memory space used to hold strings</span>
    3689. 

  3689. <a name="l03636"></a>03636 <span class="comment">** and BLOBs is freed automatically.  Do &lt;b&gt;not&lt;/b&gt; pass the pointers returned</span>
    3690. 

  3690. <a name="l03637"></a>03637 <span class="comment">** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into</span>
    3691. 

  3691. <a name="l03638"></a>03638 <span class="comment">** [sqlite3_free()].</span>
    3692. 

  3692. <a name="l03639"></a>03639 <span class="comment">**</span>
    3693. 

  3693. <a name="l03640"></a>03640 <span class="comment">** ^(If a memory allocation error occurs during the evaluation of any</span>
    3694. 

  3694. <a name="l03641"></a>03641 <span class="comment">** of these routines, a default value is returned.  The default value</span>
    3695. 

  3695. <a name="l03642"></a>03642 <span class="comment">** is either the integer 0, the floating point number 0.0, or a NULL</span>
    3696. 

  3696. <a name="l03643"></a>03643 <span class="comment">** pointer.  Subsequent calls to [sqlite3_errcode()] will return</span>
    3697. 

  3697. <a name="l03644"></a>03644 <span class="comment">** [SQLITE_NOMEM].)^</span>
    3698. 

  3698. <a name="l03645"></a>03645 <span class="comment">*/</span>
    3699. 

  3699. <a name="l03646"></a>03646 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">void</span> *sqlite3_column_blob(sqlite3_stmt*, <span class="keywordtype">int</span> iCol);
    3700. 

  3700. <a name="l03647"></a>03647 SQLITE_API <span class="keywordtype">int</span> sqlite3_column_bytes(sqlite3_stmt*, <span class="keywordtype">int</span> iCol);
    3701. 

  3701. <a name="l03648"></a>03648 SQLITE_API <span class="keywordtype">int</span> sqlite3_column_bytes16(sqlite3_stmt*, <span class="keywordtype">int</span> iCol);
    3702. 

  3702. <a name="l03649"></a>03649 SQLITE_API <span class="keywordtype">double</span> sqlite3_column_double(sqlite3_stmt*, <span class="keywordtype">int</span> iCol);
    3703. 

  3703. <a name="l03650"></a>03650 SQLITE_API <span class="keywordtype">int</span> sqlite3_column_int(sqlite3_stmt*, <span class="keywordtype">int</span> iCol);
    3704. 

  3704. <a name="l03651"></a>03651 SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, <span class="keywordtype">int</span> iCol);
    3705. 

  3705. <a name="l03652"></a>03652 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> *sqlite3_column_text(sqlite3_stmt*, <span class="keywordtype">int</span> iCol);
    3706. 

  3706. <a name="l03653"></a>03653 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">void</span> *sqlite3_column_text16(sqlite3_stmt*, <span class="keywordtype">int</span> iCol);
    3707. 

  3707. <a name="l03654"></a>03654 SQLITE_API <span class="keywordtype">int</span> sqlite3_column_type(sqlite3_stmt*, <span class="keywordtype">int</span> iCol);
    3708. 

  3708. <a name="l03655"></a>03655 SQLITE_API <a class="code" href="structMem.html">sqlite3_value</a> *sqlite3_column_value(sqlite3_stmt*, <span class="keywordtype">int</span> iCol);
    3709. 

  3709. <a name="l03656"></a>03656 
    3710. 

  3710. <a name="l03657"></a>03657 <span class="comment">/*</span>
    3711. 

  3711. <a name="l03658"></a>03658 <span class="comment">** CAPI3REF: Destroy A Prepared Statement Object</span>
    3712. 

  3712. <a name="l03659"></a>03659 <span class="comment">**</span>
    3713. 

  3713. <a name="l03660"></a>03660 <span class="comment">** ^The sqlite3_finalize() function is called to delete a [prepared statement].</span>
    3714. 

  3714. <a name="l03661"></a>03661 <span class="comment">** ^If the most recent evaluation of the statement encountered no errors</span>
    3715. 

  3715. <a name="l03662"></a>03662 <span class="comment">** or if the statement is never been evaluated, then sqlite3_finalize() returns</span>
    3716. 

  3716. <a name="l03663"></a>03663 <span class="comment">** SQLITE_OK.  ^If the most recent evaluation of statement S failed, then</span>
    3717. 

  3717. <a name="l03664"></a>03664 <span class="comment">** sqlite3_finalize(S) returns the appropriate [error code] or</span>
    3718. 

  3718. <a name="l03665"></a>03665 <span class="comment">** [extended error code].</span>
    3719. 

  3719. <a name="l03666"></a>03666 <span class="comment">**</span>
    3720. 

  3720. <a name="l03667"></a>03667 <span class="comment">** ^The sqlite3_finalize(S) routine can be called at any point during</span>
    3721. 

  3721. <a name="l03668"></a>03668 <span class="comment">** the life cycle of [prepared statement] S:</span>
    3722. 

  3722. <a name="l03669"></a>03669 <span class="comment">** before statement S is ever evaluated, after</span>
    3723. 

  3723. <a name="l03670"></a>03670 <span class="comment">** one or more calls to [sqlite3_reset()], or after any call</span>
    3724. 

  3724. <a name="l03671"></a>03671 <span class="comment">** to [sqlite3_step()] regardless of whether or not the statement has</span>
    3725. 

  3725. <a name="l03672"></a>03672 <span class="comment">** completed execution.</span>
    3726. 

  3726. <a name="l03673"></a>03673 <span class="comment">**</span>
    3727. 

  3727. <a name="l03674"></a>03674 <span class="comment">** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.</span>
    3728. 

  3728. <a name="l03675"></a>03675 <span class="comment">**</span>
    3729. 

  3729. <a name="l03676"></a>03676 <span class="comment">** The application must finalize every [prepared statement] in order to avoid</span>
    3730. 

  3730. <a name="l03677"></a>03677 <span class="comment">** resource leaks.  It is a grievous error for the application to try to use</span>
    3731. 

  3731. <a name="l03678"></a>03678 <span class="comment">** a prepared statement after it has been finalized.  Any use of a prepared</span>
    3732. 

  3732. <a name="l03679"></a>03679 <span class="comment">** statement after it has been finalized can result in undefined and</span>
    3733. 

  3733. <a name="l03680"></a>03680 <span class="comment">** undesirable behavior such as segfaults and heap corruption.</span>
    3734. 

  3734. <a name="l03681"></a>03681 <span class="comment">*/</span>
    3735. 

  3735. <a name="l03682"></a>03682 SQLITE_API <span class="keywordtype">int</span> sqlite3_finalize(sqlite3_stmt *pStmt);
    3736. 

  3736. <a name="l03683"></a>03683 
    3737. 

  3737. <a name="l03684"></a>03684 <span class="comment">/*</span>
    3738. 

  3738. <a name="l03685"></a>03685 <span class="comment">** CAPI3REF: Reset A Prepared Statement Object</span>
    3739. 

  3739. <a name="l03686"></a>03686 <span class="comment">**</span>
    3740. 

  3740. <a name="l03687"></a>03687 <span class="comment">** The sqlite3_reset() function is called to reset a [prepared statement]</span>
    3741. 

  3741. <a name="l03688"></a>03688 <span class="comment">** object back to its initial state, ready to be re-executed.</span>
    3742. 

  3742. <a name="l03689"></a>03689 <span class="comment">** ^Any SQL statement variables that had values bound to them using</span>
    3743. 

  3743. <a name="l03690"></a>03690 <span class="comment">** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.</span>
    3744. 

  3744. <a name="l03691"></a>03691 <span class="comment">** Use [sqlite3_clear_bindings()] to reset the bindings.</span>
    3745. 

  3745. <a name="l03692"></a>03692 <span class="comment">**</span>
    3746. 

  3746. <a name="l03693"></a>03693 <span class="comment">** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S</span>
    3747. 

  3747. <a name="l03694"></a>03694 <span class="comment">** back to the beginning of its program.</span>
    3748. 

  3748. <a name="l03695"></a>03695 <span class="comment">**</span>
    3749. 

  3749. <a name="l03696"></a>03696 <span class="comment">** ^If the most recent call to [sqlite3_step(S)] for the</span>
    3750. 

  3750. <a name="l03697"></a>03697 <span class="comment">** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],</span>
    3751. 

  3751. <a name="l03698"></a>03698 <span class="comment">** or if [sqlite3_step(S)] has never before been called on S,</span>
    3752. 

  3752. <a name="l03699"></a>03699 <span class="comment">** then [sqlite3_reset(S)] returns [SQLITE_OK].</span>
    3753. 

  3753. <a name="l03700"></a>03700 <span class="comment">**</span>
    3754. 

  3754. <a name="l03701"></a>03701 <span class="comment">** ^If the most recent call to [sqlite3_step(S)] for the</span>
    3755. 

  3755. <a name="l03702"></a>03702 <span class="comment">** [prepared statement] S indicated an error, then</span>
    3756. 

  3756. <a name="l03703"></a>03703 <span class="comment">** [sqlite3_reset(S)] returns an appropriate [error code].</span>
    3757. 

  3757. <a name="l03704"></a>03704 <span class="comment">**</span>
    3758. 

  3758. <a name="l03705"></a>03705 <span class="comment">** ^The [sqlite3_reset(S)] interface does not change the values</span>
    3759. 

  3759. <a name="l03706"></a>03706 <span class="comment">** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.</span>
    3760. 

  3760. <a name="l03707"></a>03707 <span class="comment">*/</span>
    3761. 

  3761. <a name="l03708"></a>03708 SQLITE_API <span class="keywordtype">int</span> sqlite3_reset(sqlite3_stmt *pStmt);
    3762. 

  3762. <a name="l03709"></a>03709 
    3763. 

  3763. <a name="l03710"></a>03710 <span class="comment">/*</span>
    3764. 

  3764. <a name="l03711"></a>03711 <span class="comment">** CAPI3REF: Create Or Redefine SQL Functions</span>
    3765. 

  3765. <a name="l03712"></a>03712 <span class="comment">** KEYWORDS: {function creation routines}</span>
    3766. 

  3766. <a name="l03713"></a>03713 <span class="comment">** KEYWORDS: {application-defined SQL function}</span>
    3767. 

  3767. <a name="l03714"></a>03714 <span class="comment">** KEYWORDS: {application-defined SQL functions}</span>
    3768. 

  3768. <a name="l03715"></a>03715 <span class="comment">**</span>
    3769. 

  3769. <a name="l03716"></a>03716 <span class="comment">** ^These functions (collectively known as &quot;function creation routines&quot;)</span>
    3770. 

  3770. <a name="l03717"></a>03717 <span class="comment">** are used to add SQL functions or aggregates or to redefine the behavior</span>
    3771. 

  3771. <a name="l03718"></a>03718 <span class="comment">** of existing SQL functions or aggregates.  The only differences between</span>
    3772. 

  3772. <a name="l03719"></a>03719 <span class="comment">** these routines are the text encoding expected for</span>
    3773. 

  3773. <a name="l03720"></a>03720 <span class="comment">** the second parameter (the name of the function being created)</span>
    3774. 

  3774. <a name="l03721"></a>03721 <span class="comment">** and the presence or absence of a destructor callback for</span>
    3775. 

  3775. <a name="l03722"></a>03722 <span class="comment">** the application data pointer.</span>
    3776. 

  3776. <a name="l03723"></a>03723 <span class="comment">**</span>
    3777. 

  3777. <a name="l03724"></a>03724 <span class="comment">** ^The first parameter is the [database connection] to which the SQL</span>
    3778. 

  3778. <a name="l03725"></a>03725 <span class="comment">** function is to be added.  ^If an application uses more than one database</span>
    3779. 

  3779. <a name="l03726"></a>03726 <span class="comment">** connection then application-defined SQL functions must be added</span>
    3780. 

  3780. <a name="l03727"></a>03727 <span class="comment">** to each database connection separately.</span>
    3781. 

  3781. <a name="l03728"></a>03728 <span class="comment">**</span>
    3782. 

  3782. <a name="l03729"></a>03729 <span class="comment">** ^The second parameter is the name of the SQL function to be created or</span>
    3783. 

  3783. <a name="l03730"></a>03730 <span class="comment">** redefined.  ^The length of the name is limited to 255 bytes in a UTF-8</span>
    3784. 

  3784. <a name="l03731"></a>03731 <span class="comment">** representation, exclusive of the zero-terminator.  ^Note that the name</span>
    3785. 

  3785. <a name="l03732"></a>03732 <span class="comment">** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.  </span>
    3786. 

  3786. <a name="l03733"></a>03733 <span class="comment">** ^Any attempt to create a function with a longer name</span>
    3787. 

  3787. <a name="l03734"></a>03734 <span class="comment">** will result in [SQLITE_MISUSE] being returned.</span>
    3788. 

  3788. <a name="l03735"></a>03735 <span class="comment">**</span>
    3789. 

  3789. <a name="l03736"></a>03736 <span class="comment">** ^The third parameter (nArg)</span>
    3790. 

  3790. <a name="l03737"></a>03737 <span class="comment">** is the number of arguments that the SQL function or</span>
    3791. 

  3791. <a name="l03738"></a>03738 <span class="comment">** aggregate takes. ^If this parameter is -1, then the SQL function or</span>
    3792. 

  3792. <a name="l03739"></a>03739 <span class="comment">** aggregate may take any number of arguments between 0 and the limit</span>
    3793. 

  3793. <a name="l03740"></a>03740 <span class="comment">** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]).  If the third</span>
    3794. 

  3794. <a name="l03741"></a>03741 <span class="comment">** parameter is less than -1 or greater than 127 then the behavior is</span>
    3795. 

  3795. <a name="l03742"></a>03742 <span class="comment">** undefined.</span>
    3796. 

  3796. <a name="l03743"></a>03743 <span class="comment">**</span>
    3797. 

  3797. <a name="l03744"></a>03744 <span class="comment">** ^The fourth parameter, eTextRep, specifies what</span>
    3798. 

  3798. <a name="l03745"></a>03745 <span class="comment">** [SQLITE_UTF8 | text encoding] this SQL function prefers for</span>
    3799. 

  3799. <a name="l03746"></a>03746 <span class="comment">** its parameters.  Every SQL function implementation must be able to work</span>
    3800. 

  3800. <a name="l03747"></a>03747 <span class="comment">** with UTF-8, UTF-16le, or UTF-16be.  But some implementations may be</span>
    3801. 

  3801. <a name="l03748"></a>03748 <span class="comment">** more efficient with one encoding than another.  ^An application may</span>
    3802. 

  3802. <a name="l03749"></a>03749 <span class="comment">** invoke sqlite3_create_function() or sqlite3_create_function16() multiple</span>
    3803. 

  3803. <a name="l03750"></a>03750 <span class="comment">** times with the same function but with different values of eTextRep.</span>
    3804. 

  3804. <a name="l03751"></a>03751 <span class="comment">** ^When multiple implementations of the same function are available, SQLite</span>
    3805. 

  3805. <a name="l03752"></a>03752 <span class="comment">** will pick the one that involves the least amount of data conversion.</span>
    3806. 

  3806. <a name="l03753"></a>03753 <span class="comment">** If there is only a single implementation which does not care what text</span>
    3807. 

  3807. <a name="l03754"></a>03754 <span class="comment">** encoding is used, then the fourth argument should be [SQLITE_ANY].</span>
    3808. 

  3808. <a name="l03755"></a>03755 <span class="comment">**</span>
    3809. 

  3809. <a name="l03756"></a>03756 <span class="comment">** ^(The fifth parameter is an arbitrary pointer.  The implementation of the</span>
    3810. 

  3810. <a name="l03757"></a>03757 <span class="comment">** function can gain access to this pointer using [sqlite3_user_data()].)^</span>
    3811. 

  3811. <a name="l03758"></a>03758 <span class="comment">**</span>
    3812. 

  3812. <a name="l03759"></a>03759 <span class="comment">** ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are</span>
    3813. 

  3813. <a name="l03760"></a>03760 <span class="comment">** pointers to C-language functions that implement the SQL function or</span>
    3814. 

  3814. <a name="l03761"></a>03761 <span class="comment">** aggregate. ^A scalar SQL function requires an implementation of the xFunc</span>
    3815. 

  3815. <a name="l03762"></a>03762 <span class="comment">** callback only; NULL pointers must be passed as the xStep and xFinal</span>
    3816. 

  3816. <a name="l03763"></a>03763 <span class="comment">** parameters. ^An aggregate SQL function requires an implementation of xStep</span>
    3817. 

  3817. <a name="l03764"></a>03764 <span class="comment">** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing</span>
    3818. 

  3818. <a name="l03765"></a>03765 <span class="comment">** SQL function or aggregate, pass NULL pointers for all three function</span>
    3819. 

  3819. <a name="l03766"></a>03766 <span class="comment">** callbacks.</span>
    3820. 

  3820. <a name="l03767"></a>03767 <span class="comment">**</span>
    3821. 

  3821. <a name="l03768"></a>03768 <span class="comment">** ^(If the ninth parameter to sqlite3_create_function_v2() is not NULL,</span>
    3822. 

  3822. <a name="l03769"></a>03769 <span class="comment">** then it is destructor for the application data pointer. </span>
    3823. 

  3823. <a name="l03770"></a>03770 <span class="comment">** The destructor is invoked when the function is deleted, either by being</span>
    3824. 

  3824. <a name="l03771"></a>03771 <span class="comment">** overloaded or when the database connection closes.)^</span>
    3825. 

  3825. <a name="l03772"></a>03772 <span class="comment">** ^The destructor is also invoked if the call to</span>
    3826. 

  3826. <a name="l03773"></a>03773 <span class="comment">** sqlite3_create_function_v2() fails.</span>
    3827. 

  3827. <a name="l03774"></a>03774 <span class="comment">** ^When the destructor callback of the tenth parameter is invoked, it</span>
    3828. 

  3828. <a name="l03775"></a>03775 <span class="comment">** is passed a single argument which is a copy of the application data </span>
    3829. 

  3829. <a name="l03776"></a>03776 <span class="comment">** pointer which was the fifth parameter to sqlite3_create_function_v2().</span>
    3830. 

  3830. <a name="l03777"></a>03777 <span class="comment">**</span>
    3831. 

  3831. <a name="l03778"></a>03778 <span class="comment">** ^It is permitted to register multiple implementations of the same</span>
    3832. 

  3832. <a name="l03779"></a>03779 <span class="comment">** functions with the same name but with either differing numbers of</span>
    3833. 

  3833. <a name="l03780"></a>03780 <span class="comment">** arguments or differing preferred text encodings.  ^SQLite will use</span>
    3834. 

  3834. <a name="l03781"></a>03781 <span class="comment">** the implementation that most closely matches the way in which the</span>
    3835. 

  3835. <a name="l03782"></a>03782 <span class="comment">** SQL function is used.  ^A function implementation with a non-negative</span>
    3836. 

  3836. <a name="l03783"></a>03783 <span class="comment">** nArg parameter is a better match than a function implementation with</span>
    3837. 

  3837. <a name="l03784"></a>03784 <span class="comment">** a negative nArg.  ^A function where the preferred text encoding</span>
    3838. 

  3838. <a name="l03785"></a>03785 <span class="comment">** matches the database encoding is a better</span>
    3839. 

  3839. <a name="l03786"></a>03786 <span class="comment">** match than a function where the encoding is different.  </span>
    3840. 

  3840. <a name="l03787"></a>03787 <span class="comment">** ^A function where the encoding difference is between UTF16le and UTF16be</span>
    3841. 

  3841. <a name="l03788"></a>03788 <span class="comment">** is a closer match than a function where the encoding difference is</span>
    3842. 

  3842. <a name="l03789"></a>03789 <span class="comment">** between UTF8 and UTF16.</span>
    3843. 

  3843. <a name="l03790"></a>03790 <span class="comment">**</span>
    3844. 

  3844. <a name="l03791"></a>03791 <span class="comment">** ^Built-in functions may be overloaded by new application-defined functions.</span>
    3845. 

  3845. <a name="l03792"></a>03792 <span class="comment">**</span>
    3846. 

  3846. <a name="l03793"></a>03793 <span class="comment">** ^An application-defined function is permitted to call other</span>
    3847. 

  3847. <a name="l03794"></a>03794 <span class="comment">** SQLite interfaces.  However, such calls must not</span>
    3848. 

  3848. <a name="l03795"></a>03795 <span class="comment">** close the database connection nor finalize or reset the prepared</span>
    3849. 

  3849. <a name="l03796"></a>03796 <span class="comment">** statement in which the function is running.</span>
    3850. 

  3850. <a name="l03797"></a>03797 <span class="comment">*/</span>
    3851. 

  3851. <a name="l03798"></a>03798 SQLITE_API <span class="keywordtype">int</span> sqlite3_create_function(
    3852. 

  3852. <a name="l03799"></a>03799   <a class="code" href="structsqlite3.html">sqlite3</a> *db,
    3853. 

  3853. <a name="l03800"></a>03800   <span class="keyword">const</span> <span class="keywordtype">char</span> *zFunctionName,
    3854. 

  3854. <a name="l03801"></a>03801   <span class="keywordtype">int</span> nArg,
    3855. 

  3855. <a name="l03802"></a>03802   <span class="keywordtype">int</span> eTextRep,
    3856. 

  3856. <a name="l03803"></a>03803   <span class="keywordtype">void</span> *pApp,
    3857. 

  3857. <a name="l03804"></a>03804   <span class="keywordtype">void</span> (*xFunc)(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*,<span class="keywordtype">int</span>,<a class="code" href="structMem.html">sqlite3_value</a>**),
    3858. 

  3858. <a name="l03805"></a>03805   <span class="keywordtype">void</span> (*xStep)(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*,<span class="keywordtype">int</span>,<a class="code" href="structMem.html">sqlite3_value</a>**),
    3859. 

  3859. <a name="l03806"></a>03806   <span class="keywordtype">void</span> (*xFinal)(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*)
    3860. 

  3860. <a name="l03807"></a>03807 );
    3861. 

  3861. <a name="l03808"></a>03808 SQLITE_API <span class="keywordtype">int</span> sqlite3_create_function16(
    3862. 

  3862. <a name="l03809"></a>03809   <a class="code" href="structsqlite3.html">sqlite3</a> *db,
    3863. 

  3863. <a name="l03810"></a>03810   <span class="keyword">const</span> <span class="keywordtype">void</span> *zFunctionName,
    3864. 

  3864. <a name="l03811"></a>03811   <span class="keywordtype">int</span> nArg,
    3865. 

  3865. <a name="l03812"></a>03812   <span class="keywordtype">int</span> eTextRep,
    3866. 

  3866. <a name="l03813"></a>03813   <span class="keywordtype">void</span> *pApp,
    3867. 

  3867. <a name="l03814"></a>03814   <span class="keywordtype">void</span> (*xFunc)(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*,<span class="keywordtype">int</span>,<a class="code" href="structMem.html">sqlite3_value</a>**),
    3868. 

  3868. <a name="l03815"></a>03815   <span class="keywordtype">void</span> (*xStep)(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*,<span class="keywordtype">int</span>,<a class="code" href="structMem.html">sqlite3_value</a>**),
    3869. 

  3869. <a name="l03816"></a>03816   <span class="keywordtype">void</span> (*xFinal)(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*)
    3870. 

  3870. <a name="l03817"></a>03817 );
    3871. 

  3871. <a name="l03818"></a>03818 SQLITE_API <span class="keywordtype">int</span> sqlite3_create_function_v2(
    3872. 

  3872. <a name="l03819"></a>03819   <a class="code" href="structsqlite3.html">sqlite3</a> *db,
    3873. 

  3873. <a name="l03820"></a>03820   <span class="keyword">const</span> <span class="keywordtype">char</span> *zFunctionName,
    3874. 

  3874. <a name="l03821"></a>03821   <span class="keywordtype">int</span> nArg,
    3875. 

  3875. <a name="l03822"></a>03822   <span class="keywordtype">int</span> eTextRep,
    3876. 

  3876. <a name="l03823"></a>03823   <span class="keywordtype">void</span> *pApp,
    3877. 

  3877. <a name="l03824"></a>03824   <span class="keywordtype">void</span> (*xFunc)(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*,<span class="keywordtype">int</span>,<a class="code" href="structMem.html">sqlite3_value</a>**),
    3878. 

  3878. <a name="l03825"></a>03825   <span class="keywordtype">void</span> (*xStep)(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*,<span class="keywordtype">int</span>,<a class="code" href="structMem.html">sqlite3_value</a>**),
    3879. 

  3879. <a name="l03826"></a>03826   <span class="keywordtype">void</span> (*xFinal)(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*),
    3880. 

  3880. <a name="l03827"></a>03827   <span class="keywordtype">void</span>(*xDestroy)(<span class="keywordtype">void</span>*)
    3881. 

  3881. <a name="l03828"></a>03828 );
    3882. 

  3882. <a name="l03829"></a>03829 
    3883. 

  3883. <a name="l03830"></a>03830 <span class="comment">/*</span>
    3884. 

  3884. <a name="l03831"></a>03831 <span class="comment">** CAPI3REF: Text Encodings</span>
    3885. 

  3885. <a name="l03832"></a>03832 <span class="comment">**</span>
    3886. 

  3886. <a name="l03833"></a>03833 <span class="comment">** These constant define integer codes that represent the various</span>
    3887. 

  3887. <a name="l03834"></a>03834 <span class="comment">** text encodings supported by SQLite.</span>
    3888. 

  3888. <a name="l03835"></a>03835 <span class="comment">*/</span>
    3889. 

  3889. <a name="l03836"></a>03836 <span class="preprocessor">#define SQLITE_UTF8           1</span>
    3890. 

  3890. <a name="l03837"></a>03837 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_UTF16LE        2</span>
    3891. 

  3891. <a name="l03838"></a>03838 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_UTF16BE        3</span>
    3892. 

  3892. <a name="l03839"></a>03839 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_UTF16          4    </span><span class="comment">/* Use native byte order */</span>
    3893. 

  3893. <a name="l03840"></a>03840 <span class="preprocessor">#define SQLITE_ANY            5    </span><span class="comment">/* sqlite3_create_function only */</span>
    3894. 

  3894. <a name="l03841"></a>03841 <span class="preprocessor">#define SQLITE_UTF16_ALIGNED  8    </span><span class="comment">/* sqlite3_create_collation only */</span>
    3895. 

  3895. <a name="l03842"></a>03842 
    3896. 

  3896. <a name="l03843"></a>03843 <span class="comment">/*</span>
    3897. 

  3897. <a name="l03844"></a>03844 <span class="comment">** CAPI3REF: Deprecated Functions</span>
    3898. 

  3898. <a name="l03845"></a>03845 <span class="comment">** DEPRECATED</span>
    3899. 

  3899. <a name="l03846"></a>03846 <span class="comment">**</span>
    3900. 

  3900. <a name="l03847"></a>03847 <span class="comment">** These functions are [deprecated].  In order to maintain</span>
    3901. 

  3901. <a name="l03848"></a>03848 <span class="comment">** backwards compatibility with older code, these functions continue </span>
    3902. 

  3902. <a name="l03849"></a>03849 <span class="comment">** to be supported.  However, new applications should avoid</span>
    3903. 

  3903. <a name="l03850"></a>03850 <span class="comment">** the use of these functions.  To help encourage people to avoid</span>
    3904. 

  3904. <a name="l03851"></a>03851 <span class="comment">** using these functions, we are not going to tell you what they do.</span>
    3905. 

  3905. <a name="l03852"></a>03852 <span class="comment">*/</span>
    3906. 

  3906. <a name="l03853"></a>03853 <span class="preprocessor">#ifndef SQLITE_OMIT_DEPRECATED</span>
    3907. 

  3907. <a name="l03854"></a>03854 <span class="preprocessor"></span>SQLITE_API SQLITE_DEPRECATED <span class="keywordtype">int</span> sqlite3_aggregate_count(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*);
    3908. 

  3908. <a name="l03855"></a>03855 SQLITE_API SQLITE_DEPRECATED <span class="keywordtype">int</span> sqlite3_expired(sqlite3_stmt*);
    3909. 

  3909. <a name="l03856"></a>03856 SQLITE_API SQLITE_DEPRECATED <span class="keywordtype">int</span> sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
    3910. 

  3910. <a name="l03857"></a>03857 SQLITE_API SQLITE_DEPRECATED <span class="keywordtype">int</span> sqlite3_global_recover(<span class="keywordtype">void</span>);
    3911. 

  3911. <a name="l03858"></a>03858 SQLITE_API SQLITE_DEPRECATED <span class="keywordtype">void</span> sqlite3_thread_cleanup(<span class="keywordtype">void</span>);
    3912. 

  3912. <a name="l03859"></a>03859 SQLITE_API SQLITE_DEPRECATED <span class="keywordtype">int</span> sqlite3_memory_alarm(<span class="keywordtype">void</span>(*)(<span class="keywordtype">void</span>*,sqlite3_int64,<span class="keywordtype">int</span>),<span class="keywordtype">void</span>*,sqlite3_int64);
    3913. 

  3913. <a name="l03860"></a>03860 <span class="preprocessor">#endif</span>
    3914. 

  3914. <a name="l03861"></a>03861 <span class="preprocessor"></span>
    3915. 

  3915. <a name="l03862"></a>03862 <span class="comment">/*</span>
    3916. 

  3916. <a name="l03863"></a>03863 <span class="comment">** CAPI3REF: Obtaining SQL Function Parameter Values</span>
    3917. 

  3917. <a name="l03864"></a>03864 <span class="comment">**</span>
    3918. 

  3918. <a name="l03865"></a>03865 <span class="comment">** The C-language implementation of SQL functions and aggregates uses</span>
    3919. 

  3919. <a name="l03866"></a>03866 <span class="comment">** this set of interface routines to access the parameter values on</span>
    3920. 

  3920. <a name="l03867"></a>03867 <span class="comment">** the function or aggregate.</span>
    3921. 

  3921. <a name="l03868"></a>03868 <span class="comment">**</span>
    3922. 

  3922. <a name="l03869"></a>03869 <span class="comment">** The xFunc (for scalar functions) or xStep (for aggregates) parameters</span>
    3923. 

  3923. <a name="l03870"></a>03870 <span class="comment">** to [sqlite3_create_function()] and [sqlite3_create_function16()]</span>
    3924. 

  3924. <a name="l03871"></a>03871 <span class="comment">** define callbacks that implement the SQL functions and aggregates.</span>
    3925. 

  3925. <a name="l03872"></a>03872 <span class="comment">** The 3rd parameter to these callbacks is an array of pointers to</span>
    3926. 

  3926. <a name="l03873"></a>03873 <span class="comment">** [protected sqlite3_value] objects.  There is one [sqlite3_value] object for</span>
    3927. 

  3927. <a name="l03874"></a>03874 <span class="comment">** each parameter to the SQL function.  These routines are used to</span>
    3928. 

  3928. <a name="l03875"></a>03875 <span class="comment">** extract values from the [sqlite3_value] objects.</span>
    3929. 

  3929. <a name="l03876"></a>03876 <span class="comment">**</span>
    3930. 

  3930. <a name="l03877"></a>03877 <span class="comment">** These routines work only with [protected sqlite3_value] objects.</span>
    3931. 

  3931. <a name="l03878"></a>03878 <span class="comment">** Any attempt to use these routines on an [unprotected sqlite3_value]</span>
    3932. 

  3932. <a name="l03879"></a>03879 <span class="comment">** object results in undefined behavior.</span>
    3933. 

  3933. <a name="l03880"></a>03880 <span class="comment">**</span>
    3934. 

  3934. <a name="l03881"></a>03881 <span class="comment">** ^These routines work just like the corresponding [column access functions]</span>
    3935. 

  3935. <a name="l03882"></a>03882 <span class="comment">** except that  these routines take a single [protected sqlite3_value] object</span>
    3936. 

  3936. <a name="l03883"></a>03883 <span class="comment">** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.</span>
    3937. 

  3937. <a name="l03884"></a>03884 <span class="comment">**</span>
    3938. 

  3938. <a name="l03885"></a>03885 <span class="comment">** ^The sqlite3_value_text16() interface extracts a UTF-16 string</span>
    3939. 

  3939. <a name="l03886"></a>03886 <span class="comment">** in the native byte-order of the host machine.  ^The</span>
    3940. 

  3940. <a name="l03887"></a>03887 <span class="comment">** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces</span>
    3941. 

  3941. <a name="l03888"></a>03888 <span class="comment">** extract UTF-16 strings as big-endian and little-endian respectively.</span>
    3942. 

  3942. <a name="l03889"></a>03889 <span class="comment">**</span>
    3943. 

  3943. <a name="l03890"></a>03890 <span class="comment">** ^(The sqlite3_value_numeric_type() interface attempts to apply</span>
    3944. 

  3944. <a name="l03891"></a>03891 <span class="comment">** numeric affinity to the value.  This means that an attempt is</span>
    3945. 

  3945. <a name="l03892"></a>03892 <span class="comment">** made to convert the value to an integer or floating point.  If</span>
    3946. 

  3946. <a name="l03893"></a>03893 <span class="comment">** such a conversion is possible without loss of information (in other</span>
    3947. 

  3947. <a name="l03894"></a>03894 <span class="comment">** words, if the value is a string that looks like a number)</span>
    3948. 

  3948. <a name="l03895"></a>03895 <span class="comment">** then the conversion is performed.  Otherwise no conversion occurs.</span>
    3949. 

  3949. <a name="l03896"></a>03896 <span class="comment">** The [SQLITE_INTEGER | datatype] after conversion is returned.)^</span>
    3950. 

  3950. <a name="l03897"></a>03897 <span class="comment">**</span>
    3951. 

  3951. <a name="l03898"></a>03898 <span class="comment">** Please pay particular attention to the fact that the pointer returned</span>
    3952. 

  3952. <a name="l03899"></a>03899 <span class="comment">** from [sqlite3_value_blob()], [sqlite3_value_text()], or</span>
    3953. 

  3953. <a name="l03900"></a>03900 <span class="comment">** [sqlite3_value_text16()] can be invalidated by a subsequent call to</span>
    3954. 

  3954. <a name="l03901"></a>03901 <span class="comment">** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],</span>
    3955. 

  3955. <a name="l03902"></a>03902 <span class="comment">** or [sqlite3_value_text16()].</span>
    3956. 

  3956. <a name="l03903"></a>03903 <span class="comment">**</span>
    3957. 

  3957. <a name="l03904"></a>03904 <span class="comment">** These routines must be called from the same thread as</span>
    3958. 

  3958. <a name="l03905"></a>03905 <span class="comment">** the SQL function that supplied the [sqlite3_value*] parameters.</span>
    3959. 

  3959. <a name="l03906"></a>03906 <span class="comment">*/</span>
    3960. 

  3960. <a name="l03907"></a>03907 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">void</span> *sqlite3_value_blob(<a class="code" href="structMem.html">sqlite3_value</a>*);
    3961. 

  3961. <a name="l03908"></a>03908 SQLITE_API <span class="keywordtype">int</span> sqlite3_value_bytes(<a class="code" href="structMem.html">sqlite3_value</a>*);
    3962. 

  3962. <a name="l03909"></a>03909 SQLITE_API <span class="keywordtype">int</span> sqlite3_value_bytes16(<a class="code" href="structMem.html">sqlite3_value</a>*);
    3963. 

  3963. <a name="l03910"></a>03910 SQLITE_API <span class="keywordtype">double</span> sqlite3_value_double(<a class="code" href="structMem.html">sqlite3_value</a>*);
    3964. 

  3964. <a name="l03911"></a>03911 SQLITE_API <span class="keywordtype">int</span> sqlite3_value_int(<a class="code" href="structMem.html">sqlite3_value</a>*);
    3965. 

  3965. <a name="l03912"></a>03912 SQLITE_API sqlite3_int64 sqlite3_value_int64(<a class="code" href="structMem.html">sqlite3_value</a>*);
    3966. 

  3966. <a name="l03913"></a>03913 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">char</span> *sqlite3_value_text(<a class="code" href="structMem.html">sqlite3_value</a>*);
    3967. 

  3967. <a name="l03914"></a>03914 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">void</span> *sqlite3_value_text16(<a class="code" href="structMem.html">sqlite3_value</a>*);
    3968. 

  3968. <a name="l03915"></a>03915 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">void</span> *sqlite3_value_text16le(<a class="code" href="structMem.html">sqlite3_value</a>*);
    3969. 

  3969. <a name="l03916"></a>03916 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">void</span> *sqlite3_value_text16be(<a class="code" href="structMem.html">sqlite3_value</a>*);
    3970. 

  3970. <a name="l03917"></a>03917 SQLITE_API <span class="keywordtype">int</span> sqlite3_value_type(<a class="code" href="structMem.html">sqlite3_value</a>*);
    3971. 

  3971. <a name="l03918"></a>03918 SQLITE_API <span class="keywordtype">int</span> sqlite3_value_numeric_type(<a class="code" href="structMem.html">sqlite3_value</a>*);
    3972. 

  3972. <a name="l03919"></a>03919 
    3973. 

  3973. <a name="l03920"></a>03920 <span class="comment">/*</span>
    3974. 

  3974. <a name="l03921"></a>03921 <span class="comment">** CAPI3REF: Obtain Aggregate Function Context</span>
    3975. 

  3975. <a name="l03922"></a>03922 <span class="comment">**</span>
    3976. 

  3976. <a name="l03923"></a>03923 <span class="comment">** Implementations of aggregate SQL functions use this</span>
    3977. 

  3977. <a name="l03924"></a>03924 <span class="comment">** routine to allocate memory for storing their state.</span>
    3978. 

  3978. <a name="l03925"></a>03925 <span class="comment">**</span>
    3979. 

  3979. <a name="l03926"></a>03926 <span class="comment">** ^The first time the sqlite3_aggregate_context(C,N) routine is called </span>
    3980. 

  3980. <a name="l03927"></a>03927 <span class="comment">** for a particular aggregate function, SQLite</span>
    3981. 

  3981. <a name="l03928"></a>03928 <span class="comment">** allocates N of memory, zeroes out that memory, and returns a pointer</span>
    3982. 

  3982. <a name="l03929"></a>03929 <span class="comment">** to the new memory. ^On second and subsequent calls to</span>
    3983. 

  3983. <a name="l03930"></a>03930 <span class="comment">** sqlite3_aggregate_context() for the same aggregate function instance,</span>
    3984. 

  3984. <a name="l03931"></a>03931 <span class="comment">** the same buffer is returned.  Sqlite3_aggregate_context() is normally</span>
    3985. 

  3985. <a name="l03932"></a>03932 <span class="comment">** called once for each invocation of the xStep callback and then one</span>
    3986. 

  3986. <a name="l03933"></a>03933 <span class="comment">** last time when the xFinal callback is invoked.  ^(When no rows match</span>
    3987. 

  3987. <a name="l03934"></a>03934 <span class="comment">** an aggregate query, the xStep() callback of the aggregate function</span>
    3988. 

  3988. <a name="l03935"></a>03935 <span class="comment">** implementation is never called and xFinal() is called exactly once.</span>
    3989. 

  3989. <a name="l03936"></a>03936 <span class="comment">** In those cases, sqlite3_aggregate_context() might be called for the</span>
    3990. 

  3990. <a name="l03937"></a>03937 <span class="comment">** first time from within xFinal().)^</span>
    3991. 

  3991. <a name="l03938"></a>03938 <span class="comment">**</span>
    3992. 

  3992. <a name="l03939"></a>03939 <span class="comment">** ^The sqlite3_aggregate_context(C,N) routine returns a NULL pointer if N is</span>
    3993. 

  3993. <a name="l03940"></a>03940 <span class="comment">** less than or equal to zero or if a memory allocate error occurs.</span>
    3994. 

  3994. <a name="l03941"></a>03941 <span class="comment">**</span>
    3995. 

  3995. <a name="l03942"></a>03942 <span class="comment">** ^(The amount of space allocated by sqlite3_aggregate_context(C,N) is</span>
    3996. 

  3996. <a name="l03943"></a>03943 <span class="comment">** determined by the N parameter on first successful call.  Changing the</span>
    3997. 

  3997. <a name="l03944"></a>03944 <span class="comment">** value of N in subsequent call to sqlite3_aggregate_context() within</span>
    3998. 

  3998. <a name="l03945"></a>03945 <span class="comment">** the same aggregate function instance will not resize the memory</span>
    3999. 

  3999. <a name="l03946"></a>03946 <span class="comment">** allocation.)^</span>
    4000. 

  4000. <a name="l03947"></a>03947 <span class="comment">**</span>
    4001. 

  4001. <a name="l03948"></a>03948 <span class="comment">** ^SQLite automatically frees the memory allocated by </span>
    4002. 

  4002. <a name="l03949"></a>03949 <span class="comment">** sqlite3_aggregate_context() when the aggregate query concludes.</span>
    4003. 

  4003. <a name="l03950"></a>03950 <span class="comment">**</span>
    4004. 

  4004. <a name="l03951"></a>03951 <span class="comment">** The first parameter must be a copy of the</span>
    4005. 

  4005. <a name="l03952"></a>03952 <span class="comment">** [sqlite3_context | SQL function context] that is the first parameter</span>
    4006. 

  4006. <a name="l03953"></a>03953 <span class="comment">** to the xStep or xFinal callback routine that implements the aggregate</span>
    4007. 

  4007. <a name="l03954"></a>03954 <span class="comment">** function.</span>
    4008. 

  4008. <a name="l03955"></a>03955 <span class="comment">**</span>
    4009. 

  4009. <a name="l03956"></a>03956 <span class="comment">** This routine must be called from the same thread in which</span>
    4010. 

  4010. <a name="l03957"></a>03957 <span class="comment">** the aggregate SQL function is running.</span>
    4011. 

  4011. <a name="l03958"></a>03958 <span class="comment">*/</span>
    4012. 

  4012. <a name="l03959"></a>03959 SQLITE_API <span class="keywordtype">void</span> *sqlite3_aggregate_context(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <span class="keywordtype">int</span> nBytes);
    4013. 

  4013. <a name="l03960"></a>03960 
    4014. 

  4014. <a name="l03961"></a>03961 <span class="comment">/*</span>
    4015. 

  4015. <a name="l03962"></a>03962 <span class="comment">** CAPI3REF: User Data For Functions</span>
    4016. 

  4016. <a name="l03963"></a>03963 <span class="comment">**</span>
    4017. 

  4017. <a name="l03964"></a>03964 <span class="comment">** ^The sqlite3_user_data() interface returns a copy of</span>
    4018. 

  4018. <a name="l03965"></a>03965 <span class="comment">** the pointer that was the pUserData parameter (the 5th parameter)</span>
    4019. 

  4019. <a name="l03966"></a>03966 <span class="comment">** of the [sqlite3_create_function()]</span>
    4020. 

  4020. <a name="l03967"></a>03967 <span class="comment">** and [sqlite3_create_function16()] routines that originally</span>
    4021. 

  4021. <a name="l03968"></a>03968 <span class="comment">** registered the application defined function.</span>
    4022. 

  4022. <a name="l03969"></a>03969 <span class="comment">**</span>
    4023. 

  4023. <a name="l03970"></a>03970 <span class="comment">** This routine must be called from the same thread in which</span>
    4024. 

  4024. <a name="l03971"></a>03971 <span class="comment">** the application-defined function is running.</span>
    4025. 

  4025. <a name="l03972"></a>03972 <span class="comment">*/</span>
    4026. 

  4026. <a name="l03973"></a>03973 SQLITE_API <span class="keywordtype">void</span> *sqlite3_user_data(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*);
    4027. 

  4027. <a name="l03974"></a>03974 
    4028. 

  4028. <a name="l03975"></a>03975 <span class="comment">/*</span>
    4029. 

  4029. <a name="l03976"></a>03976 <span class="comment">** CAPI3REF: Database Connection For Functions</span>
    4030. 

  4030. <a name="l03977"></a>03977 <span class="comment">**</span>
    4031. 

  4031. <a name="l03978"></a>03978 <span class="comment">** ^The sqlite3_context_db_handle() interface returns a copy of</span>
    4032. 

  4032. <a name="l03979"></a>03979 <span class="comment">** the pointer to the [database connection] (the 1st parameter)</span>
    4033. 

  4033. <a name="l03980"></a>03980 <span class="comment">** of the [sqlite3_create_function()]</span>
    4034. 

  4034. <a name="l03981"></a>03981 <span class="comment">** and [sqlite3_create_function16()] routines that originally</span>
    4035. 

  4035. <a name="l03982"></a>03982 <span class="comment">** registered the application defined function.</span>
    4036. 

  4036. <a name="l03983"></a>03983 <span class="comment">*/</span>
    4037. 

  4037. <a name="l03984"></a>03984 SQLITE_API <a class="code" href="structsqlite3.html">sqlite3</a> *sqlite3_context_db_handle(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*);
    4038. 

  4038. <a name="l03985"></a>03985 
    4039. 

  4039. <a name="l03986"></a>03986 <span class="comment">/*</span>
    4040. 

  4040. <a name="l03987"></a>03987 <span class="comment">** CAPI3REF: Function Auxiliary Data</span>
    4041. 

  4041. <a name="l03988"></a>03988 <span class="comment">**</span>
    4042. 

  4042. <a name="l03989"></a>03989 <span class="comment">** The following two functions may be used by scalar SQL functions to</span>
    4043. 

  4043. <a name="l03990"></a>03990 <span class="comment">** associate metadata with argument values. If the same value is passed to</span>
    4044. 

  4044. <a name="l03991"></a>03991 <span class="comment">** multiple invocations of the same SQL function during query execution, under</span>
    4045. 

  4045. <a name="l03992"></a>03992 <span class="comment">** some circumstances the associated metadata may be preserved. This may</span>
    4046. 

  4046. <a name="l03993"></a>03993 <span class="comment">** be used, for example, to add a regular-expression matching scalar</span>
    4047. 

  4047. <a name="l03994"></a>03994 <span class="comment">** function. The compiled version of the regular expression is stored as</span>
    4048. 

  4048. <a name="l03995"></a>03995 <span class="comment">** metadata associated with the SQL value passed as the regular expression</span>
    4049. 

  4049. <a name="l03996"></a>03996 <span class="comment">** pattern.  The compiled regular expression can be reused on multiple</span>
    4050. 

  4050. <a name="l03997"></a>03997 <span class="comment">** invocations of the same function so that the original pattern string</span>
    4051. 

  4051. <a name="l03998"></a>03998 <span class="comment">** does not need to be recompiled on each invocation.</span>
    4052. 

  4052. <a name="l03999"></a>03999 <span class="comment">**</span>
    4053. 

  4053. <a name="l04000"></a>04000 <span class="comment">** ^The sqlite3_get_auxdata() interface returns a pointer to the metadata</span>
    4054. 

  4054. <a name="l04001"></a>04001 <span class="comment">** associated by the sqlite3_set_auxdata() function with the Nth argument</span>
    4055. 

  4055. <a name="l04002"></a>04002 <span class="comment">** value to the application-defined function. ^If no metadata has been ever</span>
    4056. 

  4056. <a name="l04003"></a>04003 <span class="comment">** been set for the Nth argument of the function, or if the corresponding</span>
    4057. 

  4057. <a name="l04004"></a>04004 <span class="comment">** function parameter has changed since the meta-data was set,</span>
    4058. 

  4058. <a name="l04005"></a>04005 <span class="comment">** then sqlite3_get_auxdata() returns a NULL pointer.</span>
    4059. 

  4059. <a name="l04006"></a>04006 <span class="comment">**</span>
    4060. 

  4060. <a name="l04007"></a>04007 <span class="comment">** ^The sqlite3_set_auxdata() interface saves the metadata</span>
    4061. 

  4061. <a name="l04008"></a>04008 <span class="comment">** pointed to by its 3rd parameter as the metadata for the N-th</span>
    4062. 

  4062. <a name="l04009"></a>04009 <span class="comment">** argument of the application-defined function.  Subsequent</span>
    4063. 

  4063. <a name="l04010"></a>04010 <span class="comment">** calls to sqlite3_get_auxdata() might return this data, if it has</span>
    4064. 

  4064. <a name="l04011"></a>04011 <span class="comment">** not been destroyed.</span>
    4065. 

  4065. <a name="l04012"></a>04012 <span class="comment">** ^If it is not NULL, SQLite will invoke the destructor</span>
    4066. 

  4066. <a name="l04013"></a>04013 <span class="comment">** function given by the 4th parameter to sqlite3_set_auxdata() on</span>
    4067. 

  4067. <a name="l04014"></a>04014 <span class="comment">** the metadata when the corresponding function parameter changes</span>
    4068. 

  4068. <a name="l04015"></a>04015 <span class="comment">** or when the SQL statement completes, whichever comes first.</span>
    4069. 

  4069. <a name="l04016"></a>04016 <span class="comment">**</span>
    4070. 

  4070. <a name="l04017"></a>04017 <span class="comment">** SQLite is free to call the destructor and drop metadata on any</span>
    4071. 

  4071. <a name="l04018"></a>04018 <span class="comment">** parameter of any function at any time.  ^The only guarantee is that</span>
    4072. 

  4072. <a name="l04019"></a>04019 <span class="comment">** the destructor will be called before the metadata is dropped.</span>
    4073. 

  4073. <a name="l04020"></a>04020 <span class="comment">**</span>
    4074. 

  4074. <a name="l04021"></a>04021 <span class="comment">** ^(In practice, metadata is preserved between function calls for</span>
    4075. 

  4075. <a name="l04022"></a>04022 <span class="comment">** expressions that are constant at compile time. This includes literal</span>
    4076. 

  4076. <a name="l04023"></a>04023 <span class="comment">** values and [parameters].)^</span>
    4077. 

  4077. <a name="l04024"></a>04024 <span class="comment">**</span>
    4078. 

  4078. <a name="l04025"></a>04025 <span class="comment">** These routines must be called from the same thread in which</span>
    4079. 

  4079. <a name="l04026"></a>04026 <span class="comment">** the SQL function is running.</span>
    4080. 

  4080. <a name="l04027"></a>04027 <span class="comment">*/</span>
    4081. 

  4081. <a name="l04028"></a>04028 SQLITE_API <span class="keywordtype">void</span> *sqlite3_get_auxdata(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <span class="keywordtype">int</span> N);
    4082. 

  4082. <a name="l04029"></a>04029 SQLITE_API <span class="keywordtype">void</span> sqlite3_set_auxdata(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <span class="keywordtype">int</span> N, <span class="keywordtype">void</span>*, <span class="keywordtype">void</span> (*)(<span class="keywordtype">void</span>*));
    4083. 

  4083. <a name="l04030"></a>04030 
    4084. 

  4084. <a name="l04031"></a>04031 
    4085. 

  4085. <a name="l04032"></a>04032 <span class="comment">/*</span>
    4086. 

  4086. <a name="l04033"></a>04033 <span class="comment">** CAPI3REF: Constants Defining Special Destructor Behavior</span>
    4087. 

  4087. <a name="l04034"></a>04034 <span class="comment">**</span>
    4088. 

  4088. <a name="l04035"></a>04035 <span class="comment">** These are special values for the destructor that is passed in as the</span>
    4089. 

  4089. <a name="l04036"></a>04036 <span class="comment">** final argument to routines like [sqlite3_result_blob()].  ^If the destructor</span>
    4090. 

  4090. <a name="l04037"></a>04037 <span class="comment">** argument is SQLITE_STATIC, it means that the content pointer is constant</span>
    4091. 

  4091. <a name="l04038"></a>04038 <span class="comment">** and will never change.  It does not need to be destroyed.  ^The</span>
    4092. 

  4092. <a name="l04039"></a>04039 <span class="comment">** SQLITE_TRANSIENT value means that the content will likely change in</span>
    4093. 

  4093. <a name="l04040"></a>04040 <span class="comment">** the near future and that SQLite should make its own private copy of</span>
    4094. 

  4094. <a name="l04041"></a>04041 <span class="comment">** the content before returning.</span>
    4095. 

  4095. <a name="l04042"></a>04042 <span class="comment">**</span>
    4096. 

  4096. <a name="l04043"></a>04043 <span class="comment">** The typedef is necessary to work around problems in certain</span>
    4097. 

  4097. <a name="l04044"></a>04044 <span class="comment">** C++ compilers.  See ticket #2191.</span>
    4098. 

  4098. <a name="l04045"></a>04045 <span class="comment">*/</span>
    4099. 

  4099. <a name="l04046"></a>04046 <span class="keyword">typedef</span> void (*sqlite3_destructor_type)(<span class="keywordtype">void</span>*);
    4100. 

  4100. <a name="l04047"></a>04047 <span class="preprocessor">#define SQLITE_STATIC      ((sqlite3_destructor_type)0)</span>
    4101. 

  4101. <a name="l04048"></a>04048 <span class="preprocessor"></span><span class="preprocessor">#define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)</span>
    4102. 

  4102. <a name="l04049"></a>04049 <span class="preprocessor"></span>
    4103. 

  4103. <a name="l04050"></a>04050 <span class="comment">/*</span>
    4104. 

  4104. <a name="l04051"></a>04051 <span class="comment">** CAPI3REF: Setting The Result Of An SQL Function</span>
    4105. 

  4105. <a name="l04052"></a>04052 <span class="comment">**</span>
    4106. 

  4106. <a name="l04053"></a>04053 <span class="comment">** These routines are used by the xFunc or xFinal callbacks that</span>
    4107. 

  4107. <a name="l04054"></a>04054 <span class="comment">** implement SQL functions and aggregates.  See</span>
    4108. 

  4108. <a name="l04055"></a>04055 <span class="comment">** [sqlite3_create_function()] and [sqlite3_create_function16()]</span>
    4109. 

  4109. <a name="l04056"></a>04056 <span class="comment">** for additional information.</span>
    4110. 

  4110. <a name="l04057"></a>04057 <span class="comment">**</span>
    4111. 

  4111. <a name="l04058"></a>04058 <span class="comment">** These functions work very much like the [parameter binding] family of</span>
    4112. 

  4112. <a name="l04059"></a>04059 <span class="comment">** functions used to bind values to host parameters in prepared statements.</span>
    4113. 

  4113. <a name="l04060"></a>04060 <span class="comment">** Refer to the [SQL parameter] documentation for additional information.</span>
    4114. 

  4114. <a name="l04061"></a>04061 <span class="comment">**</span>
    4115. 

  4115. <a name="l04062"></a>04062 <span class="comment">** ^The sqlite3_result_blob() interface sets the result from</span>
    4116. 

  4116. <a name="l04063"></a>04063 <span class="comment">** an application-defined function to be the BLOB whose content is pointed</span>
    4117. 

  4117. <a name="l04064"></a>04064 <span class="comment">** to by the second parameter and which is N bytes long where N is the</span>
    4118. 

  4118. <a name="l04065"></a>04065 <span class="comment">** third parameter.</span>
    4119. 

  4119. <a name="l04066"></a>04066 <span class="comment">**</span>
    4120. 

  4120. <a name="l04067"></a>04067 <span class="comment">** ^The sqlite3_result_zeroblob() interfaces set the result of</span>
    4121. 

  4121. <a name="l04068"></a>04068 <span class="comment">** the application-defined function to be a BLOB containing all zero</span>
    4122. 

  4122. <a name="l04069"></a>04069 <span class="comment">** bytes and N bytes in size, where N is the value of the 2nd parameter.</span>
    4123. 

  4123. <a name="l04070"></a>04070 <span class="comment">**</span>
    4124. 

  4124. <a name="l04071"></a>04071 <span class="comment">** ^The sqlite3_result_double() interface sets the result from</span>
    4125. 

  4125. <a name="l04072"></a>04072 <span class="comment">** an application-defined function to be a floating point value specified</span>
    4126. 

  4126. <a name="l04073"></a>04073 <span class="comment">** by its 2nd argument.</span>
    4127. 

  4127. <a name="l04074"></a>04074 <span class="comment">**</span>
    4128. 

  4128. <a name="l04075"></a>04075 <span class="comment">** ^The sqlite3_result_error() and sqlite3_result_error16() functions</span>
    4129. 

  4129. <a name="l04076"></a>04076 <span class="comment">** cause the implemented SQL function to throw an exception.</span>
    4130. 

  4130. <a name="l04077"></a>04077 <span class="comment">** ^SQLite uses the string pointed to by the</span>
    4131. 

  4131. <a name="l04078"></a>04078 <span class="comment">** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()</span>
    4132. 

  4132. <a name="l04079"></a>04079 <span class="comment">** as the text of an error message.  ^SQLite interprets the error</span>
    4133. 

  4133. <a name="l04080"></a>04080 <span class="comment">** message string from sqlite3_result_error() as UTF-8. ^SQLite</span>
    4134. 

  4134. <a name="l04081"></a>04081 <span class="comment">** interprets the string from sqlite3_result_error16() as UTF-16 in native</span>
    4135. 

  4135. <a name="l04082"></a>04082 <span class="comment">** byte order.  ^If the third parameter to sqlite3_result_error()</span>
    4136. 

  4136. <a name="l04083"></a>04083 <span class="comment">** or sqlite3_result_error16() is negative then SQLite takes as the error</span>
    4137. 

  4137. <a name="l04084"></a>04084 <span class="comment">** message all text up through the first zero character.</span>
    4138. 

  4138. <a name="l04085"></a>04085 <span class="comment">** ^If the third parameter to sqlite3_result_error() or</span>
    4139. 

  4139. <a name="l04086"></a>04086 <span class="comment">** sqlite3_result_error16() is non-negative then SQLite takes that many</span>
    4140. 

  4140. <a name="l04087"></a>04087 <span class="comment">** bytes (not characters) from the 2nd parameter as the error message.</span>
    4141. 

  4141. <a name="l04088"></a>04088 <span class="comment">** ^The sqlite3_result_error() and sqlite3_result_error16()</span>
    4142. 

  4142. <a name="l04089"></a>04089 <span class="comment">** routines make a private copy of the error message text before</span>
    4143. 

  4143. <a name="l04090"></a>04090 <span class="comment">** they return.  Hence, the calling function can deallocate or</span>
    4144. 

  4144. <a name="l04091"></a>04091 <span class="comment">** modify the text after they return without harm.</span>
    4145. 

  4145. <a name="l04092"></a>04092 <span class="comment">** ^The sqlite3_result_error_code() function changes the error code</span>
    4146. 

  4146. <a name="l04093"></a>04093 <span class="comment">** returned by SQLite as a result of an error in a function.  ^By default,</span>
    4147. 

  4147. <a name="l04094"></a>04094 <span class="comment">** the error code is SQLITE_ERROR.  ^A subsequent call to sqlite3_result_error()</span>
    4148. 

  4148. <a name="l04095"></a>04095 <span class="comment">** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.</span>
    4149. 

  4149. <a name="l04096"></a>04096 <span class="comment">**</span>
    4150. 

  4150. <a name="l04097"></a>04097 <span class="comment">** ^The sqlite3_result_toobig() interface causes SQLite to throw an error</span>
    4151. 

  4151. <a name="l04098"></a>04098 <span class="comment">** indicating that a string or BLOB is too long to represent.</span>
    4152. 

  4152. <a name="l04099"></a>04099 <span class="comment">**</span>
    4153. 

  4153. <a name="l04100"></a>04100 <span class="comment">** ^The sqlite3_result_nomem() interface causes SQLite to throw an error</span>
    4154. 

  4154. <a name="l04101"></a>04101 <span class="comment">** indicating that a memory allocation failed.</span>
    4155. 

  4155. <a name="l04102"></a>04102 <span class="comment">**</span>
    4156. 

  4156. <a name="l04103"></a>04103 <span class="comment">** ^The sqlite3_result_int() interface sets the return value</span>
    4157. 

  4157. <a name="l04104"></a>04104 <span class="comment">** of the application-defined function to be the 32-bit signed integer</span>
    4158. 

  4158. <a name="l04105"></a>04105 <span class="comment">** value given in the 2nd argument.</span>
    4159. 

  4159. <a name="l04106"></a>04106 <span class="comment">** ^The sqlite3_result_int64() interface sets the return value</span>
    4160. 

  4160. <a name="l04107"></a>04107 <span class="comment">** of the application-defined function to be the 64-bit signed integer</span>
    4161. 

  4161. <a name="l04108"></a>04108 <span class="comment">** value given in the 2nd argument.</span>
    4162. 

  4162. <a name="l04109"></a>04109 <span class="comment">**</span>
    4163. 

  4163. <a name="l04110"></a>04110 <span class="comment">** ^The sqlite3_result_null() interface sets the return value</span>
    4164. 

  4164. <a name="l04111"></a>04111 <span class="comment">** of the application-defined function to be NULL.</span>
    4165. 

  4165. <a name="l04112"></a>04112 <span class="comment">**</span>
    4166. 

  4166. <a name="l04113"></a>04113 <span class="comment">** ^The sqlite3_result_text(), sqlite3_result_text16(),</span>
    4167. 

  4167. <a name="l04114"></a>04114 <span class="comment">** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces</span>
    4168. 

  4168. <a name="l04115"></a>04115 <span class="comment">** set the return value of the application-defined function to be</span>
    4169. 

  4169. <a name="l04116"></a>04116 <span class="comment">** a text string which is represented as UTF-8, UTF-16 native byte order,</span>
    4170. 

  4170. <a name="l04117"></a>04117 <span class="comment">** UTF-16 little endian, or UTF-16 big endian, respectively.</span>
    4171. 

  4171. <a name="l04118"></a>04118 <span class="comment">** ^SQLite takes the text result from the application from</span>
    4172. 

  4172. <a name="l04119"></a>04119 <span class="comment">** the 2nd parameter of the sqlite3_result_text* interfaces.</span>
    4173. 

  4173. <a name="l04120"></a>04120 <span class="comment">** ^If the 3rd parameter to the sqlite3_result_text* interfaces</span>
    4174. 

  4174. <a name="l04121"></a>04121 <span class="comment">** is negative, then SQLite takes result text from the 2nd parameter</span>
    4175. 

  4175. <a name="l04122"></a>04122 <span class="comment">** through the first zero character.</span>
    4176. 

  4176. <a name="l04123"></a>04123 <span class="comment">** ^If the 3rd parameter to the sqlite3_result_text* interfaces</span>
    4177. 

  4177. <a name="l04124"></a>04124 <span class="comment">** is non-negative, then as many bytes (not characters) of the text</span>
    4178. 

  4178. <a name="l04125"></a>04125 <span class="comment">** pointed to by the 2nd parameter are taken as the application-defined</span>
    4179. 

  4179. <a name="l04126"></a>04126 <span class="comment">** function result.  If the 3rd parameter is non-negative, then it</span>
    4180. 

  4180. <a name="l04127"></a>04127 <span class="comment">** must be the byte offset into the string where the NUL terminator would</span>
    4181. 

  4181. <a name="l04128"></a>04128 <span class="comment">** appear if the string where NUL terminated.  If any NUL characters occur</span>
    4182. 

  4182. <a name="l04129"></a>04129 <span class="comment">** in the string at a byte offset that is less than the value of the 3rd</span>
    4183. 

  4183. <a name="l04130"></a>04130 <span class="comment">** parameter, then the resulting string will contain embedded NULs and the</span>
    4184. 

  4184. <a name="l04131"></a>04131 <span class="comment">** result of expressions operating on strings with embedded NULs is undefined.</span>
    4185. 

  4185. <a name="l04132"></a>04132 <span class="comment">** ^If the 4th parameter to the sqlite3_result_text* interfaces</span>
    4186. 

  4186. <a name="l04133"></a>04133 <span class="comment">** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that</span>
    4187. 

  4187. <a name="l04134"></a>04134 <span class="comment">** function as the destructor on the text or BLOB result when it has</span>
    4188. 

  4188. <a name="l04135"></a>04135 <span class="comment">** finished using that result.</span>
    4189. 

  4189. <a name="l04136"></a>04136 <span class="comment">** ^If the 4th parameter to the sqlite3_result_text* interfaces or to</span>
    4190. 

  4190. <a name="l04137"></a>04137 <span class="comment">** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite</span>
    4191. 

  4191. <a name="l04138"></a>04138 <span class="comment">** assumes that the text or BLOB result is in constant space and does not</span>
    4192. 

  4192. <a name="l04139"></a>04139 <span class="comment">** copy the content of the parameter nor call a destructor on the content</span>
    4193. 

  4193. <a name="l04140"></a>04140 <span class="comment">** when it has finished using that result.</span>
    4194. 

  4194. <a name="l04141"></a>04141 <span class="comment">** ^If the 4th parameter to the sqlite3_result_text* interfaces</span>
    4195. 

  4195. <a name="l04142"></a>04142 <span class="comment">** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT</span>
    4196. 

  4196. <a name="l04143"></a>04143 <span class="comment">** then SQLite makes a copy of the result into space obtained from</span>
    4197. 

  4197. <a name="l04144"></a>04144 <span class="comment">** from [sqlite3_malloc()] before it returns.</span>
    4198. 

  4198. <a name="l04145"></a>04145 <span class="comment">**</span>
    4199. 

  4199. <a name="l04146"></a>04146 <span class="comment">** ^The sqlite3_result_value() interface sets the result of</span>
    4200. 

  4200. <a name="l04147"></a>04147 <span class="comment">** the application-defined function to be a copy the</span>
    4201. 

  4201. <a name="l04148"></a>04148 <span class="comment">** [unprotected sqlite3_value] object specified by the 2nd parameter.  ^The</span>
    4202. 

  4202. <a name="l04149"></a>04149 <span class="comment">** sqlite3_result_value() interface makes a copy of the [sqlite3_value]</span>
    4203. 

  4203. <a name="l04150"></a>04150 <span class="comment">** so that the [sqlite3_value] specified in the parameter may change or</span>
    4204. 

  4204. <a name="l04151"></a>04151 <span class="comment">** be deallocated after sqlite3_result_value() returns without harm.</span>
    4205. 

  4205. <a name="l04152"></a>04152 <span class="comment">** ^A [protected sqlite3_value] object may always be used where an</span>
    4206. 

  4206. <a name="l04153"></a>04153 <span class="comment">** [unprotected sqlite3_value] object is required, so either</span>
    4207. 

  4207. <a name="l04154"></a>04154 <span class="comment">** kind of [sqlite3_value] object can be used with this interface.</span>
    4208. 

  4208. <a name="l04155"></a>04155 <span class="comment">**</span>
    4209. 

  4209. <a name="l04156"></a>04156 <span class="comment">** If these routines are called from within the different thread</span>
    4210. 

  4210. <a name="l04157"></a>04157 <span class="comment">** than the one containing the application-defined function that received</span>
    4211. 

  4211. <a name="l04158"></a>04158 <span class="comment">** the [sqlite3_context] pointer, the results are undefined.</span>
    4212. 

  4212. <a name="l04159"></a>04159 <span class="comment">*/</span>
    4213. 

  4213. <a name="l04160"></a>04160 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_blob(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <span class="keyword">const</span> <span class="keywordtype">void</span>*, <span class="keywordtype">int</span>, <span class="keywordtype">void</span>(*)(<span class="keywordtype">void</span>*));
    4214. 

  4214. <a name="l04161"></a>04161 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_double(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <span class="keywordtype">double</span>);
    4215. 

  4215. <a name="l04162"></a>04162 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_error(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <span class="keyword">const</span> <span class="keywordtype">char</span>*, <span class="keywordtype">int</span>);
    4216. 

  4216. <a name="l04163"></a>04163 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_error16(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <span class="keyword">const</span> <span class="keywordtype">void</span>*, <span class="keywordtype">int</span>);
    4217. 

  4217. <a name="l04164"></a>04164 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_error_toobig(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*);
    4218. 

  4218. <a name="l04165"></a>04165 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_error_nomem(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*);
    4219. 

  4219. <a name="l04166"></a>04166 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_error_code(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <span class="keywordtype">int</span>);
    4220. 

  4220. <a name="l04167"></a>04167 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_int(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <span class="keywordtype">int</span>);
    4221. 

  4221. <a name="l04168"></a>04168 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_int64(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, sqlite3_int64);
    4222. 

  4222. <a name="l04169"></a>04169 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_null(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*);
    4223. 

  4223. <a name="l04170"></a>04170 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_text(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <span class="keyword">const</span> <span class="keywordtype">char</span>*, <span class="keywordtype">int</span>, <span class="keywordtype">void</span>(*)(<span class="keywordtype">void</span>*));
    4224. 

  4224. <a name="l04171"></a>04171 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_text16(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <span class="keyword">const</span> <span class="keywordtype">void</span>*, <span class="keywordtype">int</span>, <span class="keywordtype">void</span>(*)(<span class="keywordtype">void</span>*));
    4225. 

  4225. <a name="l04172"></a>04172 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_text16le(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <span class="keyword">const</span> <span class="keywordtype">void</span>*, <span class="keywordtype">int</span>,<span class="keywordtype">void</span>(*)(<span class="keywordtype">void</span>*));
    4226. 

  4226. <a name="l04173"></a>04173 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_text16be(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <span class="keyword">const</span> <span class="keywordtype">void</span>*, <span class="keywordtype">int</span>,<span class="keywordtype">void</span>(*)(<span class="keywordtype">void</span>*));
    4227. 

  4227. <a name="l04174"></a>04174 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_value(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <a class="code" href="structMem.html">sqlite3_value</a>*);
    4228. 

  4228. <a name="l04175"></a>04175 SQLITE_API <span class="keywordtype">void</span> sqlite3_result_zeroblob(<a class="code" href="structsqlite3__context.html">sqlite3_context</a>*, <span class="keywordtype">int</span> n);
    4229. 

  4229. <a name="l04176"></a>04176 
    4230. 

  4230. <a name="l04177"></a>04177 <span class="comment">/*</span>
    4231. 

  4231. <a name="l04178"></a>04178 <span class="comment">** CAPI3REF: Define New Collating Sequences</span>
    4232. 

  4232. <a name="l04179"></a>04179 <span class="comment">**</span>
    4233. 

  4233. <a name="l04180"></a>04180 <span class="comment">** ^These functions add, remove, or modify a [collation] associated</span>
    4234. 

  4234. <a name="l04181"></a>04181 <span class="comment">** with the [database connection] specified as the first argument.</span>
    4235. 

  4235. <a name="l04182"></a>04182 <span class="comment">**</span>
    4236. 

  4236. <a name="l04183"></a>04183 <span class="comment">** ^The name of the collation is a UTF-8 string</span>
    4237. 

  4237. <a name="l04184"></a>04184 <span class="comment">** for sqlite3_create_collation() and sqlite3_create_collation_v2()</span>
    4238. 

  4238. <a name="l04185"></a>04185 <span class="comment">** and a UTF-16 string in native byte order for sqlite3_create_collation16().</span>
    4239. 

  4239. <a name="l04186"></a>04186 <span class="comment">** ^Collation names that compare equal according to [sqlite3_strnicmp()] are</span>
    4240. 

  4240. <a name="l04187"></a>04187 <span class="comment">** considered to be the same name.</span>
    4241. 

  4241. <a name="l04188"></a>04188 <span class="comment">**</span>
    4242. 

  4242. <a name="l04189"></a>04189 <span class="comment">** ^(The third argument (eTextRep) must be one of the constants:</span>
    4243. 

  4243. <a name="l04190"></a>04190 <span class="comment">** &lt;ul&gt;</span>
    4244. 

  4244. <a name="l04191"></a>04191 <span class="comment">** &lt;li&gt; [SQLITE_UTF8],</span>
    4245. 

  4245. <a name="l04192"></a>04192 <span class="comment">** &lt;li&gt; [SQLITE_UTF16LE],</span>
    4246. 

  4246. <a name="l04193"></a>04193 <span class="comment">** &lt;li&gt; [SQLITE_UTF16BE],</span>
    4247. 

  4247. <a name="l04194"></a>04194 <span class="comment">** &lt;li&gt; [SQLITE_UTF16], or</span>
    4248. 

  4248. <a name="l04195"></a>04195 <span class="comment">** &lt;li&gt; [SQLITE_UTF16_ALIGNED].</span>
    4249. 

  4249. <a name="l04196"></a>04196 <span class="comment">** &lt;/ul&gt;)^</span>
    4250. 

  4250. <a name="l04197"></a>04197 <span class="comment">** ^The eTextRep argument determines the encoding of strings passed</span>
    4251. 

  4251. <a name="l04198"></a>04198 <span class="comment">** to the collating function callback, xCallback.</span>
    4252. 

  4252. <a name="l04199"></a>04199 <span class="comment">** ^The [SQLITE_UTF16] and [SQLITE_UTF16_ALIGNED] values for eTextRep</span>
    4253. 

  4253. <a name="l04200"></a>04200 <span class="comment">** force strings to be UTF16 with native byte order.</span>
    4254. 

  4254. <a name="l04201"></a>04201 <span class="comment">** ^The [SQLITE_UTF16_ALIGNED] value for eTextRep forces strings to begin</span>
    4255. 

  4255. <a name="l04202"></a>04202 <span class="comment">** on an even byte address.</span>
    4256. 

  4256. <a name="l04203"></a>04203 <span class="comment">**</span>
    4257. 

  4257. <a name="l04204"></a>04204 <span class="comment">** ^The fourth argument, pArg, is an application data pointer that is passed</span>
    4258. 

  4258. <a name="l04205"></a>04205 <span class="comment">** through as the first argument to the collating function callback.</span>
    4259. 

  4259. <a name="l04206"></a>04206 <span class="comment">**</span>
    4260. 

  4260. <a name="l04207"></a>04207 <span class="comment">** ^The fifth argument, xCallback, is a pointer to the collating function.</span>
    4261. 

  4261. <a name="l04208"></a>04208 <span class="comment">** ^Multiple collating functions can be registered using the same name but</span>
    4262. 

  4262. <a name="l04209"></a>04209 <span class="comment">** with different eTextRep parameters and SQLite will use whichever</span>
    4263. 

  4263. <a name="l04210"></a>04210 <span class="comment">** function requires the least amount of data transformation.</span>
    4264. 

  4264. <a name="l04211"></a>04211 <span class="comment">** ^If the xCallback argument is NULL then the collating function is</span>
    4265. 

  4265. <a name="l04212"></a>04212 <span class="comment">** deleted.  ^When all collating functions having the same name are deleted,</span>
    4266. 

  4266. <a name="l04213"></a>04213 <span class="comment">** that collation is no longer usable.</span>
    4267. 

  4267. <a name="l04214"></a>04214 <span class="comment">**</span>
    4268. 

  4268. <a name="l04215"></a>04215 <span class="comment">** ^The collating function callback is invoked with a copy of the pArg </span>
    4269. 

  4269. <a name="l04216"></a>04216 <span class="comment">** application data pointer and with two strings in the encoding specified</span>
    4270. 

  4270. <a name="l04217"></a>04217 <span class="comment">** by the eTextRep argument.  The collating function must return an</span>
    4271. 

  4271. <a name="l04218"></a>04218 <span class="comment">** integer that is negative, zero, or positive</span>
    4272. 

  4272. <a name="l04219"></a>04219 <span class="comment">** if the first string is less than, equal to, or greater than the second,</span>
    4273. 

  4273. <a name="l04220"></a>04220 <span class="comment">** respectively.  A collating function must always return the same answer</span>
    4274. 

  4274. <a name="l04221"></a>04221 <span class="comment">** given the same inputs.  If two or more collating functions are registered</span>
    4275. 

  4275. <a name="l04222"></a>04222 <span class="comment">** to the same collation name (using different eTextRep values) then all</span>
    4276. 

  4276. <a name="l04223"></a>04223 <span class="comment">** must give an equivalent answer when invoked with equivalent strings.</span>
    4277. 

  4277. <a name="l04224"></a>04224 <span class="comment">** The collating function must obey the following properties for all</span>
    4278. 

  4278. <a name="l04225"></a>04225 <span class="comment">** strings A, B, and C:</span>
    4279. 

  4279. <a name="l04226"></a>04226 <span class="comment">**</span>
    4280. 

  4280. <a name="l04227"></a>04227 <span class="comment">** &lt;ol&gt;</span>
    4281. 

  4281. <a name="l04228"></a>04228 <span class="comment">** &lt;li&gt; If A==B then B==A.</span>
    4282. 

  4282. <a name="l04229"></a>04229 <span class="comment">** &lt;li&gt; If A==B and B==C then A==C.</span>
    4283. 

  4283. <a name="l04230"></a>04230 <span class="comment">** &lt;li&gt; If A&amp;lt;B THEN B&amp;gt;A.</span>
    4284. 

  4284. <a name="l04231"></a>04231 <span class="comment">** &lt;li&gt; If A&amp;lt;B and B&amp;lt;C then A&amp;lt;C.</span>
    4285. 

  4285. <a name="l04232"></a>04232 <span class="comment">** &lt;/ol&gt;</span>
    4286. 

  4286. <a name="l04233"></a>04233 <span class="comment">**</span>
    4287. 

  4287. <a name="l04234"></a>04234 <span class="comment">** If a collating function fails any of the above constraints and that</span>
    4288. 

  4288. <a name="l04235"></a>04235 <span class="comment">** collating function is  registered and used, then the behavior of SQLite</span>
    4289. 

  4289. <a name="l04236"></a>04236 <span class="comment">** is undefined.</span>
    4290. 

  4290. <a name="l04237"></a>04237 <span class="comment">**</span>
    4291. 

  4291. <a name="l04238"></a>04238 <span class="comment">** ^The sqlite3_create_collation_v2() works like sqlite3_create_collation()</span>
    4292. 

  4292. <a name="l04239"></a>04239 <span class="comment">** with the addition that the xDestroy callback is invoked on pArg when</span>
    4293. 

  4293. <a name="l04240"></a>04240 <span class="comment">** the collating function is deleted.</span>
    4294. 

  4294. <a name="l04241"></a>04241 <span class="comment">** ^Collating functions are deleted when they are overridden by later</span>
    4295. 

  4295. <a name="l04242"></a>04242 <span class="comment">** calls to the collation creation functions or when the</span>
    4296. 

  4296. <a name="l04243"></a>04243 <span class="comment">** [database connection] is closed using [sqlite3_close()].</span>
    4297. 

  4297. <a name="l04244"></a>04244 <span class="comment">**</span>
    4298. 

  4298. <a name="l04245"></a>04245 <span class="comment">** ^The xDestroy callback is &lt;u&gt;not&lt;/u&gt; called if the </span>
    4299. 

  4299. <a name="l04246"></a>04246 <span class="comment">** sqlite3_create_collation_v2() function fails.  Applications that invoke</span>
    4300. 

  4300. <a name="l04247"></a>04247 <span class="comment">** sqlite3_create_collation_v2() with a non-NULL xDestroy argument should </span>
    4301. 

  4301. <a name="l04248"></a>04248 <span class="comment">** check the return code and dispose of the application data pointer</span>
    4302. 

  4302. <a name="l04249"></a>04249 <span class="comment">** themselves rather than expecting SQLite to deal with it for them.</span>
    4303. 

  4303. <a name="l04250"></a>04250 <span class="comment">** This is different from every other SQLite interface.  The inconsistency </span>
    4304. 

  4304. <a name="l04251"></a>04251 <span class="comment">** is unfortunate but cannot be changed without breaking backwards </span>
    4305. 

  4305. <a name="l04252"></a>04252 <span class="comment">** compatibility.</span>
    4306. 

  4306. <a name="l04253"></a>04253 <span class="comment">**</span>
    4307. 

  4307. <a name="l04254"></a>04254 <span class="comment">** See also:  [sqlite3_collation_needed()] and [sqlite3_collation_needed16()].</span>
    4308. 

  4308. <a name="l04255"></a>04255 <span class="comment">*/</span>
    4309. 

  4309. <a name="l04256"></a>04256 SQLITE_API <span class="keywordtype">int</span> sqlite3_create_collation(
    4310. 

  4310. <a name="l04257"></a>04257   <a class="code" href="structsqlite3.html">sqlite3</a>*, 
    4311. 

  4311. <a name="l04258"></a>04258   <span class="keyword">const</span> <span class="keywordtype">char</span> *zName, 
    4312. 

  4312. <a name="l04259"></a>04259   <span class="keywordtype">int</span> eTextRep, 
    4313. 

  4313. <a name="l04260"></a>04260   <span class="keywordtype">void</span> *pArg,
    4314. 

  4314. <a name="l04261"></a>04261   <span class="keywordtype">int</span>(*xCompare)(<span class="keywordtype">void</span>*,<span class="keywordtype">int</span>,<span class="keyword">const</span> <span class="keywordtype">void</span>*,<span class="keywordtype">int</span>,<span class="keyword">const</span> <span class="keywordtype">void</span>*)
    4315. 

  4315. <a name="l04262"></a>04262 );
    4316. 

  4316. <a name="l04263"></a>04263 SQLITE_API <span class="keywordtype">int</span> sqlite3_create_collation_v2(
    4317. 

  4317. <a name="l04264"></a>04264   <a class="code" href="structsqlite3.html">sqlite3</a>*, 
    4318. 

  4318. <a name="l04265"></a>04265   <span class="keyword">const</span> <span class="keywordtype">char</span> *zName, 
    4319. 

  4319. <a name="l04266"></a>04266   <span class="keywordtype">int</span> eTextRep, 
    4320. 

  4320. <a name="l04267"></a>04267   <span class="keywordtype">void</span> *pArg,
    4321. 

  4321. <a name="l04268"></a>04268   <span class="keywordtype">int</span>(*xCompare)(<span class="keywordtype">void</span>*,<span class="keywordtype">int</span>,<span class="keyword">const</span> <span class="keywordtype">void</span>*,<span class="keywordtype">int</span>,<span class="keyword">const</span> <span class="keywordtype">void</span>*),
    4322. 

  4322. <a name="l04269"></a>04269   <span class="keywordtype">void</span>(*xDestroy)(<span class="keywordtype">void</span>*)
    4323. 

  4323. <a name="l04270"></a>04270 );
    4324. 

  4324. <a name="l04271"></a>04271 SQLITE_API <span class="keywordtype">int</span> sqlite3_create_collation16(
    4325. 

  4325. <a name="l04272"></a>04272   <a class="code" href="structsqlite3.html">sqlite3</a>*, 
    4326. 

  4326. <a name="l04273"></a>04273   <span class="keyword">const</span> <span class="keywordtype">void</span> *zName,
    4327. 

  4327. <a name="l04274"></a>04274   <span class="keywordtype">int</span> eTextRep, 
    4328. 

  4328. <a name="l04275"></a>04275   <span class="keywordtype">void</span> *pArg,
    4329. 

  4329. <a name="l04276"></a>04276   <span class="keywordtype">int</span>(*xCompare)(<span class="keywordtype">void</span>*,<span class="keywordtype">int</span>,<span class="keyword">const</span> <span class="keywordtype">void</span>*,<span class="keywordtype">int</span>,<span class="keyword">const</span> <span class="keywordtype">void</span>*)
    4330. 

  4330. <a name="l04277"></a>04277 );
    4331. 

  4331. <a name="l04278"></a>04278 
    4332. 

  4332. <a name="l04279"></a>04279 <span class="comment">/*</span>
    4333. 

  4333. <a name="l04280"></a>04280 <span class="comment">** CAPI3REF: Collation Needed Callbacks</span>
    4334. 

  4334. <a name="l04281"></a>04281 <span class="comment">**</span>
    4335. 

  4335. <a name="l04282"></a>04282 <span class="comment">** ^To avoid having to register all collation sequences before a database</span>
    4336. 

  4336. <a name="l04283"></a>04283 <span class="comment">** can be used, a single callback function may be registered with the</span>
    4337. 

  4337. <a name="l04284"></a>04284 <span class="comment">** [database connection] to be invoked whenever an undefined collation</span>
    4338. 

  4338. <a name="l04285"></a>04285 <span class="comment">** sequence is required.</span>
    4339. 

  4339. <a name="l04286"></a>04286 <span class="comment">**</span>
    4340. 

  4340. <a name="l04287"></a>04287 <span class="comment">** ^If the function is registered using the sqlite3_collation_needed() API,</span>
    4341. 

  4341. <a name="l04288"></a>04288 <span class="comment">** then it is passed the names of undefined collation sequences as strings</span>
    4342. 

  4342. <a name="l04289"></a>04289 <span class="comment">** encoded in UTF-8. ^If sqlite3_collation_needed16() is used,</span>
    4343. 

  4343. <a name="l04290"></a>04290 <span class="comment">** the names are passed as UTF-16 in machine native byte order.</span>
    4344. 

  4344. <a name="l04291"></a>04291 <span class="comment">** ^A call to either function replaces the existing collation-needed callback.</span>
    4345. 

  4345. <a name="l04292"></a>04292 <span class="comment">**</span>
    4346. 

  4346. <a name="l04293"></a>04293 <span class="comment">** ^(When the callback is invoked, the first argument passed is a copy</span>
    4347. 

  4347. <a name="l04294"></a>04294 <span class="comment">** of the second argument to sqlite3_collation_needed() or</span>
    4348. 

  4348. <a name="l04295"></a>04295 <span class="comment">** sqlite3_collation_needed16().  The second argument is the database</span>
    4349. 

  4349. <a name="l04296"></a>04296 <span class="comment">** connection.  The third argument is one of [SQLITE_UTF8], [SQLITE_UTF16BE],</span>
    4350. 

  4350. <a name="l04297"></a>04297 <span class="comment">** or [SQLITE_UTF16LE], indicating the most desirable form of the collation</span>
    4351. 

  4351. <a name="l04298"></a>04298 <span class="comment">** sequence function required.  The fourth parameter is the name of the</span>
    4352. 

  4352. <a name="l04299"></a>04299 <span class="comment">** required collation sequence.)^</span>
    4353. 

  4353. <a name="l04300"></a>04300 <span class="comment">**</span>
    4354. 

  4354. <a name="l04301"></a>04301 <span class="comment">** The callback function should register the desired collation using</span>
    4355. 

  4355. <a name="l04302"></a>04302 <span class="comment">** [sqlite3_create_collation()], [sqlite3_create_collation16()], or</span>
    4356. 

  4356. <a name="l04303"></a>04303 <span class="comment">** [sqlite3_create_collation_v2()].</span>
    4357. 

  4357. <a name="l04304"></a>04304 <span class="comment">*/</span>
    4358. 

  4358. <a name="l04305"></a>04305 SQLITE_API <span class="keywordtype">int</span> sqlite3_collation_needed(
    4359. 

  4359. <a name="l04306"></a>04306   <a class="code" href="structsqlite3.html">sqlite3</a>*, 
    4360. 

  4360. <a name="l04307"></a>04307   <span class="keywordtype">void</span>*, 
    4361. 

  4361. <a name="l04308"></a>04308   <span class="keywordtype">void</span>(*)(<span class="keywordtype">void</span>*,<a class="code" href="structsqlite3.html">sqlite3</a>*,<span class="keywordtype">int</span> eTextRep,<span class="keyword">const</span> <span class="keywordtype">char</span>*)
    4362. 

  4362. <a name="l04309"></a>04309 );
    4363. 

  4363. <a name="l04310"></a>04310 SQLITE_API <span class="keywordtype">int</span> sqlite3_collation_needed16(
    4364. 

  4364. <a name="l04311"></a>04311   <a class="code" href="structsqlite3.html">sqlite3</a>*, 
    4365. 

  4365. <a name="l04312"></a>04312   <span class="keywordtype">void</span>*,
    4366. 

  4366. <a name="l04313"></a>04313   <span class="keywordtype">void</span>(*)(<span class="keywordtype">void</span>*,<a class="code" href="structsqlite3.html">sqlite3</a>*,<span class="keywordtype">int</span> eTextRep,<span class="keyword">const</span> <span class="keywordtype">void</span>*)
    4367. 

  4367. <a name="l04314"></a>04314 );
    4368. 

  4368. <a name="l04315"></a>04315 
    4369. 

  4369. <a name="l04316"></a>04316 <span class="preprocessor">#ifdef SQLITE_HAS_CODEC</span>
    4370. 

  4370. <a name="l04317"></a>04317 <span class="preprocessor"></span><span class="comment">/*</span>
    4371. 

  4371. <a name="l04318"></a>04318 <span class="comment">** Specify the key for an encrypted database.  This routine should be</span>
    4372. 

  4372. <a name="l04319"></a>04319 <span class="comment">** called right after sqlite3_open().</span>
    4373. 

  4373. <a name="l04320"></a>04320 <span class="comment">**</span>
    4374. 

  4374. <a name="l04321"></a>04321 <span class="comment">** The code to implement this API is not available in the public release</span>
    4375. 

  4375. <a name="l04322"></a>04322 <span class="comment">** of SQLite.</span>
    4376. 

  4376. <a name="l04323"></a>04323 <span class="comment">*/</span>
    4377. 

  4377. <a name="l04324"></a>04324 SQLITE_API <span class="keywordtype">int</span> sqlite3_key(
    4378. 

  4378. <a name="l04325"></a>04325   <a class="code" href="structsqlite3.html">sqlite3</a> *db,                   <span class="comment">/* Database to be rekeyed */</span>
    4379. 

  4379. <a name="l04326"></a>04326   <span class="keyword">const</span> <span class="keywordtype">void</span> *pKey, <span class="keywordtype">int</span> nKey     <span class="comment">/* The key */</span>
    4380. 

  4380. <a name="l04327"></a>04327 );
    4381. 

  4381. <a name="l04328"></a>04328 
    4382. 

  4382. <a name="l04329"></a>04329 <span class="comment">/*</span>
    4383. 

  4383. <a name="l04330"></a>04330 <span class="comment">** Change the key on an open database.  If the current database is not</span>
    4384. 

  4384. <a name="l04331"></a>04331 <span class="comment">** encrypted, this routine will encrypt it.  If pNew==0 or nNew==0, the</span>
    4385. 

  4385. <a name="l04332"></a>04332 <span class="comment">** database is decrypted.</span>
    4386. 

  4386. <a name="l04333"></a>04333 <span class="comment">**</span>
    4387. 

  4387. <a name="l04334"></a>04334 <span class="comment">** The code to implement this API is not available in the public release</span>
    4388. 

  4388. <a name="l04335"></a>04335 <span class="comment">** of SQLite.</span>
    4389. 

  4389. <a name="l04336"></a>04336 <span class="comment">*/</span>
    4390. 

  4390. <a name="l04337"></a>04337 SQLITE_API <span class="keywordtype">int</span> sqlite3_rekey(
    4391. 

  4391. <a name="l04338"></a>04338   <a class="code" href="structsqlite3.html">sqlite3</a> *db,                   <span class="comment">/* Database to be rekeyed */</span>
    4392. 

  4392. <a name="l04339"></a>04339   <span class="keyword">const</span> <span class="keywordtype">void</span> *pKey, <span class="keywordtype">int</span> nKey     <span class="comment">/* The new key */</span>
    4393. 

  4393. <a name="l04340"></a>04340 );
    4394. 

  4394. <a name="l04341"></a>04341 
    4395. 

  4395. <a name="l04342"></a>04342 <span class="comment">/*</span>
    4396. 

  4396. <a name="l04343"></a>04343 <span class="comment">** Specify the activation key for a SEE database.  Unless </span>
    4397. 

  4397. <a name="l04344"></a>04344 <span class="comment">** activated, none of the SEE routines will work.</span>
    4398. 

  4398. <a name="l04345"></a>04345 <span class="comment">*/</span>
    4399. 

  4399. <a name="l04346"></a>04346 SQLITE_API <span class="keywordtype">void</span> sqlite3_activate_see(
    4400. 

  4400. <a name="l04347"></a>04347   <span class="keyword">const</span> <span class="keywordtype">char</span> *zPassPhrase        <span class="comment">/* Activation phrase */</span>
    4401. 

  4401. <a name="l04348"></a>04348 );
    4402. 

  4402. <a name="l04349"></a>04349 <span class="preprocessor">#endif</span>
    4403. 

  4403. <a name="l04350"></a>04350 <span class="preprocessor"></span>
    4404. 

  4404. <a name="l04351"></a>04351 <span class="preprocessor">#ifdef SQLITE_ENABLE_CEROD</span>
    4405. 

  4405. <a name="l04352"></a>04352 <span class="preprocessor"></span><span class="comment">/*</span>
    4406. 

  4406. <a name="l04353"></a>04353 <span class="comment">** Specify the activation key for a CEROD database.  Unless </span>
    4407. 

  4407. <a name="l04354"></a>04354 <span class="comment">** activated, none of the CEROD routines will work.</span>
    4408. 

  4408. <a name="l04355"></a>04355 <span class="comment">*/</span>
    4409. 

  4409. <a name="l04356"></a>04356 SQLITE_API <span class="keywordtype">void</span> sqlite3_activate_cerod(
    4410. 

  4410. <a name="l04357"></a>04357   <span class="keyword">const</span> <span class="keywordtype">char</span> *zPassPhrase        <span class="comment">/* Activation phrase */</span>
    4411. 

  4411. <a name="l04358"></a>04358 );
    4412. 

  4412. <a name="l04359"></a>04359 <span class="preprocessor">#endif</span>
    4413. 

  4413. <a name="l04360"></a>04360 <span class="preprocessor"></span>
    4414. 

  4414. <a name="l04361"></a>04361 <span class="comment">/*</span>
    4415. 

  4415. <a name="l04362"></a>04362 <span class="comment">** CAPI3REF: Suspend Execution For A Short Time</span>
    4416. 

  4416. <a name="l04363"></a>04363 <span class="comment">**</span>
    4417. 

  4417. <a name="l04364"></a>04364 <span class="comment">** The sqlite3_sleep() function causes the current thread to suspend execution</span>
    4418. 

  4418. <a name="l04365"></a>04365 <span class="comment">** for at least a number of milliseconds specified in its parameter.</span>
    4419. 

  4419. <a name="l04366"></a>04366 <span class="comment">**</span>
    4420. 

  4420. <a name="l04367"></a>04367 <span class="comment">** If the operating system does not support sleep requests with</span>
    4421. 

  4421. <a name="l04368"></a>04368 <span class="comment">** millisecond time resolution, then the time will be rounded up to</span>
    4422. 

  4422. <a name="l04369"></a>04369 <span class="comment">** the nearest second. The number of milliseconds of sleep actually</span>
    4423. 

  4423. <a name="l04370"></a>04370 <span class="comment">** requested from the operating system is returned.</span>
    4424. 

  4424. <a name="l04371"></a>04371 <span class="comment">**</span>
    4425. 

  4425. <a name="l04372"></a>04372 <span class="comment">** ^SQLite implements this interface by calling the xSleep()</span>
    4426. 

  4426. <a name="l04373"></a>04373 <span class="comment">** method of the default [sqlite3_vfs] object.  If the xSleep() method</span>
    4427. 

  4427. <a name="l04374"></a>04374 <span class="comment">** of the default VFS is not implemented correctly, or not implemented at</span>
    4428. 

  4428. <a name="l04375"></a>04375 <span class="comment">** all, then the behavior of sqlite3_sleep() may deviate from the description</span>
    4429. 

  4429. <a name="l04376"></a>04376 <span class="comment">** in the previous paragraphs.</span>
    4430. 

  4430. <a name="l04377"></a>04377 <span class="comment">*/</span>
    4431. 

  4431. <a name="l04378"></a>04378 SQLITE_API <span class="keywordtype">int</span> sqlite3_sleep(<span class="keywordtype">int</span>);
    4432. 

  4432. <a name="l04379"></a>04379 
    4433. 

  4433. <a name="l04380"></a>04380 <span class="comment">/*</span>
    4434. 

  4434. <a name="l04381"></a>04381 <span class="comment">** CAPI3REF: Name Of The Folder Holding Temporary Files</span>
    4435. 

  4435. <a name="l04382"></a>04382 <span class="comment">**</span>
    4436. 

  4436. <a name="l04383"></a>04383 <span class="comment">** ^(If this global variable is made to point to a string which is</span>
    4437. 

  4437. <a name="l04384"></a>04384 <span class="comment">** the name of a folder (a.k.a. directory), then all temporary files</span>
    4438. 

  4438. <a name="l04385"></a>04385 <span class="comment">** created by SQLite when using a built-in [sqlite3_vfs | VFS]</span>
    4439. 

  4439. <a name="l04386"></a>04386 <span class="comment">** will be placed in that directory.)^  ^If this variable</span>
    4440. 

  4440. <a name="l04387"></a>04387 <span class="comment">** is a NULL pointer, then SQLite performs a search for an appropriate</span>
    4441. 

  4441. <a name="l04388"></a>04388 <span class="comment">** temporary file directory.</span>
    4442. 

  4442. <a name="l04389"></a>04389 <span class="comment">**</span>
    4443. 

  4443. <a name="l04390"></a>04390 <span class="comment">** It is not safe to read or modify this variable in more than one</span>
    4444. 

  4444. <a name="l04391"></a>04391 <span class="comment">** thread at a time.  It is not safe to read or modify this variable</span>
    4445. 

  4445. <a name="l04392"></a>04392 <span class="comment">** if a [database connection] is being used at the same time in a separate</span>
    4446. 

  4446. <a name="l04393"></a>04393 <span class="comment">** thread.</span>
    4447. 

  4447. <a name="l04394"></a>04394 <span class="comment">** It is intended that this variable be set once</span>
    4448. 

  4448. <a name="l04395"></a>04395 <span class="comment">** as part of process initialization and before any SQLite interface</span>
    4449. 

  4449. <a name="l04396"></a>04396 <span class="comment">** routines have been called and that this variable remain unchanged</span>
    4450. 

  4450. <a name="l04397"></a>04397 <span class="comment">** thereafter.</span>
    4451. 

  4451. <a name="l04398"></a>04398 <span class="comment">**</span>
    4452. 

  4452. <a name="l04399"></a>04399 <span class="comment">** ^The [temp_store_directory pragma] may modify this variable and cause</span>
    4453. 

  4453. <a name="l04400"></a>04400 <span class="comment">** it to point to memory obtained from [sqlite3_malloc].  ^Furthermore,</span>
    4454. 

  4454. <a name="l04401"></a>04401 <span class="comment">** the [temp_store_directory pragma] always assumes that any string</span>
    4455. 

  4455. <a name="l04402"></a>04402 <span class="comment">** that this variable points to is held in memory obtained from </span>
    4456. 

  4456. <a name="l04403"></a>04403 <span class="comment">** [sqlite3_malloc] and the pragma may attempt to free that memory</span>
    4457. 

  4457. <a name="l04404"></a>04404 <span class="comment">** using [sqlite3_free].</span>
    4458. 

  4458. <a name="l04405"></a>04405 <span class="comment">** Hence, if this variable is modified directly, either it should be</span>
    4459. 

  4459. <a name="l04406"></a>04406 <span class="comment">** made NULL or made to point to memory obtained from [sqlite3_malloc]</span>
    4460. 

  4460. <a name="l04407"></a>04407 <span class="comment">** or else the use of the [temp_store_directory pragma] should be avoided.</span>
    4461. 

  4461. <a name="l04408"></a>04408 <span class="comment">*/</span>
    4462. 

  4462. <a name="l04409"></a>04409 SQLITE_API SQLITE_EXTERN <span class="keywordtype">char</span> *sqlite3_temp_directory;
    4463. 

  4463. <a name="l04410"></a>04410 
    4464. 

  4464. <a name="l04411"></a>04411 <span class="comment">/*</span>
    4465. 

  4465. <a name="l04412"></a>04412 <span class="comment">** CAPI3REF: Test For Auto-Commit Mode</span>
    4466. 

  4466. <a name="l04413"></a>04413 <span class="comment">** KEYWORDS: {autocommit mode}</span>
    4467. 

  4467. <a name="l04414"></a>04414 <span class="comment">**</span>
    4468. 

  4468. <a name="l04415"></a>04415 <span class="comment">** ^The sqlite3_get_autocommit() interface returns non-zero or</span>
    4469. 

  4469. <a name="l04416"></a>04416 <span class="comment">** zero if the given database connection is or is not in autocommit mode,</span>
    4470. 

  4470. <a name="l04417"></a>04417 <span class="comment">** respectively.  ^Autocommit mode is on by default.</span>
    4471. 

  4471. <a name="l04418"></a>04418 <span class="comment">** ^Autocommit mode is disabled by a [BEGIN] statement.</span>
    4472. 

  4472. <a name="l04419"></a>04419 <span class="comment">** ^Autocommit mode is re-enabled by a [COMMIT] or [ROLLBACK].</span>
    4473. 

  4473. <a name="l04420"></a>04420 <span class="comment">**</span>
    4474. 

  4474. <a name="l04421"></a>04421 <span class="comment">** If certain kinds of errors occur on a statement within a multi-statement</span>
    4475. 

  4475. <a name="l04422"></a>04422 <span class="comment">** transaction (errors including [SQLITE_FULL], [SQLITE_IOERR],</span>
    4476. 

  4476. <a name="l04423"></a>04423 <span class="comment">** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the</span>
    4477. 

  4477. <a name="l04424"></a>04424 <span class="comment">** transaction might be rolled back automatically.  The only way to</span>
    4478. 

  4478. <a name="l04425"></a>04425 <span class="comment">** find out whether SQLite automatically rolled back the transaction after</span>
    4479. 

  4479. <a name="l04426"></a>04426 <span class="comment">** an error is to use this function.</span>
    4480. 

  4480. <a name="l04427"></a>04427 <span class="comment">**</span>
    4481. 

  4481. <a name="l04428"></a>04428 <span class="comment">** If another thread changes the autocommit status of the database</span>
    4482. 

  4482. <a name="l04429"></a>04429 <span class="comment">** connection while this routine is running, then the return value</span>
    4483. 

  4483. <a name="l04430"></a>04430 <span class="comment">** is undefined.</span>
    4484. 

  4484. <a name="l04431"></a>04431 <span class="comment">*/</span>
    4485. 

  4485. <a name="l04432"></a>04432 SQLITE_API <span class="keywordtype">int</span> sqlite3_get_autocommit(<a class="code" href="structsqlite3.html">sqlite3</a>*);
    4486. 

  4486. <a name="l04433"></a>04433 
    4487. 

  4487. <a name="l04434"></a>04434 <span class="comment">/*</span>
    4488. 

  4488. <a name="l04435"></a>04435 <span class="comment">** CAPI3REF: Find The Database Handle Of A Prepared Statement</span>
    4489. 

  4489. <a name="l04436"></a>04436 <span class="comment">**</span>
    4490. 

  4490. <a name="l04437"></a>04437 <span class="comment">** ^The sqlite3_db_handle interface returns the [database connection] handle</span>
    4491. 

  4491. <a name="l04438"></a>04438 <span class="comment">** to which a [prepared statement] belongs.  ^The [database connection]</span>
    4492. 

  4492. <a name="l04439"></a>04439 <span class="comment">** returned by sqlite3_db_handle is the same [database connection]</span>
    4493. 

  4493. <a name="l04440"></a>04440 <span class="comment">** that was the first argument</span>
    4494. 

  4494. <a name="l04441"></a>04441 <span class="comment">** to the [sqlite3_prepare_v2()] call (or its variants) that was used to</span>
    4495. 

  4495. <a name="l04442"></a>04442 <span class="comment">** create the statement in the first place.</span>
    4496. 

  4496. <a name="l04443"></a>04443 <span class="comment">*/</span>
    4497. 

  4497. <a name="l04444"></a>04444 SQLITE_API <a class="code" href="structsqlite3.html">sqlite3</a> *sqlite3_db_handle(sqlite3_stmt*);
    4498. 

  4498. <a name="l04445"></a>04445 
    4499. 

  4499. <a name="l04446"></a>04446 <span class="comment">/*</span>
    4500. 

  4500. <a name="l04447"></a>04447 <span class="comment">** CAPI3REF: Return The Filename For A Database Connection</span>
    4501. 

  4501. <a name="l04448"></a>04448 <span class="comment">**</span>
    4502. 

  4502. <a name="l04449"></a>04449 <span class="comment">** ^The sqlite3_db_filename(D,N) interface returns a pointer to a filename</span>
    4503. 

  4503. <a name="l04450"></a>04450 <span class="comment">** associated with database N of connection D.  ^The main database file</span>
    4504. 

  4504. <a name="l04451"></a>04451 <span class="comment">** has the name &quot;main&quot;.  If there is no attached database N on the database</span>
    4505. 

  4505. <a name="l04452"></a>04452 <span class="comment">** connection D, or if database N is a temporary or in-memory database, then</span>
    4506. 

  4506. <a name="l04453"></a>04453 <span class="comment">** a NULL pointer is returned.</span>
    4507. 

  4507. <a name="l04454"></a>04454 <span class="comment">**</span>
    4508. 

  4508. <a name="l04455"></a>04455 <span class="comment">** ^The filename returned by this function is the output of the</span>
    4509. 

  4509. <a name="l04456"></a>04456 <span class="comment">** xFullPathname method of the [VFS].  ^In other words, the filename</span>
    4510. 

  4510. <a name="l04457"></a>04457 <span class="comment">** will be an absolute pathname, even if the filename used</span>
    4511. 

  4511. <a name="l04458"></a>04458 <span class="comment">** to open the database originally was a URI or relative pathname.</span>
    4512. 

  4512. <a name="l04459"></a>04459 <span class="comment">*/</span>
    4513. 

  4513. <a name="l04460"></a>04460 SQLITE_API <span class="keyword">const</span> <span class="keywordtype">char</span> *sqlite3_db_filename(<a class="code" href="structsqlite3.html">sqlite3</a> *db, <span class="keyword">const</span> <span class="keywordtype">char</span> *zDbName);
    4514. 

  4514. <a name="l04461"></a>04461 
    4515. 

  4515. <a name="l04462"></a>04462 <span class="comment">/*</span>
    4516. 

  4516. <a name="l04463"></a>04463 <span class="comment">** CAPI3REF: Find the next prepared statement</span>
    4517. 

  4517. <a name="l04464"></a>04464 <span class="comment">**</span>
    4518. 

  4518. <a name="l04465"></a>04465 <span class="comment">** ^This interface returns a pointer to the next [prepared statement] after</span>
    4519. 

  4519. <a name="l04466"></a>04466 <span class="comment">** pStmt associated with the [database connection] pDb.  ^If pStmt is NULL</span>
    4520. 

  4520. <a name="l04467"></a>04467 <span class="comment">** then this interface returns a pointer to the first prepared statement</span>
    4521. 

  4521. <a name="l04468"></a>04468 <span class="comment">** associated with the database connection pDb.  ^If no prepared statement</span>
    4522. 

  4522. <a name="l04469"></a>04469 <span class="comment">** satisfies the conditions of this routine, it returns NULL.</span>
    4523. 

  4523. <a name="l04470"></a>04470 <span class="comment">**</span>
    4524. 

  4524. <a name="l04471"></a>04471 <span class="comment">** The [database connection] pointer D in a call to</span>
    4525. 

  4525. <a name="l04472"></a>04472 <span class="comment">** [sqlite3_next_stmt(D,S)] must refer to an open database</span>
    4526. 

  4526. <a name="l04473"></a>04473 <span class="comment">** connection and in particular must not be a NULL pointer.</span>
    4527. 

  4527. <a name="l04474"></a>04474 <span class="comment">*/</span>
    4528. 

  4528. <a name="l04475"></a>04475 SQLITE_API sqlite3_stmt *sqlite3_next_stmt(<a class="code" href="structsqlite3.html">sqlite3</a> *pDb, sqlite3_stmt *pStmt);
    4529. 

  4529. <a name="l04476"></a>04476 
    4530. 

  4530. <a name="l04477"></a>04477 <span class="comment">/*</span>
    4531. 

  4531. <a name="l04478"></a>04478 <span class="comment">** CAPI3REF: Commit And Rollback Notification Callbacks</span>
    4532. 

  4532. <a name="l04479"></a>04479 <span class="comment">**</span>
    4533. 

  4533. <a name="l04480"></a>04480 <span class="comment">** ^The sqlite3_commit_hook() interface registers a callback</span>
    4534. 

  4534. <a name="l04481"></a>04481 <span class="comment">** function to be invoked whenever a transaction is [COMMIT | committed].</span>
    4535. 

  4535. <a name="l04482"></a>04482 <span class="comment">** ^Any callback set by a previous call to sqlite3_commit_hook()</span>
    4536. 

  4536. <a n
    4537.