amalgalite 0.11.0 → 0.12.0

Sign up to get free protection for your applications and to get access to all the features.
@@ -18,8 +18,8 @@
18
18
  ** Some of the definitions that are in this file are marked as
19
19
  ** "experimental". Experimental interfaces are normally new
20
20
  ** features recently added to SQLite. We do not anticipate changes
21
- ** to experimental interfaces but reserve to make minor changes if
22
- ** experience from use "in the wild" suggest such changes are prudent.
21
+ ** to experimental interfaces but reserve the right to make minor changes
22
+ ** if experience from use "in the wild" suggest such changes are prudent.
23
23
  **
24
24
  ** The official C-language API documentation for SQLite is derived
25
25
  ** from comments in this file. This file is the authoritative source
@@ -29,8 +29,6 @@
29
29
  ** The makefile makes some minor changes to this file (such as inserting
30
30
  ** the version number) and changes its name to "sqlite3.h" as
31
31
  ** part of the build process.
32
- **
33
- ** @(#) $Id: sqlite.h.in,v 1.462 2009/08/06 17:40:46 drh Exp $
34
32
  */
35
33
  #ifndef _SQLITE3_H_
36
34
  #define _SQLITE3_H_
@@ -59,7 +57,7 @@ extern "C" {
59
57
  /*
60
58
  ** These no-op macros are used in front of interfaces to mark those
61
59
  ** interfaces as either deprecated or experimental. New applications
62
- ** should not use deprecated intrfaces - they are support for backwards
60
+ ** should not use deprecated interfaces - they are support for backwards
63
61
  ** compatibility only. Application writers should be aware that
64
62
  ** experimental interfaces are subject to change in point releases.
65
63
  **
@@ -89,51 +87,81 @@ extern "C" {
89
87
  ** the sqlite3.h file specify the version of SQLite with which
90
88
  ** that header file is associated.
91
89
  **
92
- ** The "version" of SQLite is a string of the form "X.Y.Z".
93
- ** The phrase "alpha" or "beta" might be appended after the Z.
94
- ** The X value is major version number always 3 in SQLite3.
95
- ** The X value only changes when backwards compatibility is
90
+ ** The "version" of SQLite is a string of the form "W.X.Y" or "W.X.Y.Z".
91
+ ** The W value is major version number and is always 3 in SQLite3.
92
+ ** The W value only changes when backwards compatibility is
96
93
  ** broken and we intend to never break backwards compatibility.
97
- ** The Y value is the minor version number and only changes when
94
+ ** The X value is the minor version number and only changes when
98
95
  ** there are major feature enhancements that are forwards compatible
99
96
  ** but not backwards compatible.
100
- ** The Z value is the release number and is incremented with
101
- ** each release but resets back to 0 whenever Y is incremented.
97
+ ** The Y value is the release number and is incremented with
98
+ ** each release but resets back to 0 whenever X is incremented.
99
+ ** The Z value only appears on branch releases.
100
+ **
101
+ ** The SQLITE_VERSION_NUMBER is an integer that is computed as
102
+ ** follows:
103
+ **
104
+ ** <blockquote><pre>
105
+ ** SQLITE_VERSION_NUMBER = W*1000000 + X*1000 + Y
106
+ ** </pre></blockquote>
107
+ **
108
+ ** Since version 3.6.18, SQLite source code has been stored in the
109
+ ** <a href="http://www.fossil-scm.org/">fossil configuration management
110
+ ** system</a>. The SQLITE_SOURCE_ID
111
+ ** macro is a string which identifies a particular check-in of SQLite
112
+ ** within its configuration management system. The string contains the
113
+ ** date and time of the check-in (UTC) and an SHA1 hash of the entire
114
+ ** source tree.
102
115
  **
103
- ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
116
+ ** See also: [sqlite3_libversion()],
117
+ ** [sqlite3_libversion_number()], [sqlite3_sourceid()],
118
+ ** [sqlite_version()] and [sqlite_source_id()].
104
119
  **
105
120
  ** Requirements: [H10011] [H10014]
106
121
  */
107
- #define SQLITE_VERSION "3.6.17"
108
- #define SQLITE_VERSION_NUMBER 3006017
122
+ #define SQLITE_VERSION "3.6.19"
123
+ #define SQLITE_VERSION_NUMBER 3006019
124
+ #define SQLITE_SOURCE_ID "2009-10-14 11:33:55 c1d499afc50d54b376945b4efb65c56c787a073d"
109
125
 
110
126
  /*
111
127
  ** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100>
112
128
  ** KEYWORDS: sqlite3_version
113
129
  **
114
- ** These features provide the same information as the [SQLITE_VERSION]
115
- ** and [SQLITE_VERSION_NUMBER] #defines in the header, but are associated
116
- ** with the library instead of the header file. Cautious programmers might
117
- ** include a check in their application to verify that
118
- ** sqlite3_libversion_number() always returns the value
119
- ** [SQLITE_VERSION_NUMBER].
130
+ ** These interfaces provide the same information as the [SQLITE_VERSION],
131
+ ** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] #defines in the header,
132
+ ** but are associated with the library instead of the header file. Cautious
133
+ ** programmers might include assert() statements in their application to
134
+ ** verify that values returned by these interfaces match the macros in
135
+ ** the header, and thus insure that the application is
136
+ ** compiled with matching library and header files.
137
+ **
138
+ ** <blockquote><pre>
139
+ ** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
140
+ ** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
141
+ ** assert( strcmp(sqlite3_libversion,SQLITE_VERSION)==0 );
142
+ ** </pre></blockquote>
120
143
  **
121
144
  ** The sqlite3_libversion() function returns the same information as is
122
145
  ** in the sqlite3_version[] string constant. The function is provided
123
146
  ** for use in DLLs since DLL users usually do not have direct access to string
124
- ** constants within the DLL.
147
+ ** constants within the DLL. Similarly, the sqlite3_sourceid() function
148
+ ** returns the same information as is in the [SQLITE_SOURCE_ID] #define of
149
+ ** the header file.
150
+ **
151
+ ** See also: [sqlite_version()] and [sqlite_source_id()].
125
152
  **
126
153
  ** Requirements: [H10021] [H10022] [H10023]
127
154
  */
128
155
  SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
129
156
  SQLITE_API const char *sqlite3_libversion(void);
157
+ SQLITE_API const char *sqlite3_sourceid(void);
130
158
  SQLITE_API int sqlite3_libversion_number(void);
131
159
 
132
160
  /*
133
161
  ** CAPI3REF: Test To See If The Library Is Threadsafe {H10100} <S60100>
134
162
  **
135
163
  ** SQLite can be compiled with or without mutexes. When
136
- ** the [SQLITE_THREADSAFE] C preprocessor macro 1 or 2, mutexes
164
+ ** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
137
165
  ** are enabled and SQLite is threadsafe. When the
138
166
  ** [SQLITE_THREADSAFE] macro is 0,
139
167
  ** the mutexes are omitted. Without the mutexes, it is not safe
@@ -144,7 +172,7 @@ SQLITE_API int sqlite3_libversion_number(void);
144
172
  ** the mutexes. But for maximum safety, mutexes should be enabled.
145
173
  ** The default behavior is for mutexes to be enabled.
146
174
  **
147
- ** This interface can be used by a program to make sure that the
175
+ ** This interface can be used by an application to make sure that the
148
176
  ** version of SQLite that it is linking against was compiled with
149
177
  ** the desired setting of the [SQLITE_THREADSAFE] macro.
150
178
  **
@@ -411,6 +439,8 @@ SQLITE_API int sqlite3_exec(
411
439
  #define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */
412
440
  #define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */
413
441
  #define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */
442
+ #define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */
443
+ #define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
414
444
 
415
445
  /*
416
446
  ** CAPI3REF: Device Characteristics {H10240} <H11120>
@@ -478,8 +508,9 @@ SQLITE_API int sqlite3_exec(
478
508
  /*
479
509
  ** CAPI3REF: OS Interface Open File Handle {H11110} <S20110>
480
510
  **
481
- ** An [sqlite3_file] object represents an open file in the OS
482
- ** interface layer. Individual OS interface implementations will
511
+ ** An [sqlite3_file] object represents an open file in the
512
+ ** [sqlite3_vfs | OS interface layer]. Individual OS interface
513
+ ** implementations will
483
514
  ** want to subclass this object by appending additional fields
484
515
  ** for their own use. The pMethods entry is a pointer to an
485
516
  ** [sqlite3_io_methods] object that defines methods for performing
@@ -855,8 +886,9 @@ struct sqlite3_vfs {
855
886
  ** interface is called automatically by sqlite3_initialize() and
856
887
  ** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
857
888
  ** implementations for sqlite3_os_init() and sqlite3_os_end()
858
- ** are built into SQLite when it is compiled for unix, windows, or os/2.
859
- ** When built for other platforms (using the [SQLITE_OS_OTHER=1] compile-time
889
+ ** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
890
+ ** When [custom builds | built for other platforms]
891
+ ** (using the [SQLITE_OS_OTHER=1] compile-time
860
892
  ** option) the application must supply a suitable implementation for
861
893
  ** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
862
894
  ** implementation of sqlite3_os_init() or sqlite3_os_end()
@@ -937,13 +969,15 @@ SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
937
969
  ** This object is used in only one place in the SQLite interface.
938
970
  ** A pointer to an instance of this object is the argument to
939
971
  ** [sqlite3_config()] when the configuration option is
940
- ** [SQLITE_CONFIG_MALLOC]. By creating an instance of this object
941
- ** and passing it to [sqlite3_config()] during configuration, an
942
- ** application can specify an alternative memory allocation subsystem
943
- ** for SQLite to use for all of its dynamic memory needs.
944
- **
945
- ** Note that SQLite comes with a built-in memory allocator that is
946
- ** perfectly adequate for the overwhelming majority of applications
972
+ ** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].
973
+ ** By creating an instance of this object
974
+ ** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
975
+ ** during configuration, an application can specify an alternative
976
+ ** memory allocation subsystem for SQLite to use for all of its
977
+ ** dynamic memory needs.
978
+ **
979
+ ** Note that SQLite comes with several [built-in memory allocators]
980
+ ** that are perfectly adequate for the overwhelming majority of applications
947
981
  ** and that this object is only useful to a tiny minority of applications
948
982
  ** with specialized memory allocation requirements. This object is
949
983
  ** also used during testing of SQLite in order to specify an alternative
@@ -951,8 +985,16 @@ SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
951
985
  ** order to verify that SQLite recovers gracefully from such
952
986
  ** conditions.
953
987
  **
954
- ** The xMalloc, xFree, and xRealloc methods must work like the
955
- ** malloc(), free(), and realloc() functions from the standard library.
988
+ ** The xMalloc and xFree methods must work like the
989
+ ** malloc() and free() functions from the standard C library.
990
+ ** The xRealloc method must work like realloc() from the standard C library
991
+ ** with the exception that if the second argument to xRealloc is zero,
992
+ ** xRealloc must be a no-op - it must not perform any allocation or
993
+ ** deallocation. SQLite guaranteeds that the second argument to
994
+ ** xRealloc is always a value returned by a prior call to xRoundup.
995
+ ** And so in cases where xRoundup always returns a positive number,
996
+ ** xRealloc can perform exactly as the standard library realloc() and
997
+ ** still be in compliance with this specification.
956
998
  **
957
999
  ** xSize should return the allocated size of a memory allocation
958
1000
  ** previously obtained from xMalloc or xRealloc. The allocated size
@@ -962,6 +1004,9 @@ SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
962
1004
  ** a memory allocation given a particular requested size. Most memory
963
1005
  ** allocators round up memory allocations at least to the next multiple
964
1006
  ** of 8. Some allocators round up to a larger multiple or to a power of 2.
1007
+ ** Every memory allocation request coming in through [sqlite3_malloc()]
1008
+ ** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0,
1009
+ ** that causes the corresponding memory allocation to fail.
965
1010
  **
966
1011
  ** The xInit method initializes the memory allocator. (For example,
967
1012
  ** it might allocate any require mutexes or initialize internal data
@@ -969,6 +1014,20 @@ SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
969
1014
  ** [sqlite3_shutdown()] and should deallocate any resources acquired
970
1015
  ** by xInit. The pAppData pointer is used as the only parameter to
971
1016
  ** xInit and xShutdown.
1017
+ **
1018
+ ** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes
1019
+ ** the xInit method, so the xInit method need not be threadsafe. The
1020
+ ** xShutdown method is only called from [sqlite3_shutdown()] so it does
1021
+ ** not need to be threadsafe either. For all other methods, SQLite
1022
+ ** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
1023
+ ** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
1024
+ ** it is by default) and so the methods are automatically serialized.
1025
+ ** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
1026
+ ** methods must be threadsafe or else make their own arrangements for
1027
+ ** serialization.
1028
+ **
1029
+ ** SQLite will never invoke xInit() more than once without an intervening
1030
+ ** call to xShutdown().
972
1031
  */
973
1032
  typedef struct sqlite3_mem_methods sqlite3_mem_methods;
974
1033
  struct sqlite3_mem_methods {
@@ -1122,9 +1181,12 @@ struct sqlite3_mem_methods {
1122
1181
  **
1123
1182
  ** <dt>SQLITE_CONFIG_LOOKASIDE</dt>
1124
1183
  ** <dd>This option takes two arguments that determine the default
1125
- ** memory allcation lookaside optimization. The first argument is the
1184
+ ** memory allocation lookaside optimization. The first argument is the
1126
1185
  ** size of each lookaside buffer slot and the second is the number of
1127
- ** slots allocated to each database connection.</dd>
1186
+ ** slots allocated to each database connection. This option sets the
1187
+ ** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
1188
+ ** verb to [sqlite3_db_config()] can be used to change the lookaside
1189
+ ** configuration on individual connections.</dd>
1128
1190
  **
1129
1191
  ** <dt>SQLITE_CONFIG_PCACHE</dt>
1130
1192
  ** <dd>This option takes a single argument which is a pointer to
@@ -1174,12 +1236,15 @@ struct sqlite3_mem_methods {
1174
1236
  ** <dd>This option takes three additional arguments that determine the
1175
1237
  ** [lookaside memory allocator] configuration for the [database connection].
1176
1238
  ** The first argument (the third parameter to [sqlite3_db_config()] is a
1177
- ** pointer to an 8-byte aligned memory buffer to use for lookaside memory.
1239
+ ** pointer to an memory buffer to use for lookaside memory.
1178
1240
  ** The first argument may be NULL in which case SQLite will allocate the
1179
1241
  ** lookaside buffer itself using [sqlite3_malloc()]. The second argument is the
1180
1242
  ** size of each lookaside buffer slot and the third argument is the number of
1181
1243
  ** slots. The size of the buffer in the first argument must be greater than
1182
- ** or equal to the product of the second and third arguments.</dd>
1244
+ ** or equal to the product of the second and third arguments. The buffer
1245
+ ** must be aligned to an 8-byte boundary. If the second argument is not
1246
+ ** a multiple of 8, it is internally rounded down to the next smaller
1247
+ ** multiple of 8. See also: [SQLITE_CONFIG_LOOKASIDE]</dd>
1183
1248
  **
1184
1249
  ** </dl>
1185
1250
  */
@@ -1251,8 +1316,9 @@ SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
1251
1316
  ** on the [database connection] specified by the first parameter.
1252
1317
  ** Only changes that are directly specified by the [INSERT], [UPDATE],
1253
1318
  ** or [DELETE] statement are counted. Auxiliary changes caused by
1254
- ** triggers are not counted. Use the [sqlite3_total_changes()] function
1255
- ** to find the total number of changes including changes caused by triggers.
1319
+ ** triggers or [foreign key actions] are not counted. Use the
1320
+ ** [sqlite3_total_changes()] function to find the total number of changes
1321
+ ** including changes caused by triggers and foreign key actions.
1256
1322
  **
1257
1323
  ** Changes to a view that are simulated by an [INSTEAD OF trigger]
1258
1324
  ** are not counted. Only real table changes are counted.
@@ -1304,8 +1370,8 @@ SQLITE_API int sqlite3_changes(sqlite3*);
1304
1370
  **
1305
1371
  ** This function returns the number of row changes caused by [INSERT],
1306
1372
  ** [UPDATE] or [DELETE] statements since the [database connection] was opened.
1307
- ** The count includes all changes from all
1308
- ** [CREATE TRIGGER | trigger] contexts. However,
1373
+ ** The count includes all changes from all [CREATE TRIGGER | trigger]
1374
+ ** contexts and changes made by [foreign key actions]. However,
1309
1375
  ** the count does not include changes used to implement [REPLACE] constraints,
1310
1376
  ** do rollbacks or ABORT processing, or [DROP TABLE] processing. The
1311
1377
  ** count does not include rows of views that fire an [INSTEAD OF trigger],
@@ -1583,7 +1649,7 @@ SQLITE_API void sqlite3_free_table(char **result);
1583
1649
  /*
1584
1650
  ** CAPI3REF: Formatted String Printing Functions {H17400} <S70000><S20000>
1585
1651
  **
1586
- ** These routines are workalikes of the "printf()" family of functions
1652
+ ** These routines are work-alikes of the "printf()" family of functions
1587
1653
  ** from the standard C library.
1588
1654
  **
1589
1655
  ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
@@ -1870,7 +1936,7 @@ SQLITE_API void sqlite3_randomness(int N, void *P);
1870
1936
  ** database connections for the meaning of "modify" in this paragraph.
1871
1937
  **
1872
1938
  ** When [sqlite3_prepare_v2()] is used to prepare a statement, the
1873
- ** statement might be reprepared during [sqlite3_step()] due to a
1939
+ ** statement might be re-prepared during [sqlite3_step()] due to a
1874
1940
  ** schema change. Hence, the application should ensure that the
1875
1941
  ** correct authorizer callback remains in place during the [sqlite3_step()].
1876
1942
  **
@@ -2037,7 +2103,8 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
2037
2103
  ** except that it accepts two additional parameters for additional control
2038
2104
  ** over the new database connection. The flags parameter can take one of
2039
2105
  ** the following three values, optionally combined with the
2040
- ** [SQLITE_OPEN_NOMUTEX] or [SQLITE_OPEN_FULLMUTEX] flags:
2106
+ ** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
2107
+ ** and/or [SQLITE_OPEN_PRIVATECACHE] flags:
2041
2108
  **
2042
2109
  ** <dl>
2043
2110
  ** <dt>[SQLITE_OPEN_READONLY]</dt>
@@ -2057,7 +2124,8 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
2057
2124
  **
2058
2125
  ** If the 3rd parameter to sqlite3_open_v2() is not one of the
2059
2126
  ** combinations shown above or one of the combinations shown above combined
2060
- ** with the [SQLITE_OPEN_NOMUTEX] or [SQLITE_OPEN_FULLMUTEX] flags,
2127
+ ** with the [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX],
2128
+ ** [SQLITE_OPEN_SHAREDCACHE] and/or [SQLITE_OPEN_SHAREDCACHE] flags,
2061
2129
  ** then the behavior is undefined.
2062
2130
  **
2063
2131
  ** If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
@@ -2066,6 +2134,11 @@ SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
2066
2134
  ** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
2067
2135
  ** in the serialized [threading mode] unless single-thread was
2068
2136
  ** previously selected at compile-time or start-time.
2137
+ ** The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
2138
+ ** eligible to use [shared cache mode], regardless of whether or not shared
2139
+ ** cache is enabled using [sqlite3_enable_shared_cache()]. The
2140
+ ** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
2141
+ ** participate in [shared cache mode] even if it is enabled.
2069
2142
  **
2070
2143
  ** If the filename is ":memory:", then a private, temporary in-memory database
2071
2144
  ** is created for the connection. This in-memory database will vanish when
@@ -2259,6 +2332,9 @@ SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
2259
2332
  ** <dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
2260
2333
  ** <dd>The maximum number of variables in an SQL statement that can
2261
2334
  ** be bound.</dd>
2335
+ **
2336
+ ** <dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
2337
+ ** <dd>The maximum depth of recursion for triggers.</dd>
2262
2338
  ** </dl>
2263
2339
  */
2264
2340
  #define SQLITE_LIMIT_LENGTH 0
@@ -2271,6 +2347,7 @@ SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
2271
2347
  #define SQLITE_LIMIT_ATTACHED 7
2272
2348
  #define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8
2273
2349
  #define SQLITE_LIMIT_VARIABLE_NUMBER 9
2350
+ #define SQLITE_LIMIT_TRIGGER_DEPTH 10
2274
2351
 
2275
2352
  /*
2276
2353
  ** CAPI3REF: Compiling An SQL Statement {H13010} <S10000>
@@ -2447,7 +2524,8 @@ typedef struct sqlite3_context sqlite3_context;
2447
2524
  ** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
2448
2525
  **
2449
2526
  ** In the SQL strings input to [sqlite3_prepare_v2()] and its variants,
2450
- ** literals may be replaced by a [parameter] in one of these forms:
2527
+ ** literals may be replaced by a [parameter] that matches one of following
2528
+ ** templates:
2451
2529
  **
2452
2530
  ** <ul>
2453
2531
  ** <li> ?
@@ -2457,8 +2535,8 @@ typedef struct sqlite3_context sqlite3_context;
2457
2535
  ** <li> $VVV
2458
2536
  ** </ul>
2459
2537
  **
2460
- ** In the parameter forms shown above NNN is an integer literal,
2461
- ** and VVV is an alpha-numeric parameter name. The values of these
2538
+ ** In the templates above, NNN represents an integer literal,
2539
+ ** and VVV represents an alphanumeric identifer. The values of these
2462
2540
  ** parameters (also called "host parameter names" or "SQL parameters")
2463
2541
  ** can be set using the sqlite3_bind_*() routines defined here.
2464
2542
  **
@@ -3110,7 +3188,7 @@ SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
3110
3188
  ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
3111
3189
  ** its parameters. Any SQL function implementation should be able to work
3112
3190
  ** work with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
3113
- ** more efficient with one encoding than another. It is allowed to
3191
+ ** more efficient with one encoding than another. An application may
3114
3192
  ** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
3115
3193
  ** times with the same function but with different values of eTextRep.
3116
3194
  ** When multiple implementations of the same function are available, SQLite
@@ -3132,7 +3210,7 @@ SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
3132
3210
  ** It is permitted to register multiple implementations of the same
3133
3211
  ** functions with the same name but with either differing numbers of
3134
3212
  ** arguments or differing preferred text encodings. SQLite will use
3135
- ** the implementation most closely matches the way in which the
3213
+ ** the implementation that most closely matches the way in which the
3136
3214
  ** SQL function is used. A function implementation with a non-negative
3137
3215
  ** nArg parameter is a better match than a function implementation with
3138
3216
  ** a negative nArg. A function where the preferred text encoding
@@ -3480,10 +3558,11 @@ typedef void (*sqlite3_destructor_type)(void*);
3480
3558
  ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
3481
3559
  ** function as the destructor on the text or BLOB result when it has
3482
3560
  ** finished using that result.
3483
- ** If the 4th parameter to the sqlite3_result_text* interfaces or
3561
+ ** If the 4th parameter to the sqlite3_result_text* interfaces or to
3484
3562
  ** sqlite3_result_blob is the special constant SQLITE_STATIC, then SQLite
3485
3563
  ** assumes that the text or BLOB result is in constant space and does not
3486
- ** copy the it or call a destructor when it has finished using that result.
3564
+ ** copy the content of the parameter nor call a destructor on the content
3565
+ ** when it has finished using that result.
3487
3566
  ** If the 4th parameter to the sqlite3_result_text* interfaces
3488
3567
  ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
3489
3568
  ** then SQLite makes a copy of the result into space obtained from
@@ -4433,6 +4512,9 @@ typedef struct sqlite3_blob sqlite3_blob;
4433
4512
  **
4434
4513
  ** If the flags parameter is non-zero, then the BLOB is opened for read
4435
4514
  ** and write access. If it is zero, the BLOB is opened for read access.
4515
+ ** It is not possible to open a column that is part of an index or primary
4516
+ ** key for writing. ^If [foreign key constraints] are enabled, it is
4517
+ ** not possible to open a column that is part of a [child key] for writing.
4436
4518
  **
4437
4519
  ** Note that the database name is not the filename that contains
4438
4520
  ** the database but rather the symbolic name of the database that
@@ -4462,7 +4544,7 @@ typedef struct sqlite3_blob sqlite3_blob;
4462
4544
  **
4463
4545
  ** Use the [sqlite3_blob_bytes()] interface to determine the size of
4464
4546
  ** the opened blob. The size of a blob may not be changed by this
4465
- ** underface. Use the [UPDATE] SQL command to change the size of a
4547
+ ** interface. Use the [UPDATE] SQL command to change the size of a
4466
4548
  ** blob.
4467
4549
  **
4468
4550
  ** The [sqlite3_bind_zeroblob()] and [sqlite3_result_zeroblob()] interfaces
@@ -4702,7 +4784,7 @@ SQLITE_API int sqlite3_vfs_unregister(sqlite3_vfs*);
4702
4784
  ** might return such a mutex in response to SQLITE_MUTEX_FAST.
4703
4785
  **
4704
4786
  ** {H17017} The other allowed parameters to sqlite3_mutex_alloc() each return
4705
- ** a pointer to a static preexisting mutex. {END} Four static mutexes are
4787
+ ** a pointer to a static preexisting mutex. {END} Six static mutexes are
4706
4788
  ** used by the current version of SQLite. Future versions of SQLite
4707
4789
  ** may add additional static mutexes. Static mutexes are for internal
4708
4790
  ** use by SQLite only. Applications that use SQLite mutexes should
@@ -4808,6 +4890,21 @@ SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*);
4808
4890
  ** of passing a NULL pointer instead of a valid mutex handle are undefined
4809
4891
  ** (i.e. it is acceptable to provide an implementation that segfaults if
4810
4892
  ** it is passed a NULL pointer).
4893
+ **
4894
+ ** The xMutexInit() method must be threadsafe. It must be harmless to
4895
+ ** invoke xMutexInit() mutiple times within the same process and without
4896
+ ** intervening calls to xMutexEnd(). Second and subsequent calls to
4897
+ ** xMutexInit() must be no-ops.
4898
+ **
4899
+ ** xMutexInit() must not use SQLite memory allocation ([sqlite3_malloc()]
4900
+ ** and its associates). Similarly, xMutexAlloc() must not use SQLite memory
4901
+ ** allocation for a static mutex. However xMutexAlloc() may use SQLite
4902
+ ** memory allocation for a fast or recursive mutex.
4903
+ **
4904
+ ** SQLite will invoke the xMutexEnd() method when [sqlite3_shutdown()] is
4905
+ ** called, but only if the prior call to xMutexInit returned SQLITE_OK.
4906
+ ** If xMutexInit fails in any way, it is expected to clean up after itself
4907
+ ** prior to returning.
4811
4908
  */
4812
4909
  typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
4813
4910
  struct sqlite3_mutex_methods {
@@ -4973,7 +5070,7 @@ SQLITE_API int sqlite3_test_control(int op, ...);
4973
5070
  ** This routine returns SQLITE_OK on success and a non-zero
4974
5071
  ** [error code] on failure.
4975
5072
  **
4976
- ** This routine is threadsafe but is not atomic. This routine can
5073
+ ** This routine is threadsafe but is not atomic. This routine can be
4977
5074
  ** called while other threads are running the same or different SQLite
4978
5075
  ** interfaces. However the values returned in *pCurrent and
4979
5076
  ** *pHighwater reflect the status of SQLite at different points in time
@@ -5096,7 +5193,14 @@ SQLITE_API SQLITE_EXPERIMENTAL int sqlite3_db_status(sqlite3*, int op, int *pCur
5096
5193
  ** CAPI3REF: Status Parameters for database connections {H17520} <H17500>
5097
5194
  ** EXPERIMENTAL
5098
5195
  **
5099
- ** Status verbs for [sqlite3_db_status()].
5196
+ ** These constants are the available integer "verbs" that can be passed as
5197
+ ** the second argument to the [sqlite3_db_status()] interface.
5198
+ **
5199
+ ** New verbs may be added in future releases of SQLite. Existing verbs
5200
+ ** might be discontinued. Applications should check the return code from
5201
+ ** [sqlite3_db_status()] to make sure that the call worked.
5202
+ ** The [sqlite3_db_status()] interface will return a non-zero error code
5203
+ ** if a discontinued or unsupported verb is invoked.
5100
5204
  **
5101
5205
  ** <dl>
5102
5206
  ** <dt>SQLITE_DBSTATUS_LOOKASIDE_USED</dt>
@@ -5174,95 +5278,109 @@ typedef struct sqlite3_pcache sqlite3_pcache;
5174
5278
 
5175
5279
  /*
5176
5280
  ** CAPI3REF: Application Defined Page Cache.
5281
+ ** KEYWORDS: {page cache}
5177
5282
  ** EXPERIMENTAL
5178
5283
  **
5179
5284
  ** The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
5180
5285
  ** register an alternative page cache implementation by passing in an
5181
5286
  ** instance of the sqlite3_pcache_methods structure. The majority of the
5182
- ** heap memory used by sqlite is used by the page cache to cache data read
5287
+ ** heap memory used by SQLite is used by the page cache to cache data read
5183
5288
  ** from, or ready to be written to, the database file. By implementing a
5184
5289
  ** custom page cache using this API, an application can control more
5185
- ** precisely the amount of memory consumed by sqlite, the way in which
5186
- ** said memory is allocated and released, and the policies used to
5290
+ ** precisely the amount of memory consumed by SQLite, the way in which
5291
+ ** that memory is allocated and released, and the policies used to
5187
5292
  ** determine exactly which parts of a database file are cached and for
5188
5293
  ** how long.
5189
5294
  **
5190
- ** The contents of the structure are copied to an internal buffer by sqlite
5191
- ** within the call to [sqlite3_config].
5295
+ ** The contents of the sqlite3_pcache_methods structure are copied to an
5296
+ ** internal buffer by SQLite within the call to [sqlite3_config]. Hence
5297
+ ** the application may discard the parameter after the call to
5298
+ ** [sqlite3_config()] returns.
5192
5299
  **
5193
5300
  ** The xInit() method is called once for each call to [sqlite3_initialize()]
5194
5301
  ** (usually only once during the lifetime of the process). It is passed
5195
5302
  ** a copy of the sqlite3_pcache_methods.pArg value. It can be used to set
5196
5303
  ** up global structures and mutexes required by the custom page cache
5197
- ** implementation. The xShutdown() method is called from within
5198
- ** [sqlite3_shutdown()], if the application invokes this API. It can be used
5199
- ** to clean up any outstanding resources before process shutdown, if required.
5304
+ ** implementation.
5305
+ **
5306
+ ** The xShutdown() method is called from within [sqlite3_shutdown()],
5307
+ ** if the application invokes this API. It can be used to clean up
5308
+ ** any outstanding resources before process shutdown, if required.
5309
+ **
5310
+ ** SQLite holds a [SQLITE_MUTEX_RECURSIVE] mutex when it invokes
5311
+ ** the xInit method, so the xInit method need not be threadsafe. The
5312
+ ** xShutdown method is only called from [sqlite3_shutdown()] so it does
5313
+ ** not need to be threadsafe either. All other methods must be threadsafe
5314
+ ** in multithreaded applications.
5200
5315
  **
5201
- ** The xCreate() method is used to construct a new cache instance. The
5316
+ ** SQLite will never invoke xInit() more than once without an intervening
5317
+ ** call to xShutdown().
5318
+ **
5319
+ ** The xCreate() method is used to construct a new cache instance. SQLite
5320
+ ** will typically create one cache instance for each open database file,
5321
+ ** though this is not guaranteed. The
5202
5322
  ** first parameter, szPage, is the size in bytes of the pages that must
5203
- ** be allocated by the cache. szPage will not be a power of two. The
5204
- ** second argument, bPurgeable, is true if the cache being created will
5205
- ** be used to cache database pages read from a file stored on disk, or
5323
+ ** be allocated by the cache. szPage will not be a power of two. szPage
5324
+ ** will the page size of the database file that is to be cached plus an
5325
+ ** increment (here called "R") of about 100 or 200. SQLite will use the
5326
+ ** extra R bytes on each page to store metadata about the underlying
5327
+ ** database page on disk. The value of R depends
5328
+ ** on the SQLite version, the target platform, and how SQLite was compiled.
5329
+ ** R is constant for a particular build of SQLite. The second argument to
5330
+ ** xCreate(), bPurgeable, is true if the cache being created will
5331
+ ** be used to cache database pages of a file stored on disk, or
5206
5332
  ** false if it is used for an in-memory database. The cache implementation
5207
- ** does not have to do anything special based on the value of bPurgeable,
5208
- ** it is purely advisory.
5333
+ ** does not have to do anything special based with the value of bPurgeable;
5334
+ ** it is purely advisory. On a cache where bPurgeable is false, SQLite will
5335
+ ** never invoke xUnpin() except to deliberately delete a page.
5336
+ ** In other words, a cache created with bPurgeable set to false will
5337
+ ** never contain any unpinned pages.
5209
5338
  **
5210
5339
  ** The xCachesize() method may be called at any time by SQLite to set the
5211
5340
  ** suggested maximum cache-size (number of pages stored by) the cache
5212
5341
  ** instance passed as the first argument. This is the value configured using
5213
5342
  ** the SQLite "[PRAGMA cache_size]" command. As with the bPurgeable parameter,
5214
- ** the implementation is not required to do anything special with this
5215
- ** value, it is advisory only.
5343
+ ** the implementation is not required to do anything with this
5344
+ ** value; it is advisory only.
5216
5345
  **
5217
5346
  ** The xPagecount() method should return the number of pages currently
5218
- ** stored in the cache supplied as an argument.
5347
+ ** stored in the cache.
5219
5348
  **
5220
5349
  ** The xFetch() method is used to fetch a page and return a pointer to it.
5221
5350
  ** A 'page', in this context, is a buffer of szPage bytes aligned at an
5222
5351
  ** 8-byte boundary. The page to be fetched is determined by the key. The
5223
5352
  ** mimimum key value is 1. After it has been retrieved using xFetch, the page
5224
- ** is considered to be pinned.
5353
+ ** is considered to be "pinned".
5225
5354
  **
5226
- ** If the requested page is already in the page cache, then a pointer to
5227
- ** the cached buffer should be returned with its contents intact. If the
5228
- ** page is not already in the cache, then the expected behaviour of the
5229
- ** cache is determined by the value of the createFlag parameter passed
5230
- ** to xFetch, according to the following table:
5355
+ ** If the requested page is already in the page cache, then the page cache
5356
+ ** implementation must return a pointer to the page buffer with its content
5357
+ ** intact. If the requested page is not already in the cache, then the
5358
+ ** behavior of the cache implementation is determined by the value of the
5359
+ ** createFlag parameter passed to xFetch, according to the following table:
5231
5360
  **
5232
5361
  ** <table border=1 width=85% align=center>
5233
- ** <tr><th>createFlag<th>Expected Behaviour
5234
- ** <tr><td>0<td>NULL should be returned. No new cache entry is created.
5235
- ** <tr><td>1<td>If createFlag is set to 1, this indicates that
5236
- ** SQLite is holding pinned pages that can be unpinned
5237
- ** by writing their contents to the database file (a
5238
- ** relatively expensive operation). In this situation the
5239
- ** cache implementation has two choices: it can return NULL,
5240
- ** in which case SQLite will attempt to unpin one or more
5241
- ** pages before re-requesting the same page, or it can
5242
- ** allocate a new page and return a pointer to it. If a new
5243
- ** page is allocated, then the first sizeof(void*) bytes of
5244
- ** it (at least) must be zeroed before it is returned.
5245
- ** <tr><td>2<td>If createFlag is set to 2, then SQLite is not holding any
5246
- ** pinned pages associated with the specific cache passed
5247
- ** as the first argument to xFetch() that can be unpinned. The
5248
- ** cache implementation should attempt to allocate a new
5249
- ** cache entry and return a pointer to it. Again, the first
5250
- ** sizeof(void*) bytes of the page should be zeroed before
5251
- ** it is returned. If the xFetch() method returns NULL when
5252
- ** createFlag==2, SQLite assumes that a memory allocation
5253
- ** failed and returns SQLITE_NOMEM to the user.
5362
+ ** <tr><th> createFlag <th> Behaviour when page is not already in cache
5363
+ ** <tr><td> 0 <td> Do not allocate a new page. Return NULL.
5364
+ ** <tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
5365
+ ** Otherwise return NULL.
5366
+ ** <tr><td> 2 <td> Make every effort to allocate a new page. Only return
5367
+ ** NULL if allocating a new page is effectively impossible.
5254
5368
  ** </table>
5255
5369
  **
5370
+ ** SQLite will normally invoke xFetch() with a createFlag of 0 or 1. If
5371
+ ** a call to xFetch() with createFlag==1 returns NULL, then SQLite will
5372
+ ** attempt to unpin one or more cache pages by spilling the content of
5373
+ ** pinned pages to disk and synching the operating system disk cache. After
5374
+ ** attempting to unpin pages, the xFetch() method will be invoked again with
5375
+ ** a createFlag of 2.
5376
+ **
5256
5377
  ** xUnpin() is called by SQLite with a pointer to a currently pinned page
5257
5378
  ** as its second argument. If the third parameter, discard, is non-zero,
5258
5379
  ** then the page should be evicted from the cache. In this case SQLite
5259
5380
  ** assumes that the next time the page is retrieved from the cache using
5260
5381
  ** the xFetch() method, it will be zeroed. If the discard parameter is
5261
5382
  ** zero, then the page is considered to be unpinned. The cache implementation
5262
- ** may choose to reclaim (free or recycle) unpinned pages at any time.
5263
- ** SQLite assumes that next time the page is retrieved from the cache
5264
- ** it will either be zeroed, or contain the same data that it did when it
5265
- ** was unpinned.
5383
+ ** may choose to evict unpinned pages at any time.
5266
5384
  **
5267
5385
  ** The cache is not required to perform any reference counting. A single
5268
5386
  ** call to xUnpin() unpins the page regardless of the number of prior calls