amalgalite 0.8.0-x86-mswin32-60 → 0.9.0-x86-mswin32-60

Sign up to get free protection for your applications and to get access to all the features.
data/ext/sqlite3.h CHANGED
@@ -30,7 +30,7 @@
30
30
  ** the version number) and changes its name to "sqlite3.h" as
31
31
  ** part of the build process.
32
32
  **
33
- ** @(#) $Id: sqlite.h.in,v 1.421 2008/12/30 06:24:58 danielk1977 Exp $
33
+ ** @(#) $Id: sqlite.h.in,v 1.436 2009/03/20 13:15:30 drh Exp $
34
34
  */
35
35
  #ifndef _SQLITE3_H_
36
36
  #define _SQLITE3_H_
@@ -97,18 +97,10 @@ extern "C" {
97
97
  **
98
98
  ** See also: [sqlite3_libversion()] and [sqlite3_libversion_number()].
99
99
  **
100
- ** INVARIANTS:
101
- **
102
- ** {H10011} The SQLITE_VERSION #define in the sqlite3.h header file shall
103
- ** evaluate to a string literal that is the SQLite version
104
- ** with which the header file is associated.
105
- **
106
- ** {H10014} The SQLITE_VERSION_NUMBER #define shall resolve to an integer
107
- ** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z
108
- ** are the major version, minor version, and release number.
100
+ ** Requirements: [H10011] [H10014]
109
101
  */
110
- #define SQLITE_VERSION "3.6.10"
111
- #define SQLITE_VERSION_NUMBER 3006010
102
+ #define SQLITE_VERSION "3.6.12"
103
+ #define SQLITE_VERSION_NUMBER 3006012
112
104
 
113
105
  /*
114
106
  ** CAPI3REF: Run-Time Library Version Numbers {H10020} <S60100>
@@ -126,16 +118,7 @@ extern "C" {
126
118
  ** for use in DLLs since DLL users usually do not have direct access to string
127
119
  ** constants within the DLL.
128
120
  **
129
- ** INVARIANTS:
130
- **
131
- ** {H10021} The [sqlite3_libversion_number()] interface shall return
132
- ** an integer equal to [SQLITE_VERSION_NUMBER].
133
- **
134
- ** {H10022} The [sqlite3_version] string constant shall contain
135
- ** the text of the [SQLITE_VERSION] string.
136
- **
137
- ** {H10023} The [sqlite3_libversion()] function shall return
138
- ** a pointer to the [sqlite3_version] string constant.
121
+ ** Requirements: [H10021] [H10022] [H10023]
139
122
  */
140
123
  SQLITE_EXTERN const char sqlite3_version[];
141
124
  const char *sqlite3_libversion(void);
@@ -171,13 +154,7 @@ int sqlite3_libversion_number(void);
171
154
  **
172
155
  ** See the [threading mode] documentation for additional information.
173
156
  **
174
- ** INVARIANTS:
175
- **
176
- ** {H10101} The [sqlite3_threadsafe()] function shall return zero if
177
- ** and only if SQLite was compiled with mutexing code omitted.
178
- **
179
- ** {H10102} The value returned by the [sqlite3_threadsafe()] function
180
- ** shall remain the same across calls to [sqlite3_config()].
157
+ ** Requirements: [H10101] [H10102]
181
158
  */
182
159
  int sqlite3_threadsafe(void);
183
160
 
@@ -207,13 +184,7 @@ typedef struct sqlite3 sqlite3;
207
184
  ** The sqlite_int64 and sqlite_uint64 types are supported for backwards
208
185
  ** compatibility only.
209
186
  **
210
- ** INVARIANTS:
211
- **
212
- ** {H10201} The [sqlite_int64] and [sqlite3_int64] type shall specify
213
- ** a 64-bit signed integer.
214
- **
215
- ** {H10202} The [sqlite_uint64] and [sqlite3_uint64] type shall specify
216
- ** a 64-bit unsigned integer.
187
+ ** Requirements: [H10201] [H10202]
217
188
  */
218
189
  #ifdef SQLITE_INT64_TYPE
219
190
  typedef SQLITE_INT64_TYPE sqlite_int64;
@@ -258,34 +229,13 @@ typedef sqlite_uint64 sqlite3_uint64;
258
229
  ** If [sqlite3_close()] is invoked while a transaction is open,
259
230
  ** the transaction is automatically rolled back.
260
231
  **
261
- ** INVARIANTS:
262
- **
263
- ** {H12011} A successful call to [sqlite3_close(C)] shall destroy the
264
- ** [database connection] object C.
265
- **
266
- ** {H12012} A successful call to [sqlite3_close(C)] shall return SQLITE_OK.
232
+ ** The C parameter to [sqlite3_close(C)] must be either a NULL
233
+ ** pointer or an [sqlite3] object pointer obtained
234
+ ** from [sqlite3_open()], [sqlite3_open16()], or
235
+ ** [sqlite3_open_v2()], and not previously closed.
267
236
  **
268
- ** {H12013} A successful call to [sqlite3_close(C)] shall release all
269
- ** memory and system resources associated with [database connection]
270
- ** C.
271
- **
272
- ** {H12014} A call to [sqlite3_close(C)] on a [database connection] C that
273
- ** has one or more open [prepared statements] shall fail with
274
- ** an [SQLITE_BUSY] error code.
275
- **
276
- ** {H12015} A call to [sqlite3_close(C)] where C is a NULL pointer shall
277
- ** be a harmless no-op returning SQLITE_OK.
278
- **
279
- ** {H12019} When [sqlite3_close(C)] is invoked on a [database connection] C
280
- ** that has a pending transaction, the transaction shall be
281
- ** rolled back.
282
- **
283
- ** ASSUMPTIONS:
284
- **
285
- ** {A12016} The C parameter to [sqlite3_close(C)] must be either a NULL
286
- ** pointer or an [sqlite3] object pointer obtained
287
- ** from [sqlite3_open()], [sqlite3_open16()], or
288
- ** [sqlite3_open_v2()], and not previously closed.
237
+ ** Requirements:
238
+ ** [H12011] [H12012] [H12013] [H12014] [H12015] [H12019]
289
239
  */
290
240
  int sqlite3_close(sqlite3 *);
291
241
 
@@ -323,86 +273,22 @@ typedef int (*sqlite3_callback)(void*,int,char**, char**);
323
273
  ** The sqlite3_exec() routine does nothing to the database that cannot be done
324
274
  ** by [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()].
325
275
  **
326
- ** INVARIANTS:
327
- **
328
- ** {H12101} A successful invocation of [sqlite3_exec(D,S,C,A,E)]
329
- ** shall sequentially evaluate all of the UTF-8 encoded,
330
- ** semicolon-separated SQL statements in the zero-terminated
331
- ** string S within the context of the [database connection] D.
332
- **
333
- ** {H12102} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL then
334
- ** the actions of the interface shall be the same as if the
335
- ** S parameter were an empty string.
336
- **
337
- ** {H12104} The return value of [sqlite3_exec()] shall be [SQLITE_OK] if all
338
- ** SQL statements run successfully and to completion.
339
- **
340
- ** {H12105} The return value of [sqlite3_exec()] shall be an appropriate
341
- ** non-zero [error code] if any SQL statement fails.
342
- **
343
- ** {H12107} If one or more of the SQL statements handed to [sqlite3_exec()]
344
- ** return results and the 3rd parameter is not NULL, then
345
- ** the callback function specified by the 3rd parameter shall be
346
- ** invoked once for each row of result.
276
+ ** The first parameter to [sqlite3_exec()] must be an valid and open
277
+ ** [database connection].
347
278
  **
348
- ** {H12110} If the callback returns a non-zero value then [sqlite3_exec()]
349
- ** shall abort the SQL statement it is currently evaluating,
350
- ** skip all subsequent SQL statements, and return [SQLITE_ABORT].
279
+ ** The database connection must not be closed while
280
+ ** [sqlite3_exec()] is running.
351
281
  **
352
- ** {H12113} The [sqlite3_exec()] routine shall pass its 4th parameter through
353
- ** as the 1st parameter of the callback.
282
+ ** The calling function should use [sqlite3_free()] to free
283
+ ** the memory that *errmsg is left pointing at once the error
284
+ ** message is no longer needed.
354
285
  **
355
- ** {H12116} The [sqlite3_exec()] routine shall set the 2nd parameter of its
356
- ** callback to be the number of columns in the current row of
357
- ** result.
286
+ ** The SQL statement text in the 2nd parameter to [sqlite3_exec()]
287
+ ** must remain unchanged while [sqlite3_exec()] is running.
358
288
  **
359
- ** {H12119} The [sqlite3_exec()] routine shall set the 3rd parameter of its
360
- ** callback to be an array of pointers to strings holding the
361
- ** values for each column in the current result set row as
362
- ** obtained from [sqlite3_column_text()].
363
- **
364
- ** {H12122} The [sqlite3_exec()] routine shall set the 4th parameter of its
365
- ** callback to be an array of pointers to strings holding the
366
- ** names of result columns as obtained from [sqlite3_column_name()].
367
- **
368
- ** {H12125} If the 3rd parameter to [sqlite3_exec()] is NULL then
369
- ** [sqlite3_exec()] shall silently discard query results.
370
- **
371
- ** {H12131} If an error occurs while parsing or evaluating any of the SQL
372
- ** statements in the S parameter of [sqlite3_exec(D,S,C,A,E)] and if
373
- ** the E parameter is not NULL, then [sqlite3_exec()] shall store
374
- ** in *E an appropriate error message written into memory obtained
375
- ** from [sqlite3_malloc()].
376
- **
377
- ** {H12134} The [sqlite3_exec(D,S,C,A,E)] routine shall set the value of
378
- ** *E to NULL if E is not NULL and there are no errors.
379
- **
380
- ** {H12137} The [sqlite3_exec(D,S,C,A,E)] function shall set the [error code]
381
- ** and message accessible via [sqlite3_errcode()],
382
- ** [sqlite3_extended_errcode()],
383
- ** [sqlite3_errmsg()], and [sqlite3_errmsg16()].
384
- **
385
- ** {H12138} If the S parameter to [sqlite3_exec(D,S,C,A,E)] is NULL or an
386
- ** empty string or contains nothing other than whitespace, comments,
387
- ** and/or semicolons, then results of [sqlite3_errcode()],
388
- ** [sqlite3_extended_errcode()],
389
- ** [sqlite3_errmsg()], and [sqlite3_errmsg16()]
390
- ** shall reset to indicate no errors.
391
- **
392
- ** ASSUMPTIONS:
393
- **
394
- ** {A12141} The first parameter to [sqlite3_exec()] must be an valid and open
395
- ** [database connection].
396
- **
397
- ** {A12142} The database connection must not be closed while
398
- ** [sqlite3_exec()] is running.
399
- **
400
- ** {A12143} The calling function should use [sqlite3_free()] to free
401
- ** the memory that *errmsg is left pointing at once the error
402
- ** message is no longer needed.
403
- **
404
- ** {A12145} The SQL statement text in the 2nd parameter to [sqlite3_exec()]
405
- ** must remain unchanged while [sqlite3_exec()] is running.
289
+ ** Requirements:
290
+ ** [H12101] [H12102] [H12104] [H12105] [H12107] [H12110] [H12113] [H12116]
291
+ ** [H12119] [H12122] [H12125] [H12131] [H12134] [H12137] [H12138]
406
292
  */
407
293
  int sqlite3_exec(
408
294
  sqlite3*, /* An open database */
@@ -478,19 +364,6 @@ int sqlite3_exec(
478
364
  **
479
365
  ** The SQLITE_OK result code will never be extended. It will always
480
366
  ** be exactly zero.
481
- **
482
- ** INVARIANTS:
483
- **
484
- ** {H10223} The symbolic name for an extended result code shall contains
485
- ** a related primary result code as a prefix.
486
- **
487
- ** {H10224} Primary result code names shall contain a single "_" character.
488
- **
489
- ** {H10225} Extended result code names shall contain two or more "_" characters.
490
- **
491
- ** {H10226} The numeric value of an extended result code shall contain the
492
- ** numeric value of its corresponding primary result code in
493
- ** its least significant 8 bits.
494
367
  */
495
368
  #define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
496
369
  #define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
@@ -510,6 +383,8 @@ int sqlite3_exec(
510
383
  #define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8))
511
384
  #define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8))
512
385
 
386
+ #define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8) )
387
+
513
388
  /*
514
389
  ** CAPI3REF: Flags For File Open Operations {H10230} <H11120> <H12700>
515
390
  **
@@ -995,94 +870,10 @@ int sqlite3_os_end(void);
995
870
  ** If the option is unknown or SQLite is unable to set the option
996
871
  ** then this routine returns a non-zero [error code].
997
872
  **
998
- ** INVARIANTS:
999
- **
1000
- ** {H14103} A successful invocation of [sqlite3_config()] shall return
1001
- ** [SQLITE_OK].
1002
- **
1003
- ** {H14106} The [sqlite3_config()] interface shall return [SQLITE_MISUSE]
1004
- ** if it is invoked in between calls to [sqlite3_initialize()] and
1005
- ** [sqlite3_shutdown()].
1006
- **
1007
- ** {H14120} A successful call to [sqlite3_config]([SQLITE_CONFIG_SINGLETHREAD])
1008
- ** shall set the default [threading mode] to Single-thread.
1009
- **
1010
- ** {H14123} A successful call to [sqlite3_config]([SQLITE_CONFIG_MULTITHREAD])
1011
- ** shall set the default [threading mode] to Multi-thread.
1012
- **
1013
- ** {H14126} A successful call to [sqlite3_config]([SQLITE_CONFIG_SERIALIZED])
1014
- ** shall set the default [threading mode] to Serialized.
1015
- **
1016
- ** {H14129} A successful call to [sqlite3_config]([SQLITE_CONFIG_MUTEX],X)
1017
- ** where X is a pointer to an initialized [sqlite3_mutex_methods]
1018
- ** object shall cause all subsequent mutex operations performed
1019
- ** by SQLite to use the mutex methods that were present in X
1020
- ** during the call to [sqlite3_config()].
1021
- **
1022
- ** {H14132} A successful call to [sqlite3_config]([SQLITE_CONFIG_GETMUTEX],X)
1023
- ** where X is a pointer to an [sqlite3_mutex_methods] object
1024
- ** shall overwrite the content of [sqlite3_mutex_methods] object
1025
- ** with the mutex methods currently in use by SQLite.
1026
- **
1027
- ** {H14135} A successful call to [sqlite3_config]([SQLITE_CONFIG_MALLOC],M)
1028
- ** where M is a pointer to an initialized [sqlite3_mem_methods]
1029
- ** object shall cause all subsequent memory allocation operations
1030
- ** performed by SQLite to use the methods that were present in
1031
- ** M during the call to [sqlite3_config()].
1032
- **
1033
- ** {H14138} A successful call to [sqlite3_config]([SQLITE_CONFIG_GETMALLOC],M)
1034
- ** where M is a pointer to an [sqlite3_mem_methods] object shall
1035
- ** overwrite the content of [sqlite3_mem_methods] object with
1036
- ** the memory allocation methods currently in use by
1037
- ** SQLite.
1038
- **
1039
- ** {H14141} A successful call to [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],1)
1040
- ** shall enable the memory allocation status collection logic.
1041
- **
1042
- ** {H14144} A successful call to [sqlite3_config]([SQLITE_CONFIG_MEMSTATUS],0)
1043
- ** shall disable the memory allocation status collection logic.
1044
- **
1045
- ** {H14147} The memory allocation status collection logic shall be
1046
- ** enabled by default.
1047
- **
1048
- ** {H14150} A successful call to [sqlite3_config]([SQLITE_CONFIG_SCRATCH],S,Z,N)
1049
- ** where Z and N are non-negative integers and
1050
- ** S is a pointer to an aligned memory buffer not less than
1051
- ** Z*N bytes in size shall cause S to be used by the
1052
- ** [scratch memory allocator] for as many as N simulataneous
1053
- ** allocations each of size (Z & ~7).
1054
- **
1055
- ** {H14153} A successful call to [sqlite3_config]([SQLITE_CONFIG_SCRATCH],S,Z,N)
1056
- ** where S is a NULL pointer shall disable the
1057
- ** [scratch memory allocator].
1058
- **
1059
- ** {H14156} A successful call to
1060
- ** [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],S,Z,N)
1061
- ** where Z and N are non-negative integers and
1062
- ** S is a pointer to an aligned memory buffer not less than
1063
- ** Z*N bytes in size shall cause S to be used by the
1064
- ** [pagecache memory allocator] for as many as N simulataneous
1065
- ** allocations each of size (Z & ~7).
1066
- **
1067
- ** {H14159} A successful call to
1068
- ** [sqlite3_config]([SQLITE_CONFIG_PAGECACHE],S,Z,N)
1069
- ** where S is a NULL pointer shall disable the
1070
- ** [pagecache memory allocator].
1071
- **
1072
- ** {H14162} A successful call to [sqlite3_config]([SQLITE_CONFIG_HEAP],H,Z,N)
1073
- ** where Z and N are non-negative integers and
1074
- ** H is a pointer to an aligned memory buffer not less than
1075
- ** Z bytes in size shall enable the [memsys5] memory allocator
1076
- ** and cause it to use buffer S as its memory source and to use
1077
- ** a minimum allocation size of N.
1078
- **
1079
- ** {H14165} A successful call to [sqlite3_config]([SQLITE_CONFIG_HEAP],H,Z,N)
1080
- ** where H is a NULL pointer shall disable the
1081
- ** [memsys5] memory allocator.
1082
- **
1083
- ** {H14168} A successful call to [sqlite3_config]([SQLITE_CONFIG_LOOKASIDE],Z,N)
1084
- ** shall cause the default [lookaside memory allocator] configuration
1085
- ** for new [database connections] to be N slots of Z bytes each.
873
+ ** Requirements:
874
+ ** [H14103] [H14106] [H14120] [H14123] [H14126] [H14129] [H14132] [H14135]
875
+ ** [H14138] [H14141] [H14144] [H14147] [H14150] [H14153] [H14156] [H14159]
876
+ ** [H14162] [H14165] [H14168]
1086
877
  */
1087
878
  SQLITE_EXPERIMENTAL int sqlite3_config(int, ...);
1088
879
 
@@ -1105,37 +896,8 @@ SQLITE_EXPERIMENTAL int sqlite3_config(int, ...);
1105
896
  ** New verbs are likely to be added in future releases of SQLite.
1106
897
  ** Additional arguments depend on the verb.
1107
898
  **
1108
- ** INVARIANTS:
1109
- **
1110
- ** {H14203} A call to [sqlite3_db_config(D,V,...)] shall return [SQLITE_OK]
1111
- ** if and only if the call is successful.
1112
- **
1113
- ** {H14206} If one or more slots of the [lookaside memory allocator] for
1114
- ** [database connection] D are in use, then a call to
1115
- ** [sqlite3_db_config](D,[SQLITE_DBCONFIG_LOOKASIDE],...) shall
1116
- ** fail with an [SQLITE_BUSY] return code.
1117
- **
1118
- ** {H14209} A successful call to
1119
- ** [sqlite3_db_config](D,[SQLITE_DBCONFIG_LOOKASIDE],B,Z,N) where
1120
- ** D is an open [database connection] and Z and N are positive
1121
- ** integers and B is an aligned buffer at least Z*N bytes in size
1122
- ** shall cause the [lookaside memory allocator] for D to use buffer B
1123
- ** with N slots of Z bytes each.
1124
- **
1125
- ** {H14212} A successful call to
1126
- ** [sqlite3_db_config](D,[SQLITE_DBCONFIG_LOOKASIDE],B,Z,N) where
1127
- ** D is an open [database connection] and Z and N are positive
1128
- ** integers and B is NULL pointer shall cause the
1129
- ** [lookaside memory allocator] for D to a obtain Z*N byte buffer
1130
- ** from the primary memory allocator and use that buffer
1131
- ** with N lookaside slots of Z bytes each.
1132
- **
1133
- ** {H14215} A successful call to
1134
- ** [sqlite3_db_config](D,[SQLITE_DBCONFIG_LOOKASIDE],B,Z,N) where
1135
- ** D is an open [database connection] and Z and N are zero shall
1136
- ** disable the [lookaside memory allocator] for D.
1137
- **
1138
- **
899
+ ** Requirements:
900
+ ** [H14203] [H14206] [H14209] [H14212] [H14215]
1139
901
  */
1140
902
  SQLITE_EXPERIMENTAL int sqlite3_db_config(sqlite3*, int op, ...);
1141
903
 
@@ -1395,14 +1157,8 @@ struct sqlite3_mem_methods {
1395
1157
  ** [extended result codes] feature of SQLite. The extended result
1396
1158
  ** codes are disabled by default for historical compatibility considerations.
1397
1159
  **
1398
- ** INVARIANTS:
1399
- **
1400
- ** {H12201} Each new [database connection] shall have the
1401
- ** [extended result codes] feature disabled by default.
1402
- **
1403
- ** {H12202} The [sqlite3_extended_result_codes(D,F)] interface shall enable
1404
- ** [extended result codes] for the [database connection] D
1405
- ** if the F parameter is true, or disable them if F is false.
1160
+ ** Requirements:
1161
+ ** [H12201] [H12202]
1406
1162
  */
1407
1163
  int sqlite3_extended_result_codes(sqlite3*, int onoff);
1408
1164
 
@@ -1439,27 +1195,15 @@ int sqlite3_extended_result_codes(sqlite3*, int onoff);
1439
1195
  ** For the purposes of this routine, an [INSERT] is considered to
1440
1196
  ** be successful even if it is subsequently rolled back.
1441
1197
  **
1442
- ** INVARIANTS:
1443
- **
1444
- ** {H12221} The [sqlite3_last_insert_rowid()] function shall return
1445
- ** the [rowid]
1446
- ** of the most recent successful [INSERT] performed on the same
1447
- ** [database connection] and within the same or higher level
1448
- ** trigger context, or zero if there have been no qualifying
1449
- ** [INSERT] statements.
1450
- **
1451
- ** {H12223} The [sqlite3_last_insert_rowid()] function shall return the
1452
- ** same value when called from the same trigger context
1453
- ** immediately before and after a [ROLLBACK].
1198
+ ** Requirements:
1199
+ ** [H12221] [H12223]
1454
1200
  **
1455
- ** ASSUMPTIONS:
1456
- **
1457
- ** {A12232} If a separate thread performs a new [INSERT] on the same
1458
- ** database connection while the [sqlite3_last_insert_rowid()]
1459
- ** function is running and thus changes the last insert [rowid],
1460
- ** then the value returned by [sqlite3_last_insert_rowid()] is
1461
- ** unpredictable and might not equal either the old or the new
1462
- ** last insert [rowid].
1201
+ ** If a separate thread performs a new [INSERT] on the same
1202
+ ** database connection while the [sqlite3_last_insert_rowid()]
1203
+ ** function is running and thus changes the last insert [rowid],
1204
+ ** then the value returned by [sqlite3_last_insert_rowid()] is
1205
+ ** unpredictable and might not equal either the old or the new
1206
+ ** last insert [rowid].
1463
1207
  */
1464
1208
  sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
1465
1209
 
@@ -1514,24 +1258,12 @@ sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
1514
1258
  ** [SQLITE_OMIT_TRUNCATE_OPTIMIZATION] compile-time option to disable the
1515
1259
  ** optimization on all queries.
1516
1260
  **
1517
- ** INVARIANTS:
1518
- **
1519
- ** {H12241} The [sqlite3_changes()] function shall return the number of
1520
- ** row changes caused by the most recent INSERT, UPDATE,
1521
- ** or DELETE statement on the same database connection and
1522
- ** within the same or higher trigger context, or zero if there have
1523
- ** not been any qualifying row changes.
1261
+ ** Requirements:
1262
+ ** [H12241] [H12243]
1524
1263
  **
1525
- ** {H12243} Statements of the form "DELETE FROM tablename" with no
1526
- ** WHERE clause shall cause subsequent calls to
1527
- ** [sqlite3_changes()] to return zero, regardless of the
1528
- ** number of rows originally in the table.
1529
- **
1530
- ** ASSUMPTIONS:
1531
- **
1532
- ** {A12252} If a separate thread makes changes on the same database connection
1533
- ** while [sqlite3_changes()] is running then the value returned
1534
- ** is unpredictable and not meaningful.
1264
+ ** If a separate thread makes changes on the same database connection
1265
+ ** while [sqlite3_changes()] is running then the value returned
1266
+ ** is unpredictable and not meaningful.
1535
1267
  */
1536
1268
  int sqlite3_changes(sqlite3*);
1537
1269
 
@@ -1560,22 +1292,12 @@ int sqlite3_changes(sqlite3*);
1560
1292
  **
1561
1293
  ** See also the [sqlite3_changes()] interface.
1562
1294
  **
1563
- ** INVARIANTS:
1564
- **
1565
- ** {H12261} The [sqlite3_total_changes()] returns the total number
1566
- ** of row changes caused by INSERT, UPDATE, and/or DELETE
1567
- ** statements on the same [database connection], in any
1568
- ** trigger context, since the database connection was created.
1569
- **
1570
- ** {H12263} Statements of the form "DELETE FROM tablename" with no
1571
- ** WHERE clause shall not change the value returned
1572
- ** by [sqlite3_total_changes()].
1573
- **
1574
- ** ASSUMPTIONS:
1295
+ ** Requirements:
1296
+ ** [H12261] [H12263]
1575
1297
  **
1576
- ** {A12264} If a separate thread makes changes on the same database connection
1577
- ** while [sqlite3_total_changes()] is running then the value
1578
- ** returned is unpredictable and not meaningful.
1298
+ ** If a separate thread makes changes on the same database connection
1299
+ ** while [sqlite3_total_changes()] is running then the value
1300
+ ** returned is unpredictable and not meaningful.
1579
1301
  */
1580
1302
  int sqlite3_total_changes(sqlite3*);
1581
1303
 
@@ -1605,19 +1327,11 @@ int sqlite3_total_changes(sqlite3*);
1605
1327
  ** A call to sqlite3_interrupt() has no effect on SQL statements
1606
1328
  ** that are started after sqlite3_interrupt() returns.
1607
1329
  **
1608
- ** INVARIANTS:
1330
+ ** Requirements:
1331
+ ** [H12271] [H12272]
1609
1332
  **
1610
- ** {H12271} The [sqlite3_interrupt()] interface will force all running
1611
- ** SQL statements associated with the same database connection
1612
- ** to halt after processing at most one additional row of data.
1613
- **
1614
- ** {H12272} Any SQL statement that is interrupted by [sqlite3_interrupt()]
1615
- ** will return [SQLITE_INTERRUPT].
1616
- **
1617
- ** ASSUMPTIONS:
1618
- **
1619
- ** {A12279} If the database connection closes while [sqlite3_interrupt()]
1620
- ** is running then bad things will likely happen.
1333
+ ** If the database connection closes while [sqlite3_interrupt()]
1334
+ ** is running then bad things will likely happen.
1621
1335
  */
1622
1336
  void sqlite3_interrupt(sqlite3*);
1623
1337
 
@@ -1638,25 +1352,13 @@ void sqlite3_interrupt(sqlite3*);
1638
1352
  ** These routines do not parse the SQL statements thus
1639
1353
  ** will not detect syntactically incorrect SQL.
1640
1354
  **
1641
- ** INVARIANTS:
1642
- **
1643
- ** {H10511} A successful evaluation of [sqlite3_complete()] or
1644
- ** [sqlite3_complete16()] functions shall
1645
- ** return a numeric 1 if and only if the last non-whitespace
1646
- ** token in their input is a semicolon that is not in between
1647
- ** the BEGIN and END of a CREATE TRIGGER statement.
1648
- **
1649
- ** {H10512} If a memory allocation error occurs during an invocation
1650
- ** of [sqlite3_complete()] or [sqlite3_complete16()] then the
1651
- ** routine shall return [SQLITE_NOMEM].
1355
+ ** Requirements: [H10511] [H10512]
1652
1356
  **
1653
- ** ASSUMPTIONS:
1357
+ ** The input to [sqlite3_complete()] must be a zero-terminated
1358
+ ** UTF-8 string.
1654
1359
  **
1655
- ** {A10512} The input to [sqlite3_complete()] must be a zero-terminated
1656
- ** UTF-8 string.
1657
- **
1658
- ** {A10513} The input to [sqlite3_complete16()] must be a zero-terminated
1659
- ** UTF-16 string in native byte order.
1360
+ ** The input to [sqlite3_complete16()] must be a zero-terminated
1361
+ ** UTF-16 string in native byte order.
1660
1362
  */
1661
1363
  int sqlite3_complete(const char *sql);
1662
1364
  int sqlite3_complete16(const void *sql);
@@ -1722,32 +1424,11 @@ int sqlite3_complete16(const void *sql);
1722
1424
  ** database connection that invoked the busy handler. Any such actions
1723
1425
  ** result in undefined behavior.
1724
1426
  **
1725
- ** INVARIANTS:
1726
- **
1727
- ** {H12311} The [sqlite3_busy_handler(D,C,A)] function shall replace
1728
- ** busy callback in the [database connection] D with a new
1729
- ** a new busy handler C and application data pointer A.
1730
- **
1731
- ** {H12312} Newly created [database connections] shall have a busy
1732
- ** handler of NULL.
1733
- **
1734
- ** {H12314} When two or more [database connections] share a
1735
- ** [sqlite3_enable_shared_cache | common cache],
1736
- ** the busy handler for the database connection currently using
1737
- ** the cache shall be invoked when the cache encounters a lock.
1738
- **
1739
- ** {H12316} If a busy handler callback returns zero, then the SQLite interface
1740
- ** that provoked the locking event shall return [SQLITE_BUSY].
1427
+ ** Requirements:
1428
+ ** [H12311] [H12312] [H12314] [H12316] [H12318]
1741
1429
  **
1742
- ** {H12318} SQLite shall invokes the busy handler with two arguments which
1743
- ** are a copy of the pointer supplied by the 3rd parameter to
1744
- ** [sqlite3_busy_handler()] and a count of the number of prior
1745
- ** invocations of the busy handler for the same locking event.
1746
- **
1747
- ** ASSUMPTIONS:
1748
- **
1749
- ** {A12319} A busy handler must not close the database connection
1750
- ** or [prepared statement] that invoked the busy handler.
1430
+ ** A busy handler must not close the database connection
1431
+ ** or [prepared statement] that invoked the busy handler.
1751
1432
  */
1752
1433
  int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
1753
1434
 
@@ -1769,21 +1450,8 @@ int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
1769
1450
  ** was defined (using [sqlite3_busy_handler()]) prior to calling
1770
1451
  ** this routine, that other busy handler is cleared.
1771
1452
  **
1772
- ** INVARIANTS:
1773
- **
1774
- ** {H12341} The [sqlite3_busy_timeout()] function shall override any prior
1775
- ** [sqlite3_busy_timeout()] or [sqlite3_busy_handler()] setting
1776
- ** on the same [database connection].
1777
- **
1778
- ** {H12343} If the 2nd parameter to [sqlite3_busy_timeout()] is less than
1779
- ** or equal to zero, then the busy handler shall be cleared so that
1780
- ** all subsequent locking events immediately return [SQLITE_BUSY].
1781
- **
1782
- ** {H12344} If the 2nd parameter to [sqlite3_busy_timeout()] is a positive
1783
- ** number N, then a busy handler shall be set that repeatedly calls
1784
- ** the xSleep() method in the [sqlite3_vfs | VFS interface] until
1785
- ** either the lock clears or until the cumulative sleep time
1786
- ** reported back by xSleep() exceeds N milliseconds.
1453
+ ** Requirements:
1454
+ ** [H12341] [H12343] [H12344]
1787
1455
  */
1788
1456
  int sqlite3_busy_timeout(sqlite3*, int ms);
1789
1457
 
@@ -1855,38 +1523,8 @@ int sqlite3_busy_timeout(sqlite3*, int ms);
1855
1523
  ** wrapper layer outside of the internal [sqlite3_exec()] call are not
1856
1524
  ** reflected in subsequent calls to [sqlite3_errcode()] or [sqlite3_errmsg()].
1857
1525
  **
1858
- ** INVARIANTS:
1859
- **
1860
- ** {H12371} If a [sqlite3_get_table()] fails a memory allocation, then
1861
- ** it shall free the result table under construction, abort the
1862
- ** query in process, skip any subsequent queries, set the
1863
- ** *pazResult output pointer to NULL and return [SQLITE_NOMEM].
1864
- **
1865
- ** {H12373} If the pnColumn parameter to [sqlite3_get_table()] is not NULL
1866
- ** then a successful invocation of [sqlite3_get_table()] shall
1867
- ** write the number of columns in the
1868
- ** result set of the query into *pnColumn.
1869
- **
1870
- ** {H12374} If the pnRow parameter to [sqlite3_get_table()] is not NULL
1871
- ** then a successful invocation of [sqlite3_get_table()] shall
1872
- ** writes the number of rows in the
1873
- ** result set of the query into *pnRow.
1874
- **
1875
- ** {H12376} A successful invocation of [sqlite3_get_table()] that computes
1876
- ** N rows of result with C columns per row shall make *pazResult
1877
- ** point to an array of pointers to (N+1)*C strings where the first
1878
- ** C strings are column names as obtained from
1879
- ** [sqlite3_column_name()] and the rest are column result values
1880
- ** obtained from [sqlite3_column_text()].
1881
- **
1882
- ** {H12379} The values in the pazResult array returned by [sqlite3_get_table()]
1883
- ** shall remain valid until cleared by [sqlite3_free_table()].
1884
- **
1885
- ** {H12382} When an error occurs during evaluation of [sqlite3_get_table()]
1886
- ** the function shall set *pazResult to NULL, write an error message
1887
- ** into memory obtained from [sqlite3_malloc()], make
1888
- ** **pzErrmsg point to that error message, and return a
1889
- ** appropriate [error code].
1526
+ ** Requirements:
1527
+ ** [H12371] [H12373] [H12374] [H12376] [H12379] [H12382]
1890
1528
  */
1891
1529
  int sqlite3_get_table(
1892
1530
  sqlite3 *db, /* An open database */
@@ -1990,22 +1628,8 @@ void sqlite3_free_table(char **result);
1990
1628
  ** addition that after the string has been read and copied into
1991
1629
  ** the result, [sqlite3_free()] is called on the input string. {END}
1992
1630
  **
1993
- ** INVARIANTS:
1994
- **
1995
- ** {H17403} The [sqlite3_mprintf()] and [sqlite3_vmprintf()] interfaces
1996
- ** return either pointers to zero-terminated UTF-8 strings held in
1997
- ** memory obtained from [sqlite3_malloc()] or NULL pointers if
1998
- ** a call to [sqlite3_malloc()] fails.
1999
- **
2000
- ** {H17406} The [sqlite3_snprintf()] interface writes a zero-terminated
2001
- ** UTF-8 string into the buffer pointed to by the second parameter
2002
- ** provided that the first parameter is greater than zero.
2003
- **
2004
- ** {H17407} The [sqlite3_snprintf()] interface does not write slots of
2005
- ** its output buffer (the second parameter) outside the range
2006
- ** of 0 through N-1 (where N is the first parameter)
2007
- ** regardless of the length of the string
2008
- ** requested by the format specification.
1631
+ ** Requirements:
1632
+ ** [H17403] [H17406] [H17407]
2009
1633
  */
2010
1634
  char *sqlite3_mprintf(const char*,...);
2011
1635
  char *sqlite3_vmprintf(const char*, va_list);
@@ -2079,57 +1703,18 @@ char *sqlite3_snprintf(int,char*,const char*, ...);
2079
1703
  ** they are reported back as [SQLITE_CANTOPEN] or
2080
1704
  ** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
2081
1705
  **
2082
- ** INVARIANTS:
2083
- **
2084
- ** {H17303} The [sqlite3_malloc(N)] interface returns either a pointer to
2085
- ** a newly checked-out block of at least N bytes of memory
2086
- ** that is 8-byte aligned, or it returns NULL if it is unable
2087
- ** to fulfill the request.
1706
+ ** Requirements:
1707
+ ** [H17303] [H17304] [H17305] [H17306] [H17310] [H17312] [H17315] [H17318]
1708
+ ** [H17321] [H17322] [H17323]
2088
1709
  **
2089
- ** {H17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if
2090
- ** N is less than or equal to zero.
1710
+ ** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
1711
+ ** must be either NULL or else pointers obtained from a prior
1712
+ ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
1713
+ ** not yet been released.
2091
1714
  **
2092
- ** {H17305} The [sqlite3_free(P)] interface releases memory previously
2093
- ** returned from [sqlite3_malloc()] or [sqlite3_realloc()],
2094
- ** making it available for reuse.
2095
- **
2096
- ** {H17306} A call to [sqlite3_free(NULL)] is a harmless no-op.
2097
- **
2098
- ** {H17310} A call to [sqlite3_realloc(0,N)] is equivalent to a call
2099
- ** to [sqlite3_malloc(N)].
2100
- **
2101
- ** {H17312} A call to [sqlite3_realloc(P,0)] is equivalent to a call
2102
- ** to [sqlite3_free(P)].
2103
- **
2104
- ** {H17315} The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()],
2105
- ** and [sqlite3_free()] for all of its memory allocation and
2106
- ** deallocation needs.
2107
- **
2108
- ** {H17318} The [sqlite3_realloc(P,N)] interface returns either a pointer
2109
- ** to a block of checked-out memory of at least N bytes in size
2110
- ** that is 8-byte aligned, or a NULL pointer.
2111
- **
2112
- ** {H17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
2113
- ** copies the first K bytes of content from P into the newly
2114
- ** allocated block, where K is the lesser of N and the size of
2115
- ** the buffer P.
2116
- **
2117
- ** {H17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first
2118
- ** releases the buffer P.
2119
- **
2120
- ** {H17323} When [sqlite3_realloc(P,N)] returns NULL, the buffer P is
2121
- ** not modified or released.
2122
- **
2123
- ** ASSUMPTIONS:
2124
- **
2125
- ** {A17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
2126
- ** must be either NULL or else pointers obtained from a prior
2127
- ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
2128
- ** not yet been released.
2129
- **
2130
- ** {A17351} The application must not read or write any part of
2131
- ** a block of memory after it has been released using
2132
- ** [sqlite3_free()] or [sqlite3_realloc()].
1715
+ ** The application must not read or write any part of
1716
+ ** a block of memory after it has been released using
1717
+ ** [sqlite3_free()] or [sqlite3_realloc()].
2133
1718
  */
2134
1719
  void *sqlite3_malloc(int);
2135
1720
  void *sqlite3_realloc(void*, int);
@@ -2142,26 +1727,8 @@ void sqlite3_free(void*);
2142
1727
  ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
2143
1728
  ** routines, which form the built-in memory allocation subsystem.
2144
1729
  **
2145
- ** INVARIANTS:
2146
- **
2147
- ** {H17371} The [sqlite3_memory_used()] routine returns the number of bytes
2148
- ** of memory currently outstanding (malloced but not freed).
2149
- **
2150
- ** {H17373} The [sqlite3_memory_highwater()] routine returns the maximum
2151
- ** value of [sqlite3_memory_used()] since the high-water mark
2152
- ** was last reset.
2153
- **
2154
- ** {H17374} The values returned by [sqlite3_memory_used()] and
2155
- ** [sqlite3_memory_highwater()] include any overhead
2156
- ** added by SQLite in its implementation of [sqlite3_malloc()],
2157
- ** but not overhead added by the any underlying system library
2158
- ** routines that [sqlite3_malloc()] may call.
2159
- **
2160
- ** {H17375} The memory high-water mark is reset to the current value of
2161
- ** [sqlite3_memory_used()] if and only if the parameter to
2162
- ** [sqlite3_memory_highwater()] is true. The value returned
2163
- ** by [sqlite3_memory_highwater(1)] is the high-water mark
2164
- ** prior to the reset.
1730
+ ** Requirements:
1731
+ ** [H17371] [H17373] [H17374] [H17375]
2165
1732
  */
2166
1733
  sqlite3_int64 sqlite3_memory_used(void);
2167
1734
  sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
@@ -2184,10 +1751,8 @@ sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
2184
1751
  ** internally and without recourse to the [sqlite3_vfs] xRandomness
2185
1752
  ** method.
2186
1753
  **
2187
- ** INVARIANTS:
2188
- **
2189
- ** {H17392} The [sqlite3_randomness(N,P)] interface writes N bytes of
2190
- ** high-quality pseudo-randomness into buffer P.
1754
+ ** Requirements:
1755
+ ** [H17392]
2191
1756
  */
2192
1757
  void sqlite3_randomness(int N, void *P);
2193
1758
 
@@ -2264,57 +1829,9 @@ void sqlite3_randomness(int N, void *P);
2264
1829
  ** [sqlite3_prepare()] or its variants. Authorization is not
2265
1830
  ** performed during statement evaluation in [sqlite3_step()].
2266
1831
  **
2267
- ** INVARIANTS:
2268
- **
2269
- ** {H12501} The [sqlite3_set_authorizer(D,...)] interface registers a
2270
- ** authorizer callback with database connection D.
2271
- **
2272
- ** {H12502} The authorizer callback is invoked as SQL statements are
2273
- ** being parseed and compiled.
2274
- **
2275
- ** {H12503} If the authorizer callback returns any value other than
2276
- ** [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY], then
2277
- ** the application interface call that caused
2278
- ** the authorizer callback to run shall fail with an
2279
- ** [SQLITE_ERROR] error code and an appropriate error message.
2280
- **
2281
- ** {H12504} When the authorizer callback returns [SQLITE_OK], the operation
2282
- ** described is processed normally.
2283
- **
2284
- ** {H12505} When the authorizer callback returns [SQLITE_DENY], the
2285
- ** application interface call that caused the
2286
- ** authorizer callback to run shall fail
2287
- ** with an [SQLITE_ERROR] error code and an error message
2288
- ** explaining that access is denied.
2289
- **
2290
- ** {H12506} If the authorizer code (the 2nd parameter to the authorizer
2291
- ** callback) is [SQLITE_READ] and the authorizer callback returns
2292
- ** [SQLITE_IGNORE], then the prepared statement is constructed to
2293
- ** insert a NULL value in place of the table column that would have
2294
- ** been read if [SQLITE_OK] had been returned.
2295
- **
2296
- ** {H12507} If the authorizer code (the 2nd parameter to the authorizer
2297
- ** callback) is anything other than [SQLITE_READ], then
2298
- ** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY].
2299
- **
2300
- ** {H12510} The first parameter to the authorizer callback is a copy of
2301
- ** the third parameter to the [sqlite3_set_authorizer()] interface.
2302
- **
2303
- ** {H12511} The second parameter to the callback is an integer
2304
- ** [SQLITE_COPY | action code] that specifies the particular action
2305
- ** to be authorized.
2306
- **
2307
- ** {H12512} The third through sixth parameters to the callback are
2308
- ** zero-terminated strings that contain
2309
- ** additional details about the action to be authorized.
2310
- **
2311
- ** {H12520} Each call to [sqlite3_set_authorizer()] overrides
2312
- ** any previously installed authorizer.
2313
- **
2314
- ** {H12521} A NULL authorizer means that no authorization
2315
- ** callback is invoked.
2316
- **
2317
- ** {H12522} The default authorizer is NULL.
1832
+ ** Requirements:
1833
+ ** [H12501] [H12502] [H12503] [H12504] [H12505] [H12506] [H12507] [H12510]
1834
+ ** [H12511] [H12512] [H12520] [H12521] [H12522]
2318
1835
  */
2319
1836
  int sqlite3_set_authorizer(
2320
1837
  sqlite3*,
@@ -2353,27 +1870,8 @@ int sqlite3_set_authorizer(
2353
1870
  ** the access attempt or NULL if this access attempt is directly from
2354
1871
  ** top-level SQL code.
2355
1872
  **
2356
- ** INVARIANTS:
2357
- **
2358
- ** {H12551} The second parameter to an
2359
- ** [sqlite3_set_authorizer | authorizer callback] shall be an integer
2360
- ** [SQLITE_COPY | authorizer code] that specifies what action
2361
- ** is being authorized.
2362
- **
2363
- ** {H12552} The 3rd and 4th parameters to the
2364
- ** [sqlite3_set_authorizer | authorization callback]
2365
- ** shall be parameters or NULL depending on which
2366
- ** [SQLITE_COPY | authorizer code] is used as the second parameter.
2367
- **
2368
- ** {H12553} The 5th parameter to the
2369
- ** [sqlite3_set_authorizer | authorizer callback] shall be the name
2370
- ** of the database (example: "main", "temp", etc.) if applicable.
2371
- **
2372
- ** {H12554} The 6th parameter to the
2373
- ** [sqlite3_set_authorizer | authorizer callback] shall be the name
2374
- ** of the inner-most trigger or view that is responsible for
2375
- ** the access attempt or NULL if this access attempt is directly from
2376
- ** top-level SQL code.
1873
+ ** Requirements:
1874
+ ** [H12551] [H12552] [H12553] [H12554]
2377
1875
  */
2378
1876
  /******************************************* 3rd ************ 4th ***********/
2379
1877
  #define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
@@ -2429,41 +1927,9 @@ int sqlite3_set_authorizer(
2429
1927
  ** the original statement text and an estimate of wall-clock time
2430
1928
  ** of how long that statement took to run.
2431
1929
  **
2432
- ** INVARIANTS:
2433
- **
2434
- ** {H12281} The callback function registered by [sqlite3_trace()]
2435
- ** shall be invoked
2436
- ** whenever an SQL statement first begins to execute and
2437
- ** whenever a trigger subprogram first begins to run.
2438
- **
2439
- ** {H12282} Each call to [sqlite3_trace()] shall override the previously
2440
- ** registered trace callback.
2441
- **
2442
- ** {H12283} A NULL trace callback shall disable tracing.
2443
- **
2444
- ** {H12284} The first argument to the trace callback shall be a copy of
2445
- ** the pointer which was the 3rd argument to [sqlite3_trace()].
2446
- **
2447
- ** {H12285} The second argument to the trace callback is a
2448
- ** zero-terminated UTF-8 string containing the original text
2449
- ** of the SQL statement as it was passed into [sqlite3_prepare_v2()]
2450
- ** or the equivalent, or an SQL comment indicating the beginning
2451
- ** of a trigger subprogram.
2452
- **
2453
- ** {H12287} The callback function registered by [sqlite3_profile()] is invoked
2454
- ** as each SQL statement finishes.
2455
- **
2456
- ** {H12288} The first parameter to the profile callback is a copy of
2457
- ** the 3rd parameter to [sqlite3_profile()].
2458
- **
2459
- ** {H12289} The second parameter to the profile callback is a
2460
- ** zero-terminated UTF-8 string that contains the complete text of
2461
- ** the SQL statement as it was processed by [sqlite3_prepare_v2()]
2462
- ** or the equivalent.
2463
- **
2464
- ** {H12290} The third parameter to the profile callback is an estimate
2465
- ** of the number of nanoseconds of wall-clock time required to
2466
- ** run the SQL statement from start to finish.
1930
+ ** Requirements:
1931
+ ** [H12281] [H12282] [H12283] [H12284] [H12285] [H12287] [H12288] [H12289]
1932
+ ** [H12290]
2467
1933
  */
2468
1934
  SQLITE_EXPERIMENTAL void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
2469
1935
  SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
@@ -2487,37 +1953,9 @@ SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
2487
1953
  ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
2488
1954
  ** database connections for the meaning of "modify" in this paragraph.
2489
1955
  **
2490
- ** INVARIANTS:
2491
- **
2492
- ** {H12911} The callback function registered by sqlite3_progress_handler()
2493
- ** is invoked periodically during long running calls to
2494
- ** [sqlite3_step()].
2495
- **
2496
- ** {H12912} The progress callback is invoked once for every N virtual
2497
- ** machine opcodes, where N is the second argument to
2498
- ** the [sqlite3_progress_handler()] call that registered
2499
- ** the callback. If N is less than 1, sqlite3_progress_handler()
2500
- ** acts as if a NULL progress handler had been specified.
2501
- **
2502
- ** {H12913} The progress callback itself is identified by the third
2503
- ** argument to sqlite3_progress_handler().
1956
+ ** Requirements:
1957
+ ** [H12911] [H12912] [H12913] [H12914] [H12915] [H12916] [H12917] [H12918]
2504
1958
  **
2505
- ** {H12914} The fourth argument to sqlite3_progress_handler() is a
2506
- ** void pointer passed to the progress callback
2507
- ** function each time it is invoked.
2508
- **
2509
- ** {H12915} If a call to [sqlite3_step()] results in fewer than N opcodes
2510
- ** being executed, then the progress callback is never invoked.
2511
- **
2512
- ** {H12916} Every call to [sqlite3_progress_handler()]
2513
- ** overwrites any previously registered progress handler.
2514
- **
2515
- ** {H12917} If the progress handler callback is NULL then no progress
2516
- ** handler is invoked.
2517
- **
2518
- ** {H12918} If the progress callback returns a result other than 0, then
2519
- ** the behavior is a if [sqlite3_interrupt()] had been called.
2520
- ** <S30500>
2521
1959
  */
2522
1960
  void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
2523
1961
 
@@ -2601,72 +2039,9 @@ void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
2601
2039
  ** characters must be converted to UTF-8 prior to passing them into
2602
2040
  ** sqlite3_open() or sqlite3_open_v2().
2603
2041
  **
2604
- ** INVARIANTS:
2605
- **
2606
- ** {H12701} The [sqlite3_open()], [sqlite3_open16()], and
2607
- ** [sqlite3_open_v2()] interfaces create a new
2608
- ** [database connection] associated with
2609
- ** the database file given in their first parameter.
2610
- **
2611
- ** {H12702} The filename argument is interpreted as UTF-8
2612
- ** for [sqlite3_open()] and [sqlite3_open_v2()] and as UTF-16
2613
- ** in the native byte order for [sqlite3_open16()].
2614
- **
2615
- ** {H12703} A successful invocation of [sqlite3_open()], [sqlite3_open16()],
2616
- ** or [sqlite3_open_v2()] writes a pointer to a new
2617
- ** [database connection] into *ppDb.
2618
- **
2619
- ** {H12704} The [sqlite3_open()], [sqlite3_open16()], and
2620
- ** [sqlite3_open_v2()] interfaces return [SQLITE_OK] upon success,
2621
- ** or an appropriate [error code] on failure.
2622
- **
2623
- ** {H12706} The default text encoding for a new database created using
2624
- ** [sqlite3_open()] or [sqlite3_open_v2()] will be UTF-8.
2625
- **
2626
- ** {H12707} The default text encoding for a new database created using
2627
- ** [sqlite3_open16()] will be UTF-16.
2628
- **
2629
- ** {H12709} The [sqlite3_open(F,D)] interface is equivalent to
2630
- ** [sqlite3_open_v2(F,D,G,0)] where the G parameter is
2631
- ** [SQLITE_OPEN_READWRITE]|[SQLITE_OPEN_CREATE].
2632
- **
2633
- ** {H12711} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
2634
- ** bit value [SQLITE_OPEN_READONLY] then the database is opened
2635
- ** for reading only.
2636
- **
2637
- ** {H12712} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
2638
- ** bit value [SQLITE_OPEN_READWRITE] then the database is opened
2639
- ** reading and writing if possible, or for reading only if the
2640
- ** file is write protected by the operating system.
2641
- **
2642
- ** {H12713} If the G parameter to [sqlite3_open_v2(F,D,G,V)] omits the
2643
- ** bit value [SQLITE_OPEN_CREATE] and the database does not
2644
- ** previously exist, an error is returned.
2645
- **
2646
- ** {H12714} If the G parameter to [sqlite3_open_v2(F,D,G,V)] contains the
2647
- ** bit value [SQLITE_OPEN_CREATE] and the database does not
2648
- ** previously exist, then an attempt is made to create and
2649
- ** initialize the database.
2650
- **
2651
- ** {H12717} If the filename argument to [sqlite3_open()], [sqlite3_open16()],
2652
- ** or [sqlite3_open_v2()] is ":memory:", then an private,
2653
- ** ephemeral, in-memory database is created for the connection.
2654
- ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
2655
- ** in sqlite3_open_v2()?</todo>
2656
- **
2657
- ** {H12719} If the filename is NULL or an empty string, then a private,
2658
- ** ephemeral on-disk database will be created.
2659
- ** <todo>Is SQLITE_OPEN_CREATE|SQLITE_OPEN_READWRITE required
2660
- ** in sqlite3_open_v2()?</todo>
2661
- **
2662
- ** {H12721} The [database connection] created by [sqlite3_open_v2(F,D,G,V)]
2663
- ** will use the [sqlite3_vfs] object identified by the V parameter,
2664
- ** or the default [sqlite3_vfs] object if V is a NULL pointer.
2665
- **
2666
- ** {H12723} Two [database connections] will share a common cache if both were
2667
- ** opened with the same VFS while [shared cache mode] was enabled and
2668
- ** if both filenames compare equal using memcmp() after having been
2669
- ** processed by the [sqlite3_vfs | xFullPathname] method of the VFS.
2042
+ ** Requirements:
2043
+ ** [H12701] [H12702] [H12703] [H12704] [H12706] [H12707] [H12709] [H12711]
2044
+ ** [H12712] [H12713] [H12714] [H12717] [H12719] [H12721] [H12723]
2670
2045
  */
2671
2046
  int sqlite3_open(
2672
2047
  const char *filename, /* Database filename (UTF-8) */
@@ -2716,36 +2091,8 @@ int sqlite3_open_v2(
2716
2091
  ** was invoked incorrectly by the application. In that case, the
2717
2092
  ** error code and message may or may not be set.
2718
2093
  **
2719
- ** INVARIANTS:
2720
- **
2721
- ** {H12801} The [sqlite3_errcode(D)] interface returns the numeric
2722
- ** [result code] or [extended result code] for the most recently
2723
- ** failed interface call associated with the [database connection] D.
2724
- **
2725
- ** {H12802} The [sqlite3_extended_errcode(D)] interface returns the numeric
2726
- ** [extended result code] for the most recently
2727
- ** failed interface call associated with the [database connection] D.
2728
- **
2729
- ** {H12803} The [sqlite3_errmsg(D)] and [sqlite3_errmsg16(D)]
2730
- ** interfaces return English-language text that describes
2731
- ** the error in the mostly recently failed interface call,
2732
- ** encoded as either UTF-8 or UTF-16 respectively.
2733
- **
2734
- ** {H12807} The strings returned by [sqlite3_errmsg()] and [sqlite3_errmsg16()]
2735
- ** are valid until the next SQLite interface call.
2736
- **
2737
- ** {H12808} Calls to API routines that do not return an error code
2738
- ** (example: [sqlite3_data_count()]) do not
2739
- ** change the error code or message returned by
2740
- ** [sqlite3_errcode()], [sqlite3_extended_errcode()],
2741
- ** [sqlite3_errmsg()], or [sqlite3_errmsg16()].
2742
- **
2743
- ** {H12809} Interfaces that are not associated with a specific
2744
- ** [database connection] (examples:
2745
- ** [sqlite3_mprintf()] or [sqlite3_enable_shared_cache()]
2746
- ** do not change the values returned by
2747
- ** [sqlite3_errcode()], [sqlite3_extended_errcode()],
2748
- ** [sqlite3_errmsg()], or [sqlite3_errmsg16()].
2094
+ ** Requirements:
2095
+ ** [H12801] [H12802] [H12803] [H12807] [H12808] [H12809]
2749
2096
  */
2750
2097
  int sqlite3_errcode(sqlite3 *db);
2751
2098
  int sqlite3_extended_errcode(sqlite3 *db);
@@ -2789,8 +2136,10 @@ typedef struct sqlite3_stmt sqlite3_stmt;
2789
2136
  ** new limit for that construct. The function returns the old limit.
2790
2137
  **
2791
2138
  ** If the new limit is a negative number, the limit is unchanged.
2792
- ** For the limit category of SQLITE_LIMIT_XYZ there is a hard upper
2793
- ** bound set by a compile-time C preprocessor macro named SQLITE_MAX_XYZ.
2139
+ ** For the limit category of SQLITE_LIMIT_XYZ there is a
2140
+ ** [limits | hard upper bound]
2141
+ ** set by a compile-time C preprocessor macro named
2142
+ ** [limits | SQLITE_MAX_XYZ].
2794
2143
  ** (The "_LIMIT_" in the name is changed to "_MAX_".)
2795
2144
  ** Attempts to increase a limit above its hard upper bound are
2796
2145
  ** silently truncated to the hard upper limit.
@@ -2798,7 +2147,7 @@ typedef struct sqlite3_stmt sqlite3_stmt;
2798
2147
  ** Run time limits are intended for use in applications that manage
2799
2148
  ** both their own internal database and also databases that are controlled
2800
2149
  ** by untrusted external sources. An example application might be a
2801
- ** webbrowser that has its own databases for storing history and
2150
+ ** web browser that has its own databases for storing history and
2802
2151
  ** separate databases controlled by JavaScript applications downloaded
2803
2152
  ** off the Internet. The internal databases can be given the
2804
2153
  ** large, default limits. Databases managed by external sources can
@@ -2810,19 +2159,8 @@ typedef struct sqlite3_stmt sqlite3_stmt;
2810
2159
  **
2811
2160
  ** New run-time limit categories may be added in future releases.
2812
2161
  **
2813
- ** INVARIANTS:
2814
- **
2815
- ** {H12762} A successful call to [sqlite3_limit(D,C,V)] where V is
2816
- ** positive changes the limit on the size of construct C in the
2817
- ** [database connection] D to the lesser of V and the hard upper
2818
- ** bound on the size of C that is set at compile-time.
2819
- **
2820
- ** {H12766} A successful call to [sqlite3_limit(D,C,V)] where V is negative
2821
- ** leaves the state of the [database connection] D unchanged.
2822
- **
2823
- ** {H12769} A successful call to [sqlite3_limit(D,C,V)] returns the
2824
- ** value of the limit on the size of construct C in the
2825
- ** [database connection] D as it was prior to the call.
2162
+ ** Requirements:
2163
+ ** [H12762] [H12766] [H12769]
2826
2164
  */
2827
2165
  int sqlite3_limit(sqlite3*, int id, int newVal);
2828
2166
 
@@ -2830,9 +2168,10 @@ int sqlite3_limit(sqlite3*, int id, int newVal);
2830
2168
  ** CAPI3REF: Run-Time Limit Categories {H12790} <H12760>
2831
2169
  ** KEYWORDS: {limit category} {limit categories}
2832
2170
  **
2833
- ** These constants define various aspects of a [database connection]
2834
- ** that can be limited in size by calls to [sqlite3_limit()].
2835
- ** The meanings of the various limits are as follows:
2171
+ ** These constants define various performance limits
2172
+ ** that can be lowered at run-time using [sqlite3_limit()].
2173
+ ** The synopsis of the meanings of the various limits is shown below.
2174
+ ** Additional information is available at [limits | Limits in SQLite].
2836
2175
  **
2837
2176
  ** <dl>
2838
2177
  ** <dt>SQLITE_LIMIT_LENGTH</dt>
@@ -2843,7 +2182,7 @@ int sqlite3_limit(sqlite3*, int id, int newVal);
2843
2182
  **
2844
2183
  ** <dt>SQLITE_LIMIT_COLUMN</dt>
2845
2184
  ** <dd>The maximum number of columns in a table definition or in the
2846
- ** result set of a SELECT or the maximum number of columns in an index
2185
+ ** result set of a [SELECT] or the maximum number of columns in an index
2847
2186
  ** or in an ORDER BY or GROUP BY clause.</dd>
2848
2187
  **
2849
2188
  ** <dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
@@ -2860,11 +2199,11 @@ int sqlite3_limit(sqlite3*, int id, int newVal);
2860
2199
  ** <dd>The maximum number of arguments on a function.</dd>
2861
2200
  **
2862
2201
  ** <dt>SQLITE_LIMIT_ATTACHED</dt>
2863
- ** <dd>The maximum number of attached databases.</dd>
2202
+ ** <dd>The maximum number of [ATTACH | attached databases].</dd>
2864
2203
  **
2865
2204
  ** <dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
2866
- ** <dd>The maximum length of the pattern argument to the LIKE or
2867
- ** GLOB operators.</dd>
2205
+ ** <dd>The maximum length of the pattern argument to the [LIKE] or
2206
+ ** [GLOB] operators.</dd>
2868
2207
  **
2869
2208
  ** <dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
2870
2209
  ** <dd>The maximum number of variables in an SQL statement that can
@@ -2951,41 +2290,9 @@ int sqlite3_limit(sqlite3*, int id, int newVal);
2951
2290
  ** </li>
2952
2291
  ** </ol>
2953
2292
  **
2954
- ** INVARIANTS:
2955
- **
2956
- ** {H13011} The [sqlite3_prepare(db,zSql,...)] and
2957
- ** [sqlite3_prepare_v2(db,zSql,...)] interfaces interpret the
2958
- ** text in their zSql parameter as UTF-8.
2959
- **
2960
- ** {H13012} The [sqlite3_prepare16(db,zSql,...)] and
2961
- ** [sqlite3_prepare16_v2(db,zSql,...)] interfaces interpret the
2962
- ** text in their zSql parameter as UTF-16 in the native byte order.
2963
- **
2964
- ** {H13013} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
2965
- ** and its variants is less than zero, the SQL text is
2966
- ** read from zSql is read up to the first zero terminator.
2967
- **
2968
- ** {H13014} If the nByte argument to [sqlite3_prepare_v2(db,zSql,nByte,...)]
2969
- ** and its variants is non-negative, then at most nBytes bytes of
2970
- ** SQL text is read from zSql.
2971
- **
2972
- ** {H13015} In [sqlite3_prepare_v2(db,zSql,N,P,pzTail)] and its variants
2973
- ** if the zSql input text contains more than one SQL statement
2974
- ** and pzTail is not NULL, then *pzTail is made to point to the
2975
- ** first byte past the end of the first SQL statement in zSql.
2976
- ** <todo>What does *pzTail point to if there is one statement?</todo>
2977
- **
2978
- ** {H13016} A successful call to [sqlite3_prepare_v2(db,zSql,N,ppStmt,...)]
2979
- ** or one of its variants writes into *ppStmt a pointer to a new
2980
- ** [prepared statement] or a pointer to NULL if zSql contains
2981
- ** nothing other than whitespace or comments.
2982
- **
2983
- ** {H13019} The [sqlite3_prepare_v2()] interface and its variants return
2984
- ** [SQLITE_OK] or an appropriate [error code] upon failure.
2293
+ ** Requirements:
2294
+ ** [H13011] [H13012] [H13013] [H13014] [H13015] [H13016] [H13019] [H13021]
2985
2295
  **
2986
- ** {H13021} Before [sqlite3_prepare(db,zSql,nByte,ppStmt,pzTail)] or its
2987
- ** variants returns an error (any value other than [SQLITE_OK]),
2988
- ** they first set *ppStmt to NULL.
2989
2296
  */
2990
2297
  int sqlite3_prepare(
2991
2298
  sqlite3 *db, /* Database handle */
@@ -3023,20 +2330,8 @@ int sqlite3_prepare16_v2(
3023
2330
  ** SQL text used to create a [prepared statement] if that statement was
3024
2331
  ** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
3025
2332
  **
3026
- ** INVARIANTS:
3027
- **
3028
- ** {H13101} If the [prepared statement] passed as the argument to
3029
- ** [sqlite3_sql()] was compiled using either [sqlite3_prepare_v2()] or
3030
- ** [sqlite3_prepare16_v2()], then [sqlite3_sql()] returns
3031
- ** a pointer to a zero-terminated string containing a UTF-8 rendering
3032
- ** of the original SQL statement.
3033
- **
3034
- ** {H13102} If the [prepared statement] passed as the argument to
3035
- ** [sqlite3_sql()] was compiled using either [sqlite3_prepare()] or
3036
- ** [sqlite3_prepare16()], then [sqlite3_sql()] returns a NULL pointer.
3037
- **
3038
- ** {H13103} The string returned by [sqlite3_sql(S)] is valid until the
3039
- ** [prepared statement] S is deleted using [sqlite3_finalize(S)].
2333
+ ** Requirements:
2334
+ ** [H13101] [H13102] [H13103]
3040
2335
  */
3041
2336
  const char *sqlite3_sql(sqlite3_stmt *pStmt);
3042
2337
 
@@ -3099,7 +2394,7 @@ typedef struct sqlite3_context sqlite3_context;
3099
2394
  ** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
3100
2395
  **
3101
2396
  ** In the SQL strings input to [sqlite3_prepare_v2()] and its variants,
3102
- ** literals may be replaced by a parameter in one of these forms:
2397
+ ** literals may be replaced by a [parameter] in one of these forms:
3103
2398
  **
3104
2399
  ** <ul>
3105
2400
  ** <li> ?
@@ -3172,79 +2467,10 @@ typedef struct sqlite3_context sqlite3_context;
3172
2467
  ** See also: [sqlite3_bind_parameter_count()],
3173
2468
  ** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
3174
2469
  **
3175
- ** INVARIANTS:
3176
- **
3177
- ** {H13506} The [SQL statement compiler] recognizes tokens of the forms
3178
- ** "?", "?NNN", "$VVV", ":VVV", and "@VVV" as SQL parameters,
3179
- ** where NNN is any sequence of one or more digits
3180
- ** and where VVV is any sequence of one or more alphanumeric
3181
- ** characters or "::" optionally followed by a string containing
3182
- ** no spaces and contained within parentheses.
3183
- **
3184
- ** {H13509} The initial value of an SQL parameter is NULL.
3185
- **
3186
- ** {H13512} The index of an "?" SQL parameter is one larger than the
3187
- ** largest index of SQL parameter to the left, or 1 if
3188
- ** the "?" is the leftmost SQL parameter.
3189
- **
3190
- ** {H13515} The index of an "?NNN" SQL parameter is the integer NNN.
3191
- **
3192
- ** {H13518} The index of an ":VVV", "$VVV", or "@VVV" SQL parameter is
3193
- ** the same as the index of leftmost occurrences of the same
3194
- ** parameter, or one more than the largest index over all
3195
- ** parameters to the left if this is the first occurrence
3196
- ** of this parameter, or 1 if this is the leftmost parameter.
3197
- **
3198
- ** {H13521} The [SQL statement compiler] fails with an [SQLITE_RANGE]
3199
- ** error if the index of an SQL parameter is less than 1
3200
- ** or greater than the compile-time SQLITE_MAX_VARIABLE_NUMBER
3201
- ** parameter.
3202
- **
3203
- ** {H13524} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,V,...)]
3204
- ** associate the value V with all SQL parameters having an
3205
- ** index of N in the [prepared statement] S.
3206
- **
3207
- ** {H13527} Calls to [sqlite3_bind_text | sqlite3_bind(S,N,...)]
3208
- ** override prior calls with the same values of S and N.
2470
+ ** Requirements:
2471
+ ** [H13506] [H13509] [H13512] [H13515] [H13518] [H13521] [H13524] [H13527]
2472
+ ** [H13530] [H13533] [H13536] [H13539] [H13542] [H13545] [H13548] [H13551]
3209
2473
  **
3210
- ** {H13530} Bindings established by [sqlite3_bind_text | sqlite3_bind(S,...)]
3211
- ** persist across calls to [sqlite3_reset(S)].
3212
- **
3213
- ** {H13533} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
3214
- ** [sqlite3_bind_text(S,N,V,L,D)], or
3215
- ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds the first L
3216
- ** bytes of the BLOB or string pointed to by V, when L
3217
- ** is non-negative.
3218
- **
3219
- ** {H13536} In calls to [sqlite3_bind_text(S,N,V,L,D)] or
3220
- ** [sqlite3_bind_text16(S,N,V,L,D)] SQLite binds characters
3221
- ** from V through the first zero character when L is negative.
3222
- **
3223
- ** {H13539} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
3224
- ** [sqlite3_bind_text(S,N,V,L,D)], or
3225
- ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
3226
- ** constant [SQLITE_STATIC], SQLite assumes that the value V
3227
- ** is held in static unmanaged space that will not change
3228
- ** during the lifetime of the binding.
3229
- **
3230
- ** {H13542} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
3231
- ** [sqlite3_bind_text(S,N,V,L,D)], or
3232
- ** [sqlite3_bind_text16(S,N,V,L,D)] when D is the special
3233
- ** constant [SQLITE_TRANSIENT], the routine makes a
3234
- ** private copy of the value V before it returns.
3235
- **
3236
- ** {H13545} In calls to [sqlite3_bind_blob(S,N,V,L,D)],
3237
- ** [sqlite3_bind_text(S,N,V,L,D)], or
3238
- ** [sqlite3_bind_text16(S,N,V,L,D)] when D is a pointer to
3239
- ** a function, SQLite invokes that function to destroy the
3240
- ** value V after it has finished using the value V.
3241
- **
3242
- ** {H13548} In calls to [sqlite3_bind_zeroblob(S,N,V,L)] the value bound
3243
- ** is a BLOB of L bytes, or a zero-length BLOB if L is negative.
3244
- **
3245
- ** {H13551} In calls to [sqlite3_bind_value(S,N,V)] the V argument may
3246
- ** be either a [protected sqlite3_value] object or an
3247
- ** [unprotected sqlite3_value] object.
3248
2474
  */
3249
2475
  int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
3250
2476
  int sqlite3_bind_double(sqlite3_stmt*, int, double);
@@ -3274,11 +2500,8 @@ int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
3274
2500
  ** [sqlite3_bind_parameter_name()], and
3275
2501
  ** [sqlite3_bind_parameter_index()].
3276
2502
  **
3277
- ** INVARIANTS:
3278
- **
3279
- ** {H13601} The [sqlite3_bind_parameter_count(S)] interface returns
3280
- ** the largest index of all SQL parameters in the
3281
- ** [prepared statement] S, or 0 if S contains no SQL parameters.
2503
+ ** Requirements:
2504
+ ** [H13601]
3282
2505
  */
3283
2506
  int sqlite3_bind_parameter_count(sqlite3_stmt*);
3284
2507
 
@@ -3307,13 +2530,8 @@ int sqlite3_bind_parameter_count(sqlite3_stmt*);
3307
2530
  ** [sqlite3_bind_parameter_count()], and
3308
2531
  ** [sqlite3_bind_parameter_index()].
3309
2532
  **
3310
- ** INVARIANTS:
3311
- **
3312
- ** {H13621} The [sqlite3_bind_parameter_name(S,N)] interface returns
3313
- ** a UTF-8 rendering of the name of the SQL parameter in
3314
- ** the [prepared statement] S having index N, or
3315
- ** NULL if there is no SQL parameter with index N or if the
3316
- ** parameter with index N is an anonymous parameter "?".
2533
+ ** Requirements:
2534
+ ** [H13621]
3317
2535
  */
3318
2536
  const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
3319
2537
 
@@ -3331,12 +2549,8 @@ const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
3331
2549
  ** [sqlite3_bind_parameter_count()], and
3332
2550
  ** [sqlite3_bind_parameter_index()].
3333
2551
  **
3334
- ** INVARIANTS:
3335
- **
3336
- ** {H13641} The [sqlite3_bind_parameter_index(S,N)] interface returns
3337
- ** the index of SQL parameter in the [prepared statement]
3338
- ** S whose name matches the UTF-8 string N, or 0 if there is
3339
- ** no match.
2552
+ ** Requirements:
2553
+ ** [H13641]
3340
2554
  */
3341
2555
  int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
3342
2556
 
@@ -3347,10 +2561,8 @@ int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
3347
2561
  ** the [sqlite3_bind_blob | bindings] on a [prepared statement].
3348
2562
  ** Use this routine to reset all host parameters to NULL.
3349
2563
  **
3350
- ** INVARIANTS:
3351
- **
3352
- ** {H13661} The [sqlite3_clear_bindings(S)] interface resets all SQL
3353
- ** parameter bindings in the [prepared statement] S back to NULL.
2564
+ ** Requirements:
2565
+ ** [H13661]
3354
2566
  */
3355
2567
  int sqlite3_clear_bindings(sqlite3_stmt*);
3356
2568
 
@@ -3361,11 +2573,8 @@ int sqlite3_clear_bindings(sqlite3_stmt*);
3361
2573
  ** [prepared statement]. This routine returns 0 if pStmt is an SQL
3362
2574
  ** statement that does not return data (for example an [UPDATE]).
3363
2575
  **
3364
- ** INVARIANTS:
3365
- **
3366
- ** {H13711} The [sqlite3_column_count(S)] interface returns the number of
3367
- ** columns in the result set generated by the [prepared statement] S,
3368
- ** or 0 if S does not generate a result set.
2576
+ ** Requirements:
2577
+ ** [H13711]
3369
2578
  */
3370
2579
  int sqlite3_column_count(sqlite3_stmt *pStmt);
3371
2580
 
@@ -3393,35 +2602,8 @@ int sqlite3_column_count(sqlite3_stmt *pStmt);
3393
2602
  ** then the name of the column is unspecified and may change from
3394
2603
  ** one release of SQLite to the next.
3395
2604
  **
3396
- ** INVARIANTS:
3397
- **
3398
- ** {H13721} A successful invocation of the [sqlite3_column_name(S,N)]
3399
- ** interface returns the name of the Nth column (where 0 is
3400
- ** the leftmost column) for the result set of the
3401
- ** [prepared statement] S as a zero-terminated UTF-8 string.
3402
- **
3403
- ** {H13723} A successful invocation of the [sqlite3_column_name16(S,N)]
3404
- ** interface returns the name of the Nth column (where 0 is
3405
- ** the leftmost column) for the result set of the
3406
- ** [prepared statement] S as a zero-terminated UTF-16 string
3407
- ** in the native byte order.
3408
- **
3409
- ** {H13724} The [sqlite3_column_name()] and [sqlite3_column_name16()]
3410
- ** interfaces return a NULL pointer if they are unable to
3411
- ** allocate memory to hold their normal return strings.
3412
- **
3413
- ** {H13725} If the N parameter to [sqlite3_column_name(S,N)] or
3414
- ** [sqlite3_column_name16(S,N)] is out of range, then the
3415
- ** interfaces return a NULL pointer.
3416
- **
3417
- ** {H13726} The strings returned by [sqlite3_column_name(S,N)] and
3418
- ** [sqlite3_column_name16(S,N)] are valid until the next
3419
- ** call to either routine with the same S and N parameters
3420
- ** or until [sqlite3_finalize(S)] is called.
3421
- **
3422
- ** {H13727} When a result column of a [SELECT] statement contains
3423
- ** an AS clause, the name of that column is the identifier
3424
- ** to the right of the AS keyword.
2605
+ ** Requirements:
2606
+ ** [H13721] [H13723] [H13724] [H13725] [H13726] [H13727]
3425
2607
  */
3426
2608
  const char *sqlite3_column_name(sqlite3_stmt*, int N);
3427
2609
  const void *sqlite3_column_name16(sqlite3_stmt*, int N);
@@ -3463,57 +2645,13 @@ const void *sqlite3_column_name16(sqlite3_stmt*, int N);
3463
2645
  ** prepared statement and column at the same time then the results are
3464
2646
  ** undefined.
3465
2647
  **
3466
- ** INVARIANTS:
3467
- **
3468
- ** {H13741} The [sqlite3_column_database_name(S,N)] interface returns either
3469
- ** the UTF-8 zero-terminated name of the database from which the
3470
- ** Nth result column of the [prepared statement] S is extracted,
3471
- ** or NULL if the Nth column of S is a general expression
3472
- ** or if unable to allocate memory to store the name.
3473
- **
3474
- ** {H13742} The [sqlite3_column_database_name16(S,N)] interface returns either
3475
- ** the UTF-16 native byte order zero-terminated name of the database
3476
- ** from which the Nth result column of the [prepared statement] S is
3477
- ** extracted, or NULL if the Nth column of S is a general expression
3478
- ** or if unable to allocate memory to store the name.
3479
- **
3480
- ** {H13743} The [sqlite3_column_table_name(S,N)] interface returns either
3481
- ** the UTF-8 zero-terminated name of the table from which the
3482
- ** Nth result column of the [prepared statement] S is extracted,
3483
- ** or NULL if the Nth column of S is a general expression
3484
- ** or if unable to allocate memory to store the name.
3485
- **
3486
- ** {H13744} The [sqlite3_column_table_name16(S,N)] interface returns either
3487
- ** the UTF-16 native byte order zero-terminated name of the table
3488
- ** from which the Nth result column of the [prepared statement] S is
3489
- ** extracted, or NULL if the Nth column of S is a general expression
3490
- ** or if unable to allocate memory to store the name.
3491
- **
3492
- ** {H13745} The [sqlite3_column_origin_name(S,N)] interface returns either
3493
- ** the UTF-8 zero-terminated name of the table column from which the
3494
- ** Nth result column of the [prepared statement] S is extracted,
3495
- ** or NULL if the Nth column of S is a general expression
3496
- ** or if unable to allocate memory to store the name.
3497
- **
3498
- ** {H13746} The [sqlite3_column_origin_name16(S,N)] interface returns either
3499
- ** the UTF-16 native byte order zero-terminated name of the table
3500
- ** column from which the Nth result column of the
3501
- ** [prepared statement] S is extracted, or NULL if the Nth column
3502
- ** of S is a general expression or if unable to allocate memory
3503
- ** to store the name.
3504
- **
3505
- ** {H13748} The return values from
3506
- ** [sqlite3_column_database_name | column metadata interfaces]
3507
- ** are valid for the lifetime of the [prepared statement]
3508
- ** or until the encoding is changed by another metadata
3509
- ** interface call for the same prepared statement and column.
3510
- **
3511
- ** ASSUMPTIONS:
3512
- **
3513
- ** {A13751} If two or more threads call one or more
3514
- ** [sqlite3_column_database_name | column metadata interfaces]
3515
- ** for the same [prepared statement] and result column
3516
- ** at the same time then the results are undefined.
2648
+ ** Requirements:
2649
+ ** [H13741] [H13742] [H13743] [H13744] [H13745] [H13746] [H13748]
2650
+ **
2651
+ ** If two or more threads call one or more
2652
+ ** [sqlite3_column_database_name | column metadata interfaces]
2653
+ ** for the same [prepared statement] and result column
2654
+ ** at the same time then the results are undefined.
3517
2655
  */
3518
2656
  const char *sqlite3_column_database_name(sqlite3_stmt*,int);
3519
2657
  const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
@@ -3551,26 +2689,8 @@ const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
3551
2689
  ** is associated with individual values, not with the containers
3552
2690
  ** used to hold those values.
3553
2691
  **
3554
- ** INVARIANTS:
3555
- **
3556
- ** {H13761} A successful call to [sqlite3_column_decltype(S,N)] returns a
3557
- ** zero-terminated UTF-8 string containing the declared datatype
3558
- ** of the table column that appears as the Nth column (numbered
3559
- ** from 0) of the result set to the [prepared statement] S.
3560
- **
3561
- ** {H13762} A successful call to [sqlite3_column_decltype16(S,N)]
3562
- ** returns a zero-terminated UTF-16 native byte order string
3563
- ** containing the declared datatype of the table column that appears
3564
- ** as the Nth column (numbered from 0) of the result set to the
3565
- ** [prepared statement] S.
3566
- **
3567
- ** {H13763} If N is less than 0 or N is greater than or equal to
3568
- ** the number of columns in the [prepared statement] S,
3569
- ** or if the Nth column of S is an expression or subquery rather
3570
- ** than a table column, or if a memory allocation failure
3571
- ** occurs during encoding conversions, then
3572
- ** calls to [sqlite3_column_decltype(S,N)] or
3573
- ** [sqlite3_column_decltype16(S,N)] return NULL.
2692
+ ** Requirements:
2693
+ ** [H13761] [H13762] [H13763]
3574
2694
  */
3575
2695
  const char *sqlite3_column_decltype(sqlite3_stmt*,int);
3576
2696
  const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
@@ -3640,31 +2760,8 @@ const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
3640
2760
  ** then the more specific [error codes] are returned directly
3641
2761
  ** by sqlite3_step(). The use of the "v2" interface is recommended.
3642
2762
  **
3643
- ** INVARIANTS:
3644
- **
3645
- ** {H13202} If the [prepared statement] S is ready to be run, then
3646
- ** [sqlite3_step(S)] advances that prepared statement until
3647
- ** completion or until it is ready to return another row of the
3648
- ** result set, or until an [sqlite3_interrupt | interrupt]
3649
- ** or a run-time error occurs.
3650
- **
3651
- ** {H15304} When a call to [sqlite3_step(S)] causes the [prepared statement]
3652
- ** S to run to completion, the function returns [SQLITE_DONE].
3653
- **
3654
- ** {H15306} When a call to [sqlite3_step(S)] stops because it is ready to
3655
- ** return another row of the result set, it returns [SQLITE_ROW].
3656
- **
3657
- ** {H15308} If a call to [sqlite3_step(S)] encounters an
3658
- ** [sqlite3_interrupt | interrupt] or a run-time error,
3659
- ** it returns an appropriate error code that is not one of
3660
- ** [SQLITE_OK], [SQLITE_ROW], or [SQLITE_DONE].
3661
- **
3662
- ** {H15310} If an [sqlite3_interrupt | interrupt] or a run-time error
3663
- ** occurs during a call to [sqlite3_step(S)]
3664
- ** for a [prepared statement] S created using
3665
- ** legacy interfaces [sqlite3_prepare()] or
3666
- ** [sqlite3_prepare16()], then the function returns either
3667
- ** [SQLITE_ERROR], [SQLITE_BUSY], or [SQLITE_MISUSE].
2763
+ ** Requirements:
2764
+ ** [H13202] [H15304] [H15306] [H15308] [H15310]
3668
2765
  */
3669
2766
  int sqlite3_step(sqlite3_stmt*);
3670
2767
 
@@ -3673,17 +2770,8 @@ int sqlite3_step(sqlite3_stmt*);
3673
2770
  **
3674
2771
  ** Returns the number of values in the current row of the result set.
3675
2772
  **
3676
- ** INVARIANTS:
3677
- **
3678
- ** {H13771} After a call to [sqlite3_step(S)] that returns [SQLITE_ROW],
3679
- ** the [sqlite3_data_count(S)] routine will return the same value
3680
- ** as the [sqlite3_column_count(S)] function.
3681
- **
3682
- ** {H13772} After [sqlite3_step(S)] has returned any value other than
3683
- ** [SQLITE_ROW] or before [sqlite3_step(S)] has been called on the
3684
- ** [prepared statement] for the first time since it was
3685
- ** [sqlite3_prepare | prepared] or [sqlite3_reset | reset],
3686
- ** the [sqlite3_data_count(S)] routine returns zero.
2773
+ ** Requirements:
2774
+ ** [H13771] [H13772]
3687
2775
  */
3688
2776
  int sqlite3_data_count(sqlite3_stmt *pStmt);
3689
2777
 
@@ -3871,60 +2959,9 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
3871
2959
  ** pointer. Subsequent calls to [sqlite3_errcode()] will return
3872
2960
  ** [SQLITE_NOMEM].
3873
2961
  **
3874
- ** INVARIANTS:
3875
- **
3876
- ** {H13803} The [sqlite3_column_blob(S,N)] interface converts the
3877
- ** Nth column in the current row of the result set for
3878
- ** the [prepared statement] S into a BLOB and then returns a
3879
- ** pointer to the converted value.
3880
- **
3881
- ** {H13806} The [sqlite3_column_bytes(S,N)] interface returns the
3882
- ** number of bytes in the BLOB or string (exclusive of the
3883
- ** zero terminator on the string) that was returned by the
3884
- ** most recent call to [sqlite3_column_blob(S,N)] or
3885
- ** [sqlite3_column_text(S,N)].
3886
- **
3887
- ** {H13809} The [sqlite3_column_bytes16(S,N)] interface returns the
3888
- ** number of bytes in the string (exclusive of the
3889
- ** zero terminator on the string) that was returned by the
3890
- ** most recent call to [sqlite3_column_text16(S,N)].
3891
- **
3892
- ** {H13812} The [sqlite3_column_double(S,N)] interface converts the
3893
- ** Nth column in the current row of the result set for the
3894
- ** [prepared statement] S into a floating point value and
3895
- ** returns a copy of that value.
3896
- **
3897
- ** {H13815} The [sqlite3_column_int(S,N)] interface converts the
3898
- ** Nth column in the current row of the result set for the
3899
- ** [prepared statement] S into a 64-bit signed integer and
3900
- ** returns the lower 32 bits of that integer.
3901
- **
3902
- ** {H13818} The [sqlite3_column_int64(S,N)] interface converts the
3903
- ** Nth column in the current row of the result set for the
3904
- ** [prepared statement] S into a 64-bit signed integer and
3905
- ** returns a copy of that integer.
3906
- **
3907
- ** {H13821} The [sqlite3_column_text(S,N)] interface converts the
3908
- ** Nth column in the current row of the result set for
3909
- ** the [prepared statement] S into a zero-terminated UTF-8
3910
- ** string and returns a pointer to that string.
3911
- **
3912
- ** {H13824} The [sqlite3_column_text16(S,N)] interface converts the
3913
- ** Nth column in the current row of the result set for the
3914
- ** [prepared statement] S into a zero-terminated 2-byte
3915
- ** aligned UTF-16 native byte order string and returns
3916
- ** a pointer to that string.
3917
- **
3918
- ** {H13827} The [sqlite3_column_type(S,N)] interface returns
3919
- ** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
3920
- ** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
3921
- ** the Nth column in the current row of the result set for
3922
- ** the [prepared statement] S.
3923
- **
3924
- ** {H13830} The [sqlite3_column_value(S,N)] interface returns a
3925
- ** pointer to an [unprotected sqlite3_value] object for the
3926
- ** Nth column in the current row of the result set for
3927
- ** the [prepared statement] S.
2962
+ ** Requirements:
2963
+ ** [H13803] [H13806] [H13809] [H13812] [H13815] [H13818] [H13821] [H13824]
2964
+ ** [H13827] [H13830]
3928
2965
  */
3929
2966
  const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
3930
2967
  int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
@@ -3953,15 +2990,8 @@ sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
3953
2990
  ** depending on the circumstances, and the
3954
2991
  ** [error code] returned will be [SQLITE_ABORT].
3955
2992
  **
3956
- ** INVARIANTS:
3957
- **
3958
- ** {H11302} The [sqlite3_finalize(S)] interface destroys the
3959
- ** [prepared statement] S and releases all
3960
- ** memory and file resources held by that object.
3961
- **
3962
- ** {H11304} If the most recent call to [sqlite3_step(S)] for the
3963
- ** [prepared statement] S returned an error,
3964
- ** then [sqlite3_finalize(S)] returns that same error.
2993
+ ** Requirements:
2994
+ ** [H11302] [H11304]
3965
2995
  */
3966
2996
  int sqlite3_finalize(sqlite3_stmt *pStmt);
3967
2997
 
@@ -4068,70 +3098,9 @@ int sqlite3_reset(sqlite3_stmt *pStmt);
4068
3098
  ** close the database connection nor finalize or reset the prepared
4069
3099
  ** statement in which the function is running.
4070
3100
  **
4071
- ** INVARIANTS:
4072
- **
4073
- ** {H16103} The [sqlite3_create_function16(D,X,...)] interface shall behave
4074
- ** as [sqlite3_create_function(D,X,...)] in every way except that it
4075
- ** interprets the X argument as zero-terminated UTF-16
4076
- ** native byte order instead of as zero-terminated UTF-8.
4077
- **
4078
- ** {H16106} A successful invocation of the
4079
- ** [sqlite3_create_function(D,X,N,E,...)] interface shall register
4080
- ** or replaces callback functions in the [database connection] D
4081
- ** used to implement the SQL function named X with N parameters
4082
- ** and having a preferred text encoding of E.
4083
- **
4084
- ** {H16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)]
4085
- ** shall replace the P, F, S, and L values from any prior calls with
4086
- ** the same D, X, N, and E values.
4087
- **
4088
- ** {H16112} The [sqlite3_create_function(D,X,...)] interface shall fail
4089
- ** if the SQL function name X is
4090
- ** longer than 255 bytes exclusive of the zero terminator.
4091
- **
4092
- ** {H16118} The [sqlite3_create_function(D,X,N,E,P,F,S,L)] interface
4093
- ** shall fail unless either F is NULL and S and L are non-NULL or
4094
- *** F is non-NULL and S and L are NULL.
4095
- **
4096
- ** {H16121} The [sqlite3_create_function(D,...)] interface shall fails with an
4097
- ** error code of [SQLITE_BUSY] if there exist [prepared statements]
4098
- ** associated with the [database connection] D.
4099
- **
4100
- ** {H16124} The [sqlite3_create_function(D,X,N,...)] interface shall fail with
4101
- ** an error code of [SQLITE_ERROR] if parameter N is less
4102
- ** than -1 or greater than 127.
4103
- **
4104
- ** {H16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)]
4105
- ** interface shall register callbacks to be invoked for the
4106
- ** SQL function
4107
- ** named X when the number of arguments to the SQL function is
4108
- ** exactly N.
4109
- **
4110
- ** {H16130} When N is -1, the [sqlite3_create_function(D,X,N,...)]
4111
- ** interface shall register callbacks to be invoked for the SQL
4112
- ** function named X with any number of arguments.
4113
- **
4114
- ** {H16133} When calls to [sqlite3_create_function(D,X,N,...)]
4115
- ** specify multiple implementations of the same function X
4116
- ** and when one implementation has N>=0 and the other has N=(-1)
4117
- ** the implementation with a non-zero N shall be preferred.
4118
- **
4119
- ** {H16136} When calls to [sqlite3_create_function(D,X,N,E,...)]
4120
- ** specify multiple implementations of the same function X with
4121
- ** the same number of arguments N but with different
4122
- ** encodings E, then the implementation where E matches the
4123
- ** database encoding shall preferred.
4124
- **
4125
- ** {H16139} For an aggregate SQL function created using
4126
- ** [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finalizer
4127
- ** function L shall always be invoked exactly once if the
4128
- ** step function S is called one or more times.
4129
- **
4130
- ** {H16142} When SQLite invokes either the xFunc or xStep function of
4131
- ** an application-defined SQL function or aggregate created
4132
- ** by [sqlite3_create_function()] or [sqlite3_create_function16()],
4133
- ** then the array of [sqlite3_value] objects passed as the
4134
- ** third parameter shall be [protected sqlite3_value] objects.
3101
+ ** Requirements:
3102
+ ** [H16103] [H16106] [H16109] [H16112] [H16118] [H16121] [H16124] [H16127]
3103
+ ** [H16130] [H16133] [H16136] [H16139] [H16142]
4135
3104
  */
4136
3105
  int sqlite3_create_function(
4137
3106
  sqlite3 *db,
@@ -4231,67 +3200,9 @@ SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void
4231
3200
  ** These routines must be called from the same thread as
4232
3201
  ** the SQL function that supplied the [sqlite3_value*] parameters.
4233
3202
  **
4234
- ** INVARIANTS:
4235
- **
4236
- ** {H15103} The [sqlite3_value_blob(V)] interface converts the
4237
- ** [protected sqlite3_value] object V into a BLOB and then
4238
- ** returns a pointer to the converted value.
4239
- **
4240
- ** {H15106} The [sqlite3_value_bytes(V)] interface returns the
4241
- ** number of bytes in the BLOB or string (exclusive of the
4242
- ** zero terminator on the string) that was returned by the
4243
- ** most recent call to [sqlite3_value_blob(V)] or
4244
- ** [sqlite3_value_text(V)].
4245
- **
4246
- ** {H15109} The [sqlite3_value_bytes16(V)] interface returns the
4247
- ** number of bytes in the string (exclusive of the
4248
- ** zero terminator on the string) that was returned by the
4249
- ** most recent call to [sqlite3_value_text16(V)],
4250
- ** [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)].
4251
- **
4252
- ** {H15112} The [sqlite3_value_double(V)] interface converts the
4253
- ** [protected sqlite3_value] object V into a floating point value and
4254
- ** returns a copy of that value.
4255
- **
4256
- ** {H15115} The [sqlite3_value_int(V)] interface converts the
4257
- ** [protected sqlite3_value] object V into a 64-bit signed integer and
4258
- ** returns the lower 32 bits of that integer.
4259
- **
4260
- ** {H15118} The [sqlite3_value_int64(V)] interface converts the
4261
- ** [protected sqlite3_value] object V into a 64-bit signed integer and
4262
- ** returns a copy of that integer.
4263
- **
4264
- ** {H15121} The [sqlite3_value_text(V)] interface converts the
4265
- ** [protected sqlite3_value] object V into a zero-terminated UTF-8
4266
- ** string and returns a pointer to that string.
4267
- **
4268
- ** {H15124} The [sqlite3_value_text16(V)] interface converts the
4269
- ** [protected sqlite3_value] object V into a zero-terminated 2-byte
4270
- ** aligned UTF-16 native byte order
4271
- ** string and returns a pointer to that string.
4272
- **
4273
- ** {H15127} The [sqlite3_value_text16be(V)] interface converts the
4274
- ** [protected sqlite3_value] object V into a zero-terminated 2-byte
4275
- ** aligned UTF-16 big-endian
4276
- ** string and returns a pointer to that string.
4277
- **
4278
- ** {H15130} The [sqlite3_value_text16le(V)] interface converts the
4279
- ** [protected sqlite3_value] object V into a zero-terminated 2-byte
4280
- ** aligned UTF-16 little-endian
4281
- ** string and returns a pointer to that string.
4282
- **
4283
- ** {H15133} The [sqlite3_value_type(V)] interface returns
4284
- ** one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
4285
- ** [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
4286
- ** the [sqlite3_value] object V.
4287
- **
4288
- ** {H15136} The [sqlite3_value_numeric_type(V)] interface converts
4289
- ** the [protected sqlite3_value] object V into either an integer or
4290
- ** a floating point value if it can do so without loss of
4291
- ** information, and returns one of [SQLITE_NULL],
4292
- ** [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or
4293
- ** [SQLITE_BLOB] as appropriate for the
4294
- ** [protected sqlite3_value] object V after the conversion attempt.
3203
+ ** Requirements:
3204
+ ** [H15103] [H15106] [H15109] [H15112] [H15115] [H15118] [H15121] [H15124]
3205
+ ** [H15127] [H15130] [H15133] [H15136]
4295
3206
  */
4296
3207
  const void *sqlite3_value_blob(sqlite3_value*);
4297
3208
  int sqlite3_value_bytes(sqlite3_value*);
@@ -4329,25 +3240,8 @@ int sqlite3_value_numeric_type(sqlite3_value*);
4329
3240
  ** This routine must be called from the same thread in which
4330
3241
  ** the aggregate SQL function is running.
4331
3242
  **
4332
- ** INVARIANTS:
4333
- **
4334
- ** {H16211} The first invocation of [sqlite3_aggregate_context(C,N)] for
4335
- ** a particular instance of an aggregate function (for a particular
4336
- ** context C) causes SQLite to allocate N bytes of memory,
4337
- ** zero that memory, and return a pointer to the allocated memory.
4338
- **
4339
- ** {H16213} If a memory allocation error occurs during
4340
- ** [sqlite3_aggregate_context(C,N)] then the function returns 0.
4341
- **
4342
- ** {H16215} Second and subsequent invocations of
4343
- ** [sqlite3_aggregate_context(C,N)] for the same context pointer C
4344
- ** ignore the N parameter and return a pointer to the same
4345
- ** block of memory returned by the first invocation.
4346
- **
4347
- ** {H16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is
4348
- ** automatically freed on the next call to [sqlite3_reset()]
4349
- ** or [sqlite3_finalize()] for the [prepared statement] containing
4350
- ** the aggregate function associated with context C.
3243
+ ** Requirements:
3244
+ ** [H16211] [H16213] [H16215] [H16217]
4351
3245
  */
4352
3246
  void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
4353
3247
 
@@ -4363,12 +3257,8 @@ void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
4363
3257
  ** This routine must be called from the same thread in which
4364
3258
  ** the application-defined function is running.
4365
3259
  **
4366
- ** INVARIANTS:
4367
- **
4368
- ** {H16243} The [sqlite3_user_data(C)] interface returns a copy of the
4369
- ** P pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)]
4370
- ** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that
4371
- ** registered the SQL function associated with [sqlite3_context] C.
3260
+ ** Requirements:
3261
+ ** [H16243]
4372
3262
  */
4373
3263
  void *sqlite3_user_data(sqlite3_context*);
4374
3264
 
@@ -4381,12 +3271,8 @@ void *sqlite3_user_data(sqlite3_context*);
4381
3271
  ** and [sqlite3_create_function16()] routines that originally
4382
3272
  ** registered the application defined function.
4383
3273
  **
4384
- ** INVARIANTS:
4385
- **
4386
- ** {H16253} The [sqlite3_context_db_handle(C)] interface returns a copy of the
4387
- ** D pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)]
4388
- ** or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that
4389
- ** registered the SQL function associated with [sqlite3_context] C.
3274
+ ** Requirements:
3275
+ ** [H16253]
4390
3276
  */
4391
3277
  sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
4392
3278
 
@@ -4432,31 +3318,8 @@ sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
4432
3318
  ** These routines must be called from the same thread in which
4433
3319
  ** the SQL function is running.
4434
3320
  **
4435
- ** INVARIANTS:
4436
- **
4437
- ** {H16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer
4438
- ** to metadata associated with the Nth parameter of the SQL function
4439
- ** whose context is C, or NULL if there is no metadata associated
4440
- ** with that parameter.
4441
- **
4442
- ** {H16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata
4443
- ** pointer P to the Nth parameter of the SQL function with context C.
4444
- **
4445
- ** {H16276} SQLite will invoke the destructor D with a single argument
4446
- ** which is the metadata pointer P following a call to
4447
- ** [sqlite3_set_auxdata(C,N,P,D)] when SQLite ceases to hold
4448
- ** the metadata.
4449
- **
4450
- ** {H16277} SQLite ceases to hold metadata for an SQL function parameter
4451
- ** when the value of that parameter changes.
4452
- **
4453
- ** {H16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor
4454
- ** is called for any prior metadata associated with the same function
4455
- ** context C and parameter N.
4456
- **
4457
- ** {H16279} SQLite will call destructors for any metadata it is holding
4458
- ** in a particular [prepared statement] S when either
4459
- ** [sqlite3_reset(S)] or [sqlite3_finalize(S)] is called.
3321
+ ** Requirements:
3322
+ ** [H16272] [H16274] [H16276] [H16277] [H16278] [H16279]
4460
3323
  */
4461
3324
  void *sqlite3_get_auxdata(sqlite3_context*, int N);
4462
3325
  void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
@@ -4584,101 +3447,10 @@ typedef void (*sqlite3_destructor_type)(void*);
4584
3447
  ** than the one containing the application-defined function that received
4585
3448
  ** the [sqlite3_context] pointer, the results are undefined.
4586
3449
  **
4587
- ** INVARIANTS:
4588
- **
4589
- ** {H16403} The default return value from any SQL function is NULL.
4590
- **
4591
- ** {H16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the
4592
- ** return value of function C to be a BLOB that is N bytes
4593
- ** in length and with content pointed to by V.
4594
- **
4595
- ** {H16409} The [sqlite3_result_double(C,V)] interface changes the
4596
- ** return value of function C to be the floating point value V.
4597
- **
4598
- ** {H16412} The [sqlite3_result_error(C,V,N)] interface changes the return
4599
- ** value of function C to be an exception with error code
4600
- ** [SQLITE_ERROR] and a UTF-8 error message copied from V up to the
4601
- ** first zero byte or until N bytes are read if N is positive.
4602
- **
4603
- ** {H16415} The [sqlite3_result_error16(C,V,N)] interface changes the return
4604
- ** value of function C to be an exception with error code
4605
- ** [SQLITE_ERROR] and a UTF-16 native byte order error message
4606
- ** copied from V up to the first zero terminator or until N bytes
4607
- ** are read if N is positive.
4608
- **
4609
- ** {H16418} The [sqlite3_result_error_toobig(C)] interface changes the return
4610
- ** value of the function C to be an exception with error code
4611
- ** [SQLITE_TOOBIG] and an appropriate error message.
4612
- **
4613
- ** {H16421} The [sqlite3_result_error_nomem(C)] interface changes the return
4614
- ** value of the function C to be an exception with error code
4615
- ** [SQLITE_NOMEM] and an appropriate error message.
4616
- **
4617
- ** {H16424} The [sqlite3_result_error_code(C,E)] interface changes the return
4618
- ** value of the function C to be an exception with error code E.
4619
- ** The error message text is unchanged.
4620
- **
4621
- ** {H16427} The [sqlite3_result_int(C,V)] interface changes the
4622
- ** return value of function C to be the 32-bit integer value V.
4623
- **
4624
- ** {H16430} The [sqlite3_result_int64(C,V)] interface changes the
4625
- ** return value of function C to be the 64-bit integer value V.
4626
- **
4627
- ** {H16433} The [sqlite3_result_null(C)] interface changes the
4628
- ** return value of function C to be NULL.
4629
- **
4630
- ** {H16436} The [sqlite3_result_text(C,V,N,D)] interface changes the
4631
- ** return value of function C to be the UTF-8 string
4632
- ** V up to the first zero if N is negative
4633
- ** or the first N bytes of V if N is non-negative.
4634
- **
4635
- ** {H16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the
4636
- ** return value of function C to be the UTF-16 native byte order
4637
- ** string V up to the first zero if N is negative
4638
- ** or the first N bytes of V if N is non-negative.
4639
- **
4640
- ** {H16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the
4641
- ** return value of function C to be the UTF-16 big-endian
4642
- ** string V up to the first zero if N is negative
4643
- ** or the first N bytes or V if N is non-negative.
4644
- **
4645
- ** {H16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the
4646
- ** return value of function C to be the UTF-16 little-endian
4647
- ** string V up to the first zero if N is negative
4648
- ** or the first N bytes of V if N is non-negative.
4649
- **
4650
- ** {H16448} The [sqlite3_result_value(C,V)] interface changes the
4651
- ** return value of function C to be the [unprotected sqlite3_value]
4652
- ** object V.
4653
- **
4654
- ** {H16451} The [sqlite3_result_zeroblob(C,N)] interface changes the
4655
- ** return value of function C to be an N-byte BLOB of all zeros.
4656
- **
4657
- ** {H16454} The [sqlite3_result_error()] and [sqlite3_result_error16()]
4658
- ** interfaces make a copy of their error message strings before
4659
- ** returning.
4660
- **
4661
- ** {H16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
4662
- ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
4663
- ** [sqlite3_result_text16be(C,V,N,D)], or
4664
- ** [sqlite3_result_text16le(C,V,N,D)] is the constant [SQLITE_STATIC]
4665
- ** then no destructor is ever called on the pointer V and SQLite
4666
- ** assumes that V is immutable.
4667
- **
4668
- ** {H16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
4669
- ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
4670
- ** [sqlite3_result_text16be(C,V,N,D)], or
4671
- ** [sqlite3_result_text16le(C,V,N,D)] is the constant
4672
- ** [SQLITE_TRANSIENT] then the interfaces makes a copy of the
4673
- ** content of V and retains the copy.
4674
- **
4675
- ** {H16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
4676
- ** [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
4677
- ** [sqlite3_result_text16be(C,V,N,D)], or
4678
- ** [sqlite3_result_text16le(C,V,N,D)] is some value other than
4679
- ** the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then
4680
- ** SQLite will invoke the destructor D with V as its only argument
4681
- ** when it has finished with the V value.
3450
+ ** Requirements:
3451
+ ** [H16403] [H16406] [H16409] [H16412] [H16415] [H16418] [H16421] [H16424]
3452
+ ** [H16427] [H16430] [H16433] [H16436] [H16439] [H16442] [H16445] [H16448]
3453
+ ** [H16451] [H16454] [H16457] [H16460] [H16463]
4682
3454
  */
4683
3455
  void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
4684
3456
  void sqlite3_result_double(sqlite3_context*, double);
@@ -4739,54 +3511,9 @@ void sqlite3_result_zeroblob(sqlite3_context*, int n);
4739
3511
  ** collation creation functions or when the [database connection] is closed
4740
3512
  ** using [sqlite3_close()].
4741
3513
  **
4742
- ** INVARIANTS:
4743
- **
4744
- ** {H16603} A successful call to the
4745
- ** [sqlite3_create_collation_v2(B,X,E,P,F,D)] interface
4746
- ** registers function F as the comparison function used to
4747
- ** implement collation X on the [database connection] B for
4748
- ** databases having encoding E.
4749
- **
4750
- ** {H16604} SQLite understands the X parameter to
4751
- ** [sqlite3_create_collation_v2(B,X,E,P,F,D)] as a zero-terminated
4752
- ** UTF-8 string in which case is ignored for ASCII characters and
4753
- ** is significant for non-ASCII characters.
4754
- **
4755
- ** {H16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)]
4756
- ** with the same values for B, X, and E, override prior values
4757
- ** of P, F, and D.
4758
- **
4759
- ** {H16609} If the destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)]
4760
- ** is not NULL then it is called with argument P when the
4761
- ** collating function is dropped by SQLite.
4762
- **
4763
- ** {H16612} A collating function is dropped when it is overloaded.
4764
- **
4765
- ** {H16615} A collating function is dropped when the database connection
4766
- ** is closed using [sqlite3_close()].
4767
- **
4768
- ** {H16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)]
4769
- ** is passed through as the first parameter to the comparison
4770
- ** function F for all subsequent invocations of F.
4771
- **
4772
- ** {H16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly
4773
- ** the same as a call to [sqlite3_create_collation_v2()] with
4774
- ** the same parameters and a NULL destructor.
4775
- **
4776
- ** {H16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)],
4777
- ** SQLite uses the comparison function F for all text comparison
4778
- ** operations on the [database connection] B on text values that
4779
- ** use the collating sequence named X.
4780
- **
4781
- ** {H16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same
4782
- ** as [sqlite3_create_collation(B,X,E,P,F)] except that the
4783
- ** collation name X is understood as UTF-16 in native byte order
4784
- ** instead of UTF-8.
4785
- **
4786
- ** {H16630} When multiple comparison functions are available for the same
4787
- ** collating sequence, SQLite chooses the one whose text encoding
4788
- ** requires the least amount of conversion from the default
4789
- ** text encoding of the database.
3514
+ ** Requirements:
3515
+ ** [H16603] [H16604] [H16606] [H16609] [H16612] [H16615] [H16618] [H16621]
3516
+ ** [H16624] [H16627] [H16630]
4790
3517
  */
4791
3518
  int sqlite3_create_collation(
4792
3519
  sqlite3*,
@@ -4837,24 +3564,8 @@ int sqlite3_create_collation16(
4837
3564
  ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
4838
3565
  ** [sqlite3_create_collation_v2()].
4839
3566
  **
4840
- ** INVARIANTS:
4841
- **
4842
- ** {H16702} A successful call to [sqlite3_collation_needed(D,P,F)]
4843
- ** or [sqlite3_collation_needed16(D,P,F)] causes
4844
- ** the [database connection] D to invoke callback F with first
4845
- ** parameter P whenever it needs a comparison function for a
4846
- ** collating sequence that it does not know about.
4847
- **
4848
- ** {H16704} Each successful call to [sqlite3_collation_needed()] or
4849
- ** [sqlite3_collation_needed16()] overrides the callback registered
4850
- ** on the same [database connection] by prior calls to either
4851
- ** interface.
4852
- **
4853
- ** {H16706} The name of the requested collating function passed in the
4854
- ** 4th parameter to the callback is in UTF-8 if the callback
4855
- ** was registered using [sqlite3_collation_needed()] and
4856
- ** is in UTF-16 native byte order if the callback was
4857
- ** registered using [sqlite3_collation_needed16()].
3567
+ ** Requirements:
3568
+ ** [H16702] [H16704] [H16706]
4858
3569
  */
4859
3570
  int sqlite3_collation_needed(
4860
3571
  sqlite3*,
@@ -4906,16 +3617,7 @@ int sqlite3_rekey(
4906
3617
  ** SQLite implements this interface by calling the xSleep()
4907
3618
  ** method of the default [sqlite3_vfs] object.
4908
3619
  **
4909
- ** INVARIANTS:
4910
- **
4911
- ** {H10533} The [sqlite3_sleep(M)] interface invokes the xSleep
4912
- ** method of the default [sqlite3_vfs|VFS] in order to
4913
- ** suspend execution of the current thread for at least
4914
- ** M milliseconds.
4915
- **
4916
- ** {H10536} The [sqlite3_sleep(M)] interface returns the number of
4917
- ** milliseconds of sleep actually requested of the operating
4918
- ** system, which might be larger than the parameter M.
3620
+ ** Requirements: [H10533] [H10536]
4919
3621
  */
4920
3622
  int sqlite3_sleep(int);
4921
3623
 
@@ -4952,24 +3654,11 @@ SQLITE_EXTERN char *sqlite3_temp_directory;
4952
3654
  ** find out whether SQLite automatically rolled back the transaction after
4953
3655
  ** an error is to use this function.
4954
3656
  **
4955
- ** INVARIANTS:
4956
- **
4957
- ** {H12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or
4958
- ** zero if the [database connection] D is or is not in autocommit
4959
- ** mode, respectively.
3657
+ ** If another thread changes the autocommit status of the database
3658
+ ** connection while this routine is running, then the return value
3659
+ ** is undefined.
4960
3660
  **
4961
- ** {H12932} Autocommit mode is on by default.
4962
- **
4963
- ** {H12933} Autocommit mode is disabled by a successful [BEGIN] statement.
4964
- **
4965
- ** {H12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK]
4966
- ** statement.
4967
- **
4968
- ** ASSUMPTIONS:
4969
- **
4970
- ** {A12936} If another thread changes the autocommit status of the database
4971
- ** connection while this routine is running, then the return value
4972
- ** is undefined.
3661
+ ** Requirements: [H12931] [H12932] [H12933] [H12934]
4973
3662
  */
4974
3663
  int sqlite3_get_autocommit(sqlite3*);
4975
3664
 
@@ -4977,16 +3666,12 @@ int sqlite3_get_autocommit(sqlite3*);
4977
3666
  ** CAPI3REF: Find The Database Handle Of A Prepared Statement {H13120} <S60600>
4978
3667
  **
4979
3668
  ** The sqlite3_db_handle interface returns the [database connection] handle
4980
- ** to which a [prepared statement] belongs. The database handle returned by
4981
- ** sqlite3_db_handle is the same database handle that was the first argument
3669
+ ** to which a [prepared statement] belongs. The [database connection]
3670
+ ** returned by sqlite3_db_handle is the same [database connection] that was the first argument
4982
3671
  ** to the [sqlite3_prepare_v2()] call (or its variants) that was used to
4983
3672
  ** create the statement in the first place.
4984
3673
  **
4985
- ** INVARIANTS:
4986
- **
4987
- ** {H13123} The [sqlite3_db_handle(S)] interface returns a pointer
4988
- ** to the [database connection] associated with the
4989
- ** [prepared statement] S.
3674
+ ** Requirements: [H13123]
4990
3675
  */
4991
3676
  sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
4992
3677
 
@@ -4999,31 +3684,11 @@ sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
4999
3684
  ** associated with the database connection pDb. If no prepared statement
5000
3685
  ** satisfies the conditions of this routine, it returns NULL.
5001
3686
  **
5002
- ** INVARIANTS:
5003
- **
5004
- ** {H13143} If D is a [database connection] that holds one or more
5005
- ** unfinalized [prepared statements] and S is a NULL pointer,
5006
- ** then [sqlite3_next_stmt(D, S)] routine shall return a pointer
5007
- ** to one of the prepared statements associated with D.
5008
- **
5009
- ** {H13146} If D is a [database connection] that holds no unfinalized
5010
- ** [prepared statements] and S is a NULL pointer, then
5011
- ** [sqlite3_next_stmt(D, S)] routine shall return a NULL pointer.
5012
- **
5013
- ** {H13149} If S is a [prepared statement] in the [database connection] D
5014
- ** and S is not the last prepared statement in D, then
5015
- ** [sqlite3_next_stmt(D, S)] routine shall return a pointer
5016
- ** to the next prepared statement in D after S.
5017
- **
5018
- ** {H13152} If S is the last [prepared statement] in the
5019
- ** [database connection] D then the [sqlite3_next_stmt(D, S)]
5020
- ** routine shall return a NULL pointer.
5021
- **
5022
- ** ASSUMPTIONS:
3687
+ ** The [database connection] pointer D in a call to
3688
+ ** [sqlite3_next_stmt(D,S)] must refer to an open database
3689
+ ** connection and in particular must not be a NULL pointer.
5023
3690
  **
5024
- ** {A13154} The [database connection] pointer D in a call to
5025
- ** [sqlite3_next_stmt(D,S)] must refer to an open database
5026
- ** connection and in particular must not be a NULL pointer.
3691
+ ** Requirements: [H13143] [H13146] [H13149] [H13152]
5027
3692
  */
5028
3693
  sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
5029
3694
 
@@ -5064,41 +3729,9 @@ sqlite3_stmt *sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt);
5064
3729
  ** rolled back because a commit callback returned non-zero.
5065
3730
  ** <todo> Check on this </todo>
5066
3731
  **
5067
- ** INVARIANTS:
5068
- **
5069
- ** {H12951} The [sqlite3_commit_hook(D,F,P)] interface registers the
5070
- ** callback function F to be invoked with argument P whenever
5071
- ** a transaction commits on the [database connection] D.
5072
- **
5073
- ** {H12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P argument
5074
- ** from the previous call with the same [database connection] D,
5075
- ** or NULL on the first call for a particular database connection D.
5076
- **
5077
- ** {H12953} Each call to [sqlite3_commit_hook()] overwrites the callback
5078
- ** registered by prior calls.
5079
- **
5080
- ** {H12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL
5081
- ** then the commit hook callback is canceled and no callback
5082
- ** is invoked when a transaction commits.
5083
- **
5084
- ** {H12955} If the commit callback returns non-zero then the commit is
5085
- ** converted into a rollback.
5086
- **
5087
- ** {H12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the
5088
- ** callback function F to be invoked with argument P whenever
5089
- ** a transaction rolls back on the [database connection] D.
5090
- **
5091
- ** {H12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P
5092
- ** argument from the previous call with the same
5093
- ** [database connection] D, or NULL on the first call
5094
- ** for a particular database connection D.
5095
- **
5096
- ** {H12963} Each call to [sqlite3_rollback_hook()] overwrites the callback
5097
- ** registered by prior calls.
5098
- **
5099
- ** {H12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL
5100
- ** then the rollback hook callback is canceled and no callback
5101
- ** is invoked when a transaction rolls back.
3732
+ ** Requirements:
3733
+ ** [H12951] [H12952] [H12953] [H12954] [H12955]
3734
+ ** [H12961] [H12962] [H12963] [H12964]
5102
3735
  */
5103
3736
  void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
5104
3737
  void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
@@ -5137,36 +3770,8 @@ void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
5137
3770
  ** If another function was previously registered, its pArg value
5138
3771
  ** is returned. Otherwise NULL is returned.
5139
3772
  **
5140
- ** INVARIANTS:
5141
- **
5142
- ** {H12971} The [sqlite3_update_hook(D,F,P)] interface causes the callback
5143
- ** function F to be invoked with first parameter P whenever
5144
- ** a table row is modified, inserted, or deleted on
5145
- ** the [database connection] D.
5146
- **
5147
- ** {H12973} The [sqlite3_update_hook(D,F,P)] interface returns the value
5148
- ** of P for the previous call on the same [database connection] D,
5149
- ** or NULL for the first call.
5150
- **
5151
- ** {H12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)]
5152
- ** is NULL then the no update callbacks are made.
5153
- **
5154
- ** {H12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls
5155
- ** to the same interface on the same [database connection] D.
5156
- **
5157
- ** {H12979} The update hook callback is not invoked when internal system
5158
- ** tables such as sqlite_master and sqlite_sequence are modified.
5159
- **
5160
- ** {H12981} The second parameter to the update callback
5161
- ** is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
5162
- ** depending on the operation that caused the callback to be invoked.
5163
- **
5164
- ** {H12983} The third and fourth arguments to the callback contain pointers
5165
- ** to zero-terminated UTF-8 strings which are the names of the
5166
- ** database and table that is being updated.
5167
-
5168
- ** {H12985} The final callback parameter is the [rowid] of the row after
5169
- ** the change occurs.
3773
+ ** Requirements:
3774
+ ** [H12971] [H12973] [H12975] [H12977] [H12979] [H12981] [H12983] [H12986]
5170
3775
  */
5171
3776
  void *sqlite3_update_hook(
5172
3777
  sqlite3*,
@@ -5183,7 +3788,7 @@ void *sqlite3_update_hook(
5183
3788
  ** to the same database. Sharing is enabled if the argument is true
5184
3789
  ** and disabled if the argument is false.
5185
3790
  **
5186
- ** Cache sharing is enabled and disabled for an entire process. {END}
3791
+ ** Cache sharing is enabled and disabled for an entire process.
5187
3792
  ** This is a change as of SQLite version 3.5.0. In prior versions of SQLite,
5188
3793
  ** sharing was enabled or disabled for each thread separately.
5189
3794
  **
@@ -5203,19 +3808,9 @@ void *sqlite3_update_hook(
5203
3808
  ** future releases of SQLite. Applications that care about shared
5204
3809
  ** cache setting should set it explicitly.
5205
3810
  **
5206
- ** INVARIANTS:
5207
- **
5208
- ** {H10331} A successful invocation of [sqlite3_enable_shared_cache(B)]
5209
- ** will enable or disable shared cache mode for any subsequently
5210
- ** created [database connection] in the same process.
5211
- **
5212
- ** {H10336} When shared cache is enabled, the [sqlite3_create_module()]
5213
- ** interface will always return an error.
5214
- **
5215
- ** {H10337} The [sqlite3_enable_shared_cache(B)] interface returns
5216
- ** [SQLITE_OK] if shared cache was enabled or disabled successfully.
3811
+ ** See Also: [SQLite Shared-Cache Mode]
5217
3812
  **
5218
- ** {H10339} Shared cache is disabled by default.
3813
+ ** Requirements: [H10331] [H10336] [H10337] [H10339]
5219
3814
  */
5220
3815
  int sqlite3_enable_shared_cache(int);
5221
3816
 
@@ -5229,15 +3824,7 @@ int sqlite3_enable_shared_cache(int);
5229
3824
  ** sqlite3_release_memory() returns the number of bytes actually freed,
5230
3825
  ** which might be more or less than the amount requested.
5231
3826
  **
5232
- ** INVARIANTS:
5233
- **
5234
- ** {H17341} The [sqlite3_release_memory(N)] interface attempts to
5235
- ** free N bytes of heap memory by deallocating non-essential
5236
- ** memory allocations held by the database library.
5237
- **
5238
- ** {H16342} The [sqlite3_release_memory(N)] returns the number
5239
- ** of bytes actually freed, which might be more or less
5240
- ** than the amount requested.
3827
+ ** Requirements: [H17341] [H17342]
5241
3828
  */
5242
3829
  int sqlite3_release_memory(int);
5243
3830
 
@@ -5271,33 +3858,8 @@ int sqlite3_release_memory(int);
5271
3858
  ** version 3.5.0 there is no mechanism for limiting the heap usage for
5272
3859
  ** individual threads.
5273
3860
  **
5274
- ** INVARIANTS:
5275
- **
5276
- ** {H16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit
5277
- ** of N bytes on the amount of heap memory that may be allocated
5278
- ** using [sqlite3_malloc()] or [sqlite3_realloc()] at any point
5279
- ** in time.
5280
- **
5281
- ** {H16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would
5282
- ** cause the total amount of allocated memory to exceed the
5283
- ** soft heap limit, then [sqlite3_release_memory()] is invoked
5284
- ** in an attempt to reduce the memory usage prior to proceeding
5285
- ** with the memory allocation attempt.
5286
- **
5287
- ** {H16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger
5288
- ** attempts to reduce memory usage through the soft heap limit
5289
- ** mechanism continue even if the attempt to reduce memory
5290
- ** usage is unsuccessful.
5291
- **
5292
- ** {H16354} A negative or zero value for N in a call to
5293
- ** [sqlite3_soft_heap_limit(N)] means that there is no soft
5294
- ** heap limit and [sqlite3_release_memory()] will only be
5295
- ** called when memory is completely exhausted.
5296
- **
5297
- ** {H16355} The default value for the soft heap limit is zero.
5298
- **
5299
- ** {H16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the
5300
- ** values set by all prior calls.
3861
+ ** Requirements:
3862
+ ** [H16351] [H16352] [H16353] [H16354] [H16355] [H16358]
5301
3863
  */
5302
3864
  void sqlite3_soft_heap_limit(int);
5303
3865
 
@@ -5797,34 +4359,8 @@ typedef struct sqlite3_blob sqlite3_blob;
5797
4359
  ** rollback by the expiration of the BLOB. Such changes will eventually
5798
4360
  ** commit if the transaction continues to completion.
5799
4361
  **
5800
- ** INVARIANTS:
5801
- **
5802
- ** {H17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)]
5803
- ** interface shall open an [sqlite3_blob] object P on the BLOB
5804
- ** in column C of the table T in the database B on
5805
- ** the [database connection] D.
5806
- **
5807
- ** {H17814} A successful invocation of [sqlite3_blob_open(D,...)] shall start
5808
- ** a new transaction on the [database connection] D if that
5809
- ** connection is not already in a transaction.
5810
- **
5811
- ** {H17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface shall open
5812
- ** the BLOB for read and write access if and only if the F
5813
- ** parameter is non-zero.
5814
- **
5815
- ** {H17819} The [sqlite3_blob_open()] interface shall return [SQLITE_OK] on
5816
- ** success and an appropriate [error code] on failure.
5817
- **
5818
- ** {H17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)]
5819
- ** then subsequent calls to [sqlite3_errcode(D)],
5820
- ** [sqlite3_extended_errcode()],
5821
- ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return
5822
- ** information appropriate for that error.
5823
- **
5824
- ** {H17824} If any column in the row that a [sqlite3_blob] has open is
5825
- ** changed by a separate [UPDATE] or [DELETE] statement or by
5826
- ** an [ON CONFLICT] side effect, then the [sqlite3_blob] shall
5827
- ** be marked as invalid.
4362
+ ** Requirements:
4363
+ ** [H17813] [H17814] [H17816] [H17819] [H17821] [H17824]
5828
4364
  */
5829
4365
  int sqlite3_blob_open(
5830
4366
  sqlite3*,
@@ -5855,20 +4391,8 @@ int sqlite3_blob_open(
5855
4391
  ** The BLOB is closed unconditionally. Even if this routine returns
5856
4392
  ** an error code, the BLOB is still closed.
5857
4393
  **
5858
- ** INVARIANTS:
5859
- **
5860
- ** {H17833} The [sqlite3_blob_close(P)] interface closes an [sqlite3_blob]
5861
- ** object P previously opened using [sqlite3_blob_open()].
5862
- **
5863
- ** {H17836} Closing an [sqlite3_blob] object using
5864
- ** [sqlite3_blob_close()] shall cause the current transaction to
5865
- ** commit if there are no other open [sqlite3_blob] objects
5866
- ** or [prepared statements] on the same [database connection] and
5867
- ** the database connection is in [autocommit mode].
5868
- **
5869
- ** {H17839} The [sqlite3_blob_close(P)] interfaces shall close the
5870
- ** [sqlite3_blob] object P unconditionally, even if
5871
- ** [sqlite3_blob_close(P)] returns something other than [SQLITE_OK].
4394
+ ** Requirements:
4395
+ ** [H17833] [H17836] [H17839]
5872
4396
  */
5873
4397
  int sqlite3_blob_close(sqlite3_blob *);
5874
4398
 
@@ -5878,11 +4402,8 @@ int sqlite3_blob_close(sqlite3_blob *);
5878
4402
  ** Returns the size in bytes of the BLOB accessible via the open
5879
4403
  ** []BLOB handle] in its only argument.
5880
4404
  **
5881
- ** INVARIANTS:
5882
- **
5883
- ** {H17843} The [sqlite3_blob_bytes(P)] interface returns the size
5884
- ** in bytes of the BLOB that the [sqlite3_blob] object P
5885
- ** refers to.
4405
+ ** Requirements:
4406
+ ** [H17843]
5886
4407
  */
5887
4408
  int sqlite3_blob_bytes(sqlite3_blob *);
5888
4409
 
@@ -5903,38 +4424,8 @@ int sqlite3_blob_bytes(sqlite3_blob *);
5903
4424
  ** On success, SQLITE_OK is returned.
5904
4425
  ** Otherwise, an [error code] or an [extended error code] is returned.
5905
4426
  **
5906
- ** INVARIANTS:
5907
- **
5908
- ** {H17853} A successful invocation of [sqlite3_blob_read(P,Z,N,X)]
5909
- ** shall reads N bytes of data out of the BLOB referenced by
5910
- ** [BLOB handle] P beginning at offset X and store those bytes
5911
- ** into buffer Z.
5912
- **
5913
- ** {H17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the BLOB
5914
- ** is less than N+X bytes, then the function shall leave the
5915
- ** Z buffer unchanged and return [SQLITE_ERROR].
5916
- **
5917
- ** {H17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero
5918
- ** then the function shall leave the Z buffer unchanged
5919
- ** and return [SQLITE_ERROR].
5920
- **
5921
- ** {H17862} The [sqlite3_blob_read(P,Z,N,X)] interface shall return [SQLITE_OK]
5922
- ** if N bytes are successfully read into buffer Z.
5923
- **
5924
- ** {H17863} If the [BLOB handle] P is expired and X and N are within bounds
5925
- ** then [sqlite3_blob_read(P,Z,N,X)] shall leave the Z buffer
5926
- ** unchanged and return [SQLITE_ABORT].
5927
- **
5928
- ** {H17865} If the requested read could not be completed,
5929
- ** the [sqlite3_blob_read(P,Z,N,X)] interface shall return an
5930
- ** appropriate [error code] or [extended error code].
5931
- **
5932
- ** {H17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)]
5933
- ** then subsequent calls to [sqlite3_errcode(D)],
5934
- ** [sqlite3_extended_errcode()],
5935
- ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return
5936
- ** information appropriate for that error, where D is the
5937
- ** [database connection] that was used to open the [BLOB handle] P.
4427
+ ** Requirements:
4428
+ ** [H17853] [H17856] [H17859] [H17862] [H17863] [H17865] [H17868]
5938
4429
  */
5939
4430
  int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
5940
4431
 
@@ -5965,45 +4456,9 @@ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
5965
4456
  ** On success, SQLITE_OK is returned.
5966
4457
  ** Otherwise, an [error code] or an [extended error code] is returned.
5967
4458
  **
5968
- ** INVARIANTS:
5969
- **
5970
- ** {H17873} A successful invocation of [sqlite3_blob_write(P,Z,N,X)]
5971
- ** shall write N bytes of data from buffer Z into the BLOB
5972
- ** referenced by [BLOB handle] P beginning at offset X into
5973
- ** the BLOB.
5974
- **
5975
- ** {H17874} In the absence of other overridding changes, the changes
5976
- ** written to a BLOB by [sqlite3_blob_write()] shall
5977
- ** remain in effect after the associated [BLOB handle] expires.
5978
- **
5979
- ** {H17875} If the [BLOB handle] P was opened for reading only then
5980
- ** an invocation of [sqlite3_blob_write(P,Z,N,X)] shall leave
5981
- ** the referenced BLOB unchanged and return [SQLITE_READONLY].
5982
- **
5983
- ** {H17876} If the size of the BLOB referenced by [BLOB handle] P is
5984
- ** less than N+X bytes then [sqlite3_blob_write(P,Z,N,X)] shall
5985
- ** leave the BLOB unchanged and return [SQLITE_ERROR].
5986
- **
5987
- ** {H17877} If the [BLOB handle] P is expired and X and N are within bounds
5988
- ** then [sqlite3_blob_read(P,Z,N,X)] shall leave the BLOB
5989
- ** unchanged and return [SQLITE_ABORT].
5990
- **
5991
- ** {H17879} If X or N are less than zero then [sqlite3_blob_write(P,Z,N,X)]
5992
- ** shall leave the BLOB referenced by [BLOB handle] P unchanged
5993
- ** and return [SQLITE_ERROR].
5994
- **
5995
- ** {H17882} The [sqlite3_blob_write(P,Z,N,X)] interface shall return
5996
- ** [SQLITE_OK] if N bytes where successfully written into the BLOB.
5997
- **
5998
- ** {H17885} If the requested write could not be completed,
5999
- ** the [sqlite3_blob_write(P,Z,N,X)] interface shall return an
6000
- ** appropriate [error code] or [extended error code].
6001
- **
6002
- ** {H17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)]
6003
- ** then subsequent calls to [sqlite3_errcode(D)],
6004
- ** [sqlite3_extended_errcode()],
6005
- ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return
6006
- ** information appropriate for that error.
4459
+ ** Requirements:
4460
+ ** [H17873] [H17874] [H17875] [H17876] [H17877] [H17879] [H17882] [H17885]
4461
+ ** [H17888]
6007
4462
  */
6008
4463
  int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
6009
4464
 
@@ -6036,31 +4491,8 @@ int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
6036
4491
  ** If the default VFS is unregistered, another VFS is chosen as
6037
4492
  ** the default. The choice for the new VFS is arbitrary.
6038
4493
  **
6039
- ** INVARIANTS:
6040
- **
6041
- ** {H11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the
6042
- ** registered [sqlite3_vfs] object whose name exactly matches
6043
- ** the zero-terminated UTF-8 string N, or it returns NULL if
6044
- ** there is no match.
6045
- **
6046
- ** {H11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then
6047
- ** the function returns a pointer to the default [sqlite3_vfs]
6048
- ** object if there is one, or NULL if there is no default
6049
- ** [sqlite3_vfs] object.
6050
- **
6051
- ** {H11209} The [sqlite3_vfs_register(P,F)] interface registers the
6052
- ** well-formed [sqlite3_vfs] object P using the name given
6053
- ** by the zName field of the object.
6054
- **
6055
- ** {H11212} Using the [sqlite3_vfs_register(P,F)] interface to register
6056
- ** the same [sqlite3_vfs] object multiple times is a harmless no-op.
6057
- **
6058
- ** {H11215} The [sqlite3_vfs_register(P,F)] interface makes the [sqlite3_vfs]
6059
- ** object P the default [sqlite3_vfs] object if F is non-zero.
6060
- **
6061
- ** {H11218} The [sqlite3_vfs_unregister(P)] interface unregisters the
6062
- ** [sqlite3_vfs] object P so that it is no longer returned by
6063
- ** subsequent calls to [sqlite3_vfs_find()].
4494
+ ** Requirements:
4495
+ ** [H11203] [H11206] [H11209] [H11212] [H11215] [H11218]
6064
4496
  */
6065
4497
  sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
6066
4498
  int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
@@ -6294,7 +4726,8 @@ int sqlite3_mutex_notheld(sqlite3_mutex*);
6294
4726
  #define SQLITE_MUTEX_RECURSIVE 1
6295
4727
  #define SQLITE_MUTEX_STATIC_MASTER 2
6296
4728
  #define SQLITE_MUTEX_STATIC_MEM 3 /* sqlite3_malloc() */
6297
- #define SQLITE_MUTEX_STATIC_MEM2 4 /* sqlite3_release_memory() */
4729
+ #define SQLITE_MUTEX_STATIC_MEM2 4 /* NOT USED */
4730
+ #define SQLITE_MUTEX_STATIC_OPEN 4 /* sqlite3BtreeOpen() */
6298
4731
  #define SQLITE_MUTEX_STATIC_PRNG 5 /* sqlite3_random() */
6299
4732
  #define SQLITE_MUTEX_STATIC_LRU 6 /* lru page list */
6300
4733
  #define SQLITE_MUTEX_STATIC_LRU2 7 /* lru page list */
@@ -6372,6 +4805,7 @@ int sqlite3_test_control(int op, ...);
6372
4805
  #define SQLITE_TESTCTRL_BITVEC_TEST 8
6373
4806
  #define SQLITE_TESTCTRL_FAULT_INSTALL 9
6374
4807
  #define SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS 10
4808
+ #define SQLITE_TESTCTRL_PENDING_BYTE 11
6375
4809
 
6376
4810
  /*
6377
4811
  ** CAPI3REF: SQLite Runtime Status {H17200} <S60200>
@@ -6661,17 +5095,17 @@ typedef struct sqlite3_pcache sqlite3_pcache;
6661
5095
  ** in which case SQLite will attempt to unpin one or more
6662
5096
  ** pages before re-requesting the same page, or it can
6663
5097
  ** allocate a new page and return a pointer to it. If a new
6664
- ** page is allocated, then it must be completely zeroed before
6665
- ** it is returned.
5098
+ ** page is allocated, then the first sizeof(void*) bytes of
5099
+ ** it (at least) must be zeroed before it is returned.
6666
5100
  ** <tr><td>2<td>If createFlag is set to 2, then SQLite is not holding any
6667
5101
  ** pinned pages associated with the specific cache passed
6668
5102
  ** as the first argument to xFetch() that can be unpinned. The
6669
5103
  ** cache implementation should attempt to allocate a new
6670
- ** cache entry and return a pointer to it. Again, the new
6671
- ** page should be zeroed before it is returned. If the xFetch()
6672
- ** method returns NULL when createFlag==2, SQLite assumes that
6673
- ** a memory allocation failed and returns SQLITE_NOMEM to the
6674
- ** user.
5104
+ ** cache entry and return a pointer to it. Again, the first
5105
+ ** sizeof(void*) bytes of the page should be zeroed before
5106
+ ** it is returned. If the xFetch() method returns NULL when
5107
+ ** createFlag==2, SQLite assumes that a memory allocation
5108
+ ** failed and returns SQLITE_NOMEM to the user.
6675
5109
  ** </table>
6676
5110
  **
6677
5111
  ** xUnpin() is called by SQLite with a pointer to a currently pinned page
@@ -6722,6 +5156,323 @@ struct sqlite3_pcache_methods {
6722
5156
  void (*xDestroy)(sqlite3_pcache*);
6723
5157
  };
6724
5158
 
5159
+ /*
5160
+ ** CAPI3REF: Online Backup Object
5161
+ ** EXPERIMENTAL
5162
+ **
5163
+ ** The sqlite3_backup object records state information about an ongoing
5164
+ ** online backup operation. The sqlite3_backup object is created by
5165
+ ** a call to [sqlite3_backup_init()] and is destroyed by a call to
5166
+ ** [sqlite3_backup_finish()].
5167
+ **
5168
+ ** See Also: [Using the SQLite Online Backup API]
5169
+ */
5170
+ typedef struct sqlite3_backup sqlite3_backup;
5171
+
5172
+ /*
5173
+ ** CAPI3REF: Online Backup API.
5174
+ ** EXPERIMENTAL
5175
+ **
5176
+ ** This API is used to overwrite the contents of one database with that
5177
+ ** of another. It is useful either for creating backups of databases or
5178
+ ** for copying in-memory databases to or from persistent files.
5179
+ **
5180
+ ** See Also: [Using the SQLite Online Backup API]
5181
+ **
5182
+ ** Exclusive access is required to the destination database for the
5183
+ ** duration of the operation. However the source database is only
5184
+ ** read-locked while it is actually being read, it is not locked
5185
+ ** continuously for the entire operation. Thus, the backup may be
5186
+ ** performed on a live database without preventing other users from
5187
+ ** writing to the database for an extended period of time.
5188
+ **
5189
+ ** To perform a backup operation:
5190
+ ** <ol>
5191
+ ** <li><b>sqlite3_backup_init()</b> is called once to initialize the
5192
+ ** backup,
5193
+ ** <li><b>sqlite3_backup_step()</b> is called one or more times to transfer
5194
+ ** the data between the two databases, and finally
5195
+ ** <li><b>sqlite3_backup_finish()</b> is called to release all resources
5196
+ ** associated with the backup operation.
5197
+ ** </ol>
5198
+ ** There should be exactly one call to sqlite3_backup_finish() for each
5199
+ ** successful call to sqlite3_backup_init().
5200
+ **
5201
+ ** <b>sqlite3_backup_init()</b>
5202
+ **
5203
+ ** The first two arguments passed to [sqlite3_backup_init()] are the database
5204
+ ** handle associated with the destination database and the database name
5205
+ ** used to attach the destination database to the handle. The database name
5206
+ ** is "main" for the main database, "temp" for the temporary database, or
5207
+ ** the name specified as part of the [ATTACH] statement if the destination is
5208
+ ** an attached database. The third and fourth arguments passed to
5209
+ ** sqlite3_backup_init() identify the [database connection]
5210
+ ** and database name used
5211
+ ** to access the source database. The values passed for the source and
5212
+ ** destination [database connection] parameters must not be the same.
5213
+ **
5214
+ ** If an error occurs within sqlite3_backup_init(), then NULL is returned
5215
+ ** and an error code and error message written into the [database connection]
5216
+ ** passed as the first argument. They may be retrieved using the
5217
+ ** [sqlite3_errcode()], [sqlite3_errmsg()], and [sqlite3_errmsg16()] functions.
5218
+ ** Otherwise, if successful, a pointer to an [sqlite3_backup] object is
5219
+ ** returned. This pointer may be used with the sqlite3_backup_step() and
5220
+ ** sqlite3_backup_finish() functions to perform the specified backup
5221
+ ** operation.
5222
+ **
5223
+ ** <b>sqlite3_backup_step()</b>
5224
+ **
5225
+ ** Function [sqlite3_backup_step()] is used to copy up to nPage pages between
5226
+ ** the source and destination databases, where nPage is the value of the
5227
+ ** second parameter passed to sqlite3_backup_step(). If nPage is a negative
5228
+ ** value, all remaining source pages are copied. If the required pages are
5229
+ ** succesfully copied, but there are still more pages to copy before the
5230
+ ** backup is complete, it returns [SQLITE_OK]. If no error occured and there
5231
+ ** are no more pages to copy, then [SQLITE_DONE] is returned. If an error
5232
+ ** occurs, then an SQLite error code is returned. As well as [SQLITE_OK] and
5233
+ ** [SQLITE_DONE], a call to sqlite3_backup_step() may return [SQLITE_READONLY],
5234
+ ** [SQLITE_NOMEM], [SQLITE_BUSY], [SQLITE_LOCKED], or an
5235
+ ** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] extended error code.
5236
+ **
5237
+ ** As well as the case where the destination database file was opened for
5238
+ ** read-only access, sqlite3_backup_step() may return [SQLITE_READONLY] if
5239
+ ** the destination is an in-memory database with a different page size
5240
+ ** from the source database.
5241
+ **
5242
+ ** If sqlite3_backup_step() cannot obtain a required file-system lock, then
5243
+ ** the [sqlite3_busy_handler | busy-handler function]
5244
+ ** is invoked (if one is specified). If the
5245
+ ** busy-handler returns non-zero before the lock is available, then
5246
+ ** [SQLITE_BUSY] is returned to the caller. In this case the call to
5247
+ ** sqlite3_backup_step() can be retried later. If the source
5248
+ ** [database connection]
5249
+ ** is being used to write to the source database when sqlite3_backup_step()
5250
+ ** is called, then [SQLITE_LOCKED] is returned immediately. Again, in this
5251
+ ** case the call to sqlite3_backup_step() can be retried later on. If
5252
+ ** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX], [SQLITE_NOMEM], or
5253
+ ** [SQLITE_READONLY] is returned, then
5254
+ ** there is no point in retrying the call to sqlite3_backup_step(). These
5255
+ ** errors are considered fatal. At this point the application must accept
5256
+ ** that the backup operation has failed and pass the backup operation handle
5257
+ ** to the sqlite3_backup_finish() to release associated resources.
5258
+ **
5259
+ ** Following the first call to sqlite3_backup_step(), an exclusive lock is
5260
+ ** obtained on the destination file. It is not released until either
5261
+ ** sqlite3_backup_finish() is called or the backup operation is complete
5262
+ ** and sqlite3_backup_step() returns [SQLITE_DONE]. Additionally, each time
5263
+ ** a call to sqlite3_backup_step() is made a [shared lock] is obtained on
5264
+ ** the source database file. This lock is released before the
5265
+ ** sqlite3_backup_step() call returns. Because the source database is not
5266
+ ** locked between calls to sqlite3_backup_step(), it may be modified mid-way
5267
+ ** through the backup procedure. If the source database is modified by an
5268
+ ** external process or via a database connection other than the one being
5269
+ ** used by the backup operation, then the backup will be transparently
5270
+ ** restarted by the next call to sqlite3_backup_step(). If the source
5271
+ ** database is modified by the using the same database connection as is used
5272
+ ** by the backup operation, then the backup database is transparently
5273
+ ** updated at the same time.
5274
+ **
5275
+ ** <b>sqlite3_backup_finish()</b>
5276
+ **
5277
+ ** Once sqlite3_backup_step() has returned [SQLITE_DONE], or when the
5278
+ ** application wishes to abandon the backup operation, the [sqlite3_backup]
5279
+ ** object should be passed to sqlite3_backup_finish(). This releases all
5280
+ ** resources associated with the backup operation. If sqlite3_backup_step()
5281
+ ** has not yet returned [SQLITE_DONE], then any active write-transaction on the
5282
+ ** destination database is rolled back. The [sqlite3_backup] object is invalid
5283
+ ** and may not be used following a call to sqlite3_backup_finish().
5284
+ **
5285
+ ** The value returned by sqlite3_backup_finish is [SQLITE_OK] if no error
5286
+ ** occurred, regardless or whether or not sqlite3_backup_step() was called
5287
+ ** a sufficient number of times to complete the backup operation. Or, if
5288
+ ** an out-of-memory condition or IO error occured during a call to
5289
+ ** sqlite3_backup_step() then [SQLITE_NOMEM] or an
5290
+ ** [SQLITE_IOERR_ACCESS | SQLITE_IOERR_XXX] error code
5291
+ ** is returned. In this case the error code and an error message are
5292
+ ** written to the destination [database connection].
5293
+ **
5294
+ ** A return of [SQLITE_BUSY] or [SQLITE_LOCKED] from sqlite3_backup_step() is
5295
+ ** not a permanent error and does not affect the return value of
5296
+ ** sqlite3_backup_finish().
5297
+ **
5298
+ ** <b>sqlite3_backup_remaining(), sqlite3_backup_pagecount()</b>
5299
+ **
5300
+ ** Each call to sqlite3_backup_step() sets two values stored internally
5301
+ ** by an [sqlite3_backup] object. The number of pages still to be backed
5302
+ ** up, which may be queried by sqlite3_backup_remaining(), and the total
5303
+ ** number of pages in the source database file, which may be queried by
5304
+ ** sqlite3_backup_pagecount().
5305
+ **
5306
+ ** The values returned by these functions are only updated by
5307
+ ** sqlite3_backup_step(). If the source database is modified during a backup
5308
+ ** operation, then the values are not updated to account for any extra
5309
+ ** pages that need to be updated or the size of the source database file
5310
+ ** changing.
5311
+ **
5312
+ ** <b>Concurrent Usage of Database Handles</b>
5313
+ **
5314
+ ** The source [database connection] may be used by the application for other
5315
+ ** purposes while a backup operation is underway or being initialized.
5316
+ ** If SQLite is compiled and configured to support threadsafe database
5317
+ ** connections, then the source database connection may be used concurrently
5318
+ ** from within other threads.
5319
+ **
5320
+ ** However, the application must guarantee that the destination database
5321
+ ** connection handle is not passed to any other API (by any thread) after
5322
+ ** sqlite3_backup_init() is called and before the corresponding call to
5323
+ ** sqlite3_backup_finish(). Unfortunately SQLite does not currently check
5324
+ ** for this, if the application does use the destination [database connection]
5325
+ ** for some other purpose during a backup operation, things may appear to
5326
+ ** work correctly but in fact be subtly malfunctioning. Use of the
5327
+ ** destination database connection while a backup is in progress might
5328
+ ** also cause a mutex deadlock.
5329
+ **
5330
+ ** Furthermore, if running in [shared cache mode], the application must
5331
+ ** guarantee that the shared cache used by the destination database
5332
+ ** is not accessed while the backup is running. In practice this means
5333
+ ** that the application must guarantee that the file-system file being
5334
+ ** backed up to is not accessed by any connection within the process,
5335
+ ** not just the specific connection that was passed to sqlite3_backup_init().
5336
+ **
5337
+ ** The [sqlite3_backup] object itself is partially threadsafe. Multiple
5338
+ ** threads may safely make multiple concurrent calls to sqlite3_backup_step().
5339
+ ** However, the sqlite3_backup_remaining() and sqlite3_backup_pagecount()
5340
+ ** APIs are not strictly speaking threadsafe. If they are invoked at the
5341
+ ** same time as another thread is invoking sqlite3_backup_step() it is
5342
+ ** possible that they return invalid values.
5343
+ */
5344
+ sqlite3_backup *sqlite3_backup_init(
5345
+ sqlite3 *pDest, /* Destination database handle */
5346
+ const char *zDestName, /* Destination database name */
5347
+ sqlite3 *pSource, /* Source database handle */
5348
+ const char *zSourceName /* Source database name */
5349
+ );
5350
+ int sqlite3_backup_step(sqlite3_backup *p, int nPage);
5351
+ int sqlite3_backup_finish(sqlite3_backup *p);
5352
+ int sqlite3_backup_remaining(sqlite3_backup *p);
5353
+ int sqlite3_backup_pagecount(sqlite3_backup *p);
5354
+
5355
+ /*
5356
+ ** CAPI3REF: Unlock Notification
5357
+ ** EXPERIMENTAL
5358
+ **
5359
+ ** When running in shared-cache mode, a database operation may fail with
5360
+ ** an [SQLITE_LOCKED] error if the required locks on the shared-cache or
5361
+ ** individual tables within the shared-cache cannot be obtained. See
5362
+ ** [SQLite Shared-Cache Mode] for a description of shared-cache locking.
5363
+ ** This API may be used to register a callback that SQLite will invoke
5364
+ ** when the connection currently holding the required lock relinquishes it.
5365
+ ** This API is only available if the library was compiled with the
5366
+ ** [SQLITE_ENABLE_UNLOCK_NOTIFY] C-preprocessor symbol defined.
5367
+ **
5368
+ ** See Also: [Using the SQLite Unlock Notification Feature].
5369
+ **
5370
+ ** Shared-cache locks are released when a database connection concludes
5371
+ ** its current transaction, either by committing it or rolling it back.
5372
+ **
5373
+ ** When a connection (known as the blocked connection) fails to obtain a
5374
+ ** shared-cache lock and SQLITE_LOCKED is returned to the caller, the
5375
+ ** identity of the database connection (the blocking connection) that
5376
+ ** has locked the required resource is stored internally. After an
5377
+ ** application receives an SQLITE_LOCKED error, it may call the
5378
+ ** sqlite3_unlock_notify() method with the blocked connection handle as
5379
+ ** the first argument to register for a callback that will be invoked
5380
+ ** when the blocking connections current transaction is concluded. The
5381
+ ** callback is invoked from within the [sqlite3_step] or [sqlite3_close]
5382
+ ** call that concludes the blocking connections transaction.
5383
+ **
5384
+ ** If sqlite3_unlock_notify() is called in a multi-threaded application,
5385
+ ** there is a chance that the blocking connection will have already
5386
+ ** concluded its transaction by the time sqlite3_unlock_notify() is invoked.
5387
+ ** If this happens, then the specified callback is invoked immediately,
5388
+ ** from within the call to sqlite3_unlock_notify().
5389
+ **
5390
+ ** If the blocked connection is attempting to obtain a write-lock on a
5391
+ ** shared-cache table, and more than one other connection currently holds
5392
+ ** a read-lock on the same table, then SQLite arbitrarily selects one of
5393
+ ** the other connections to use as the blocking connection.
5394
+ **
5395
+ ** There may be at most one unlock-notify callback registered by a
5396
+ ** blocked connection. If sqlite3_unlock_notify() is called when the
5397
+ ** blocked connection already has a registered unlock-notify callback,
5398
+ ** then the new callback replaces the old. If sqlite3_unlock_notify() is
5399
+ ** called with a NULL pointer as its second argument, then any existing
5400
+ ** unlock-notify callback is cancelled. The blocked connections
5401
+ ** unlock-notify callback may also be canceled by closing the blocked
5402
+ ** connection using [sqlite3_close()].
5403
+ **
5404
+ ** The unlock-notify callback is not reentrant. If an application invokes
5405
+ ** any sqlite3_xxx API functions from within an unlock-notify callback, a
5406
+ ** crash or deadlock may be the result.
5407
+ **
5408
+ ** Unless deadlock is detected (see below), sqlite3_unlock_notify() always
5409
+ ** returns SQLITE_OK.
5410
+ **
5411
+ ** <b>Callback Invocation Details</b>
5412
+ **
5413
+ ** When an unlock-notify callback is registered, the application provides a
5414
+ ** single void* pointer that is passed to the callback when it is invoked.
5415
+ ** However, the signature of the callback function allows SQLite to pass
5416
+ ** it an array of void* context pointers. The first argument passed to
5417
+ ** an unlock-notify callback is a pointer to an array of void* pointers,
5418
+ ** and the second is the number of entries in the array.
5419
+ **
5420
+ ** When a blocking connections transaction is concluded, there may be
5421
+ ** more than one blocked connection that has registered for an unlock-notify
5422
+ ** callback. If two or more such blocked connections have specified the
5423
+ ** same callback function, then instead of invoking the callback function
5424
+ ** multiple times, it is invoked once with the set of void* context pointers
5425
+ ** specified by the blocked connections bundled together into an array.
5426
+ ** This gives the application an opportunity to prioritize any actions
5427
+ ** related to the set of unblocked database connections.
5428
+ **
5429
+ ** <b>Deadlock Detection</b>
5430
+ **
5431
+ ** Assuming that after registering for an unlock-notify callback a
5432
+ ** database waits for the callback to be issued before taking any further
5433
+ ** action (a reasonable assumption), then using this API may cause the
5434
+ ** application to deadlock. For example, if connection X is waiting for
5435
+ ** connection Y's transaction to be concluded, and similarly connection
5436
+ ** Y is waiting on connection X's transaction, then neither connection
5437
+ ** will proceed and the system may remain deadlocked indefinitely.
5438
+ **
5439
+ ** To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
5440
+ ** detection. If a given call to sqlite3_unlock_notify() would put the
5441
+ ** system in a deadlocked state, then SQLITE_LOCKED is returned and no
5442
+ ** unlock-notify callback is registered. The system is said to be in
5443
+ ** a deadlocked state if connection A has registered for an unlock-notify
5444
+ ** callback on the conclusion of connection B's transaction, and connection
5445
+ ** B has itself registered for an unlock-notify callback when connection
5446
+ ** A's transaction is concluded. Indirect deadlock is also detected, so
5447
+ ** the system is also considered to be deadlocked if connection B has
5448
+ ** registered for an unlock-notify callback on the conclusion of connection
5449
+ ** C's transaction, where connection C is waiting on connection A. Any
5450
+ ** number of levels of indirection are allowed.
5451
+ **
5452
+ ** <b>The "DROP TABLE" Exception</b>
5453
+ **
5454
+ ** When a call to [sqlite3_step()] returns SQLITE_LOCKED, it is almost
5455
+ ** always appropriate to call sqlite3_unlock_notify(). There is however,
5456
+ ** one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
5457
+ ** SQLite checks if there are any currently executing SELECT statements
5458
+ ** that belong to the same connection. If there are, SQLITE_LOCKED is
5459
+ ** returned. In this case there is no "blocking connection", so invoking
5460
+ ** sqlite3_unlock_notify() results in the unlock-notify callback being
5461
+ ** invoked immediately. If the application then re-attempts the "DROP TABLE"
5462
+ ** or "DROP INDEX" query, an infinite loop might be the result.
5463
+ **
5464
+ ** One way around this problem is to check the extended error code returned
5465
+ ** by an sqlite3_step() call. If there is a blocking connection, then the
5466
+ ** extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
5467
+ ** the special "DROP TABLE/INDEX" case, the extended error code is just
5468
+ ** SQLITE_LOCKED.
5469
+ */
5470
+ int sqlite3_unlock_notify(
5471
+ sqlite3 *pBlocked, /* Waiting connection */
5472
+ void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
5473
+ void *pNotifyArg /* Argument to pass to xNotify */
5474
+ );
5475
+
6725
5476
  /*
6726
5477
  ** Undo the hack that converts floating point types to integer for
6727
5478
  ** builds on processors without floating point support.