@cryptotaxi247 / netdata-1 / commits / e9d59e37d

Migrate metadata log to SQLite (#10139)

Stelios Fragkakis committed Nov 24, 2020 at 20:00 UTC e9d59e37d98db379fcbeeffeb6046af0f9cb2d2f
40 files changed +244110 -2598
CMakeLists.txt
+6 -3
@@ -597,6 +597,10 @@ set(RRD_PLUGIN_FILES
597 database/rrdsetvar.h
598 database/rrdvar.c
599 database/rrdvar.h
600 + database/sqlite/sqlite_functions.c
601 + database/sqlite/sqlite_functions.h
602 + database/sqlite/sqlite3.c
603 + database/sqlite/sqlite3.h
604 database/engine/rrdengine.c
605 database/engine/rrdengine.h
606 database/engine/rrddiskprotocol.h
@@ -612,7 +616,6 @@ set(RRD_PLUGIN_FILES
616 database/engine/pagecache.h
617 database/engine/rrdenglocking.c
618 database/engine/rrdenglocking.h
615 - database/engine/metadata_log/metadatalog.c
619 database/engine/metadata_log/metadatalog.h
620 database/engine/metadata_log/metadatalogapi.c
621 database/engine/metadata_log/metadatalogapi.h
@@ -623,8 +626,6 @@ set(RRD_PLUGIN_FILES
626 database/engine/metadata_log/metalogpluginsd.h
627 database/engine/metadata_log/compaction.c
628 database/engine/metadata_log/compaction.h
626 - database/engine/global_uuid_map/global_uuid_map.c
627 - database/engine/global_uuid_map/global_uuid_map.h
629 )
630
631 set(WEB_PLUGIN_FILES
@@ -1293,6 +1294,7 @@ endif()
1294 -Wl,--wrap=web_client_api_request_v1
1295 -Wl,--wrap=rrdhost_find_by_guid
1296 -Wl,--wrap=rrdset_find_byname
1297 + -Wl,--wrap=sql_create_host_by_uuid
1298 -Wl,--wrap=rrdset_find
1299 -Wl,--wrap=rrdpush_receiver_thread_spawn
1300 -Wl,--wrap=debug_int
@@ -1317,6 +1319,7 @@ endif()
1319 -Wl,--wrap=web_client_api_request_v1
1320 -Wl,--wrap=rrdhost_find_by_guid
1321 -Wl,--wrap=rrdset_find_byname
1322 + -Wl,--wrap=sql_create_host_by_uuid
1323 -Wl,--wrap=rrdset_find
1324 -Wl,--wrap=rrdpush_receiver_thread_spawn
1325 -Wl,--wrap=debug_int
Makefile.am
+4 -3
@@ -377,6 +377,10 @@ RRD_PLUGIN_FILES = \
377
378 if ENABLE_DBENGINE
379 RRD_PLUGIN_FILES += \
380 + database/sqlite/sqlite_functions.c \
381 + database/sqlite/sqlite_functions.h \
382 + database/sqlite/sqlite3.c \
383 + database/sqlite/sqlite3.h \
384 database/engine/rrdengine.c \
385 database/engine/rrdengine.h \
386 database/engine/rrddiskprotocol.h \
@@ -392,7 +396,6 @@ if ENABLE_DBENGINE
396 database/engine/pagecache.h \
397 database/engine/rrdenglocking.c \
398 database/engine/rrdenglocking.h \
395 - database/engine/metadata_log/metadatalog.c \
399 database/engine/metadata_log/metadatalog.h \
400 database/engine/metadata_log/metadatalogapi.c \
401 database/engine/metadata_log/metadatalogapi.h \
@@ -403,8 +406,6 @@ if ENABLE_DBENGINE
406 database/engine/metadata_log/metalogpluginsd.h \
407 database/engine/metadata_log/compaction.c \
408 database/engine/metadata_log/compaction.h \
406 - database/engine/global_uuid_map/global_uuid_map.c \
407 - database/engine/global_uuid_map/global_uuid_map.h \
409 $(NULL)
410 endif
411
collectors/plugins.d/pluginsd_parser.c
+8 -5
@@ -274,7 +274,7 @@ PARSER_RC pluginsd_end(char **words, void *user, PLUGINSD_ACTION *plugins_actio
274 PARSER_RC pluginsd_chart(char **words, void *user, PLUGINSD_ACTION *plugins_action)
275 {
276 RRDHOST *host = ((PARSER_USER_OBJECT *) user)->host;
277 - if (unlikely(!host)) {
277 + if (unlikely(!host && !((PARSER_USER_OBJECT *) user)->host_exists)) {
278 debug(D_PLUGINSD, "Ignoring chart belonging to missing or ignored host.");
279 return PARSER_RC_OK;
280 }
@@ -303,7 +303,10 @@ PARSER_RC pluginsd_chart(char **words, void *user, PLUGINSD_ACTION *plugins_act
303
304 // make sure we have the required variables
305 if (unlikely((!type || !*type || !id || !*id))) {
306 - error("requested a CHART, without a type.id, on host '%s'. Disabling it.", host->hostname);
306 + if (likely(host))
307 + error("requested a CHART, without a type.id, on host '%s'. Disabling it.", host->hostname);
308 + else
309 + error("requested a CHART, without a type.id. Disabling it.");
310 ((PARSER_USER_OBJECT *) user)->enabled = 0;
311 return PARSER_RC_ERROR;
312 }
@@ -375,7 +378,7 @@ PARSER_RC pluginsd_dimension(char **words, void *user, PLUGINSD_ACTION *plugins
378
379 RRDSET *st = ((PARSER_USER_OBJECT *) user)->st;
380 RRDHOST *host = ((PARSER_USER_OBJECT *) user)->host;
378 - if (unlikely(!host)) {
381 + if (unlikely(!host && !((PARSER_USER_OBJECT *) user)->host_exists)) {
382 debug(D_PLUGINSD, "Ignoring dimension belonging to missing or ignored host.");
383 return PARSER_RC_OK;
384 }
@@ -387,7 +390,7 @@ PARSER_RC pluginsd_dimension(char **words, void *user, PLUGINSD_ACTION *plugins
390 goto disable;
391 }
392
390 - if (unlikely(!st)) {
393 + if (unlikely(!st && !((PARSER_USER_OBJECT *) user)->st_exists)) {
394 error("requested a DIMENSION, without a CHART, on host '%s'. Disabling it.", host->hostname);
395 goto disable;
396 }
@@ -409,7 +412,7 @@ PARSER_RC pluginsd_dimension(char **words, void *user, PLUGINSD_ACTION *plugins
412 if (unlikely(!algorithm || !*algorithm))
413 algorithm = "absolute";
414
412 - if (unlikely(rrdset_flag_check(st, RRDSET_FLAG_DEBUG)))
415 + if (unlikely(st && rrdset_flag_check(st, RRDSET_FLAG_DEBUG)))
416 debug(
417 D_PLUGINSD,
418 "creating dimension in chart %s, id='%s', name='%s', algorithm='%s', multiplier=%ld, divisor=%ld, hidden='%s'",
collectors/plugins.d/pluginsd_parser.h
+2
@@ -16,6 +16,8 @@ typedef struct parser_user_object {
16 struct label *new_labels;
17 size_t count;
18 int enabled;
19 + uint8_t st_exists;
20 + uint8_t host_exists;
21 void *private; // the user can set this for private use
22 } PARSER_USER_OBJECT;
23
collectors/statsd.plugin/statsd.c
-4
@@ -1464,8 +1464,6 @@ static inline RRDSET *statsd_private_rrdset_create(
1464 , chart_type // chart type
1465 , memory_mode // memory mode
1466 , history // history
1467 - , 0 // not archived
1468 - , NULL // no known UUID
1467 );
1468 rrdset_flag_set(st, RRDSET_FLAG_STORE_FIRST);
1469
@@ -2004,8 +2002,6 @@ static inline void statsd_update_app_chart(STATSD_APP *app, STATSD_APP_CHART *ch
2002 , chart->chart_type // chart type
2003 , app->rrd_memory_mode // memory mode
2004 , app->rrd_history_entries // history
2007 - , 0 // not archived
2008 - , NULL // no known UUID
2005 );
2006
2007 rrdset_flag_set(chart->st, RRDSET_FLAG_STORE_FIRST);
configure.ac
-1
@@ -1549,7 +1549,6 @@ AC_CONFIG_FILES([
1549 database/Makefile
1550 database/engine/Makefile
1551 database/engine/metadata_log/Makefile
1552 - database/engine/global_uuid_map/Makefile
1552 diagrams/Makefile
1553 exporting/Makefile
1554 exporting/graphite/Makefile
daemon/common.h
-4
@@ -73,10 +73,6 @@
73 // netdata agent spawn server
74 #include "spawn/spawn.h"
75
76 -#ifdef ENABLE_DBENGINE
77 -#include "database/engine/global_uuid_map/global_uuid_map.h"
78 -#endif
79 -
76 // the netdata deamon
77 #include "daemon.h"
78 #include "main.h"
daemon/main.c
-10
@@ -60,9 +60,6 @@ void netdata_cleanup_and_exit(int ret) {
60
61 #ifdef ENABLE_HTTPS
62 security_clean_openssl();
63 -#endif
64 -#ifdef ENABLE_DBENGINE
65 - free_global_guid_map();
63 #endif
64 info("EXIT: all done - netdata is now exiting - bye bye...");
65 exit(ret);
@@ -1451,9 +1448,6 @@ int main(int argc, char **argv) {
1448 struct rrdhost_system_info *system_info = calloc(1, sizeof(struct rrdhost_system_info));
1449 get_system_info(system_info);
1450
1454 -#ifdef ENABLE_DBENGINE
1455 - init_global_guid_map();
1456 -#endif
1451 if(rrd_init(netdata_configured_hostname, system_info))
1452 fatal("Cannot initialize localhost instance with name '%s'.", netdata_configured_hostname);
1453
@@ -1471,10 +1465,6 @@ int main(int argc, char **argv) {
1465
1466 // Load host labels
1467 reload_host_labels();
1474 -#ifdef ENABLE_DBENGINE
1475 - if (localhost->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE)
1476 - metalog_commit_update_host(localhost);
1477 -#endif
1468
1469 // ------------------------------------------------------------------------
1470 // spawn the threads
database/engine/Makefile.am
-1
@@ -5,7 +5,6 @@ MAINTAINERCLEANFILES = $(srcdir)/Makefile.in
5
6 SUBDIRS = \
7 metadata_log \
8 - global_uuid_map \
8 $(NULL)
9
10 dist_noinst_DATA = \
database/engine/global_uuid_map/Makefile.am deleted
-8
@@ -1,8 +0,0 @@
1 -# SPDX-License-Identifier: GPL-3.0-or-later
2 -
3 -AUTOMAKE_OPTIONS = subdir-objects
4 -MAINTAINERCLEANFILES = $(srcdir)/Makefile.in
5 -
6 -dist_noinst_DATA = \
7 - README.md \
8 - $(NULL)
database/engine/global_uuid_map/README.md
database/engine/global_uuid_map/global_uuid_map.c deleted
-292
@@ -1,292 +0,0 @@
1 -// SPDX-License-Identifier: GPL-3.0-or-later
2 -
3 -#include "global_uuid_map.h"
4 -
5 -static Pvoid_t JGUID_map = (Pvoid_t) NULL;
6 -static Pvoid_t JGUID_object_map = (Pvoid_t) NULL;
7 -static uv_rwlock_t guid_lock;
8 -static uv_rwlock_t object_lock;
9 -static uv_rwlock_t global_lock;
10 -
11 -
12 -void free_global_guid_map()
13 -{
14 - JudyHSFreeArray(&JGUID_map, PJE0);
15 - JudyHSFreeArray(&JGUID_object_map, PJE0);
16 -}
17 -
18 -static void free_single_uuid(uuid_t *uuid)
19 -{
20 - Pvoid_t *PValue, *PValue1;
21 - char *existing_object;
22 - Word_t size;
23 -
24 - PValue = JudyHSGet(JGUID_map, (void *) uuid, (Word_t) sizeof(uuid_t));
25 - if (likely(PValue)) {
26 - existing_object = *PValue;
27 - GUID_TYPE object_type = existing_object[0];
28 - size = (Word_t)object_type ? (object_type * 16) + 1 : strlen((char *)existing_object + 1) + 2;
29 - PValue1 = JudyHSGet(JGUID_object_map, (void *)existing_object, (Word_t)size);
30 - if (PValue1 && *PValue1) {
31 - freez(*PValue1);
32 - }
33 - JudyHSDel(&JGUID_object_map, (void *)existing_object,
34 - (Word_t)object_type ? (object_type * 16) + 1 : strlen((char *)existing_object + 1) + 2, PJE0);
35 - JudyHSDel(&JGUID_map, (void *)uuid, (Word_t)sizeof(uuid_t), PJE0);
36 - freez(existing_object);
37 - }
38 -}
39 -
40 -void free_uuid(uuid_t *uuid)
41 -{
42 - GUID_TYPE ret;
43 - char object[49];
44 -
45 - ret = find_object_by_guid(uuid, object, sizeof(object));
46 - if (GUID_TYPE_DIMENSION == ret)
47 - free_single_uuid((uuid_t *)(object + 16 + 16));
48 -
49 - if (GUID_TYPE_CHART == ret)
50 - free_single_uuid((uuid_t *)(object + 16));
51 -
52 - free_single_uuid(uuid);
53 - return;
54 -}
55 -
56 -
57 -void dump_object(uuid_t *index, void *object)
58 -{
59 - char uuid_s[36 + 1];
60 - uuid_unparse_lower(*index, uuid_s);
61 - char local_object[3 * 36 + 2 + 1];
62 -
63 - switch (*(char *) object) {
64 - case GUID_TYPE_CHAR:
65 - debug(D_GUIDLOG, "OBJECT GUID %s on [%s]", uuid_s, (char *)object + 1);
66 - break;
67 - case GUID_TYPE_CHART:
68 - uuid_unparse_lower((const unsigned char *)object + 1, local_object);
69 - uuid_unparse_lower((const unsigned char *)object + 17, local_object+37);
70 - local_object[36] = ':';
71 - local_object[74] = '\0';
72 - debug(D_GUIDLOG, "CHART GUID %s on [%s]", uuid_s, local_object);
73 - break;
74 - case GUID_TYPE_DIMENSION:
75 - uuid_unparse_lower((const unsigned char *)object + 1, local_object);
76 - uuid_unparse_lower((const unsigned char *)object + 17, local_object + 37);
77 - uuid_unparse_lower((const unsigned char *)object + 33, local_object + 74);
78 - local_object[36] = ':';
79 - local_object[73] = ':';
80 - local_object[110] = '\0';
81 - debug(D_GUIDLOG, "DIM GUID %s on [%s]", uuid_s, local_object);
82 - break;
83 - default:
84 - debug(D_GUIDLOG, "Unknown object");
85 - }
86 -}
87 -
88 -/* Returns 0 if it successfully stores the uuid-object mapping or if an identical mapping already exists */
89 -static inline int guid_store_nolock(uuid_t *uuid, void *object, GUID_TYPE object_type)
90 -{
91 - char *existing_object;
92 - GUID_TYPE existing_object_type;
93 -
94 - if (unlikely(!object) || uuid == NULL)
95 - return 0;
96 -
97 - Pvoid_t *PValue;
98 -
99 - PValue = JudyHSIns(&JGUID_map, (void *) uuid, (Word_t) sizeof(uuid_t), PJE0);
100 - if (PPJERR == PValue)
101 - fatal("JudyHSIns() fatal error.");
102 - if (*PValue) {
103 - existing_object = *PValue;
104 - existing_object_type = existing_object[0];
105 - if (existing_object_type != object_type)
106 - return 1;
107 - switch (existing_object_type) {
108 - case GUID_TYPE_DIMENSION:
109 - if (memcmp(existing_object, object, 1 + 16 + 16 + 16))
110 - return 1;
111 - break;
112 - case GUID_TYPE_CHART:
113 - if (memcmp(existing_object, object, 1 + 16 + 16))
114 - return 1;
115 - break;
116 - case GUID_TYPE_CHAR:
117 - if (strcmp(existing_object + 1, (char *)object))
118 - return 1;
119 - break;
120 - default:
121 - return 1;
122 - }
123 - freez(existing_object);
124 - }
125 -
126 - *PValue = (Pvoid_t *) object;
127 -
128 - PValue = JudyHSIns(&JGUID_object_map, (void *)object, (Word_t) object_type?(object_type * 16)+1:strlen((char *) object+1)+2, PJE0);
129 - if (PPJERR == PValue)
130 - fatal("JudyHSIns() fatal error.");
131 - if (*PValue == NULL) {
132 - uuid_t *value = (uuid_t *) mallocz(sizeof(uuid_t));
133 - uuid_copy(*value, *uuid);
134 - *PValue = value;
135 - }
136 -
137 -#ifdef NETDATA_INTERNAL_CHECKS
138 - static uint32_t count = 0;
139 - count++;
140 - char uuid_s[36 + 1];
141 - uuid_unparse_lower(*uuid, uuid_s);
142 - debug(D_GUIDLOG,"GUID added item %" PRIu32" [%s] as:", count, uuid_s);
143 - dump_object(uuid, object);
144 -#endif
145 - return 0;
146 -}
147 -
148 -
149 -/*
150 - * Given a GUID, find if an object is stored
151 - * - Optionally return the object
152 - */
153 -
154 -GUID_TYPE find_object_by_guid(uuid_t *uuid, char *object, size_t max_bytes)
155 -{
156 - Pvoid_t *PValue;
157 - GUID_TYPE value_type;
158 -
159 - uv_rwlock_rdlock(&global_lock);
160 - PValue = JudyHSGet(JGUID_map, (void *) uuid, (Word_t) sizeof(uuid_t));
161 - if (unlikely(!PValue)) {
162 - uv_rwlock_rdunlock(&global_lock);
163 - return GUID_TYPE_NOTFOUND;
164 - }
165 -
166 - value_type = *(char *) *PValue;
167 -
168 - if (likely(object && max_bytes)) {
169 - switch (value_type) {
170 - case GUID_TYPE_CHAR:
171 - if (unlikely(max_bytes - 1 < strlen((char *) *PValue+1))) {
172 - uv_rwlock_rdunlock(&global_lock);
173 - return GUID_TYPE_NOSPACE;
174 - }
175 - strncpyz(object, (char *) *PValue+1, max_bytes - 1);
176 - break;
177 - case GUID_TYPE_HOST:
178 - case GUID_TYPE_CHART:
179 - case GUID_TYPE_DIMENSION:
180 - if (unlikely(max_bytes < (size_t) value_type * 16)) {
181 - uv_rwlock_rdunlock(&global_lock);
182 - return GUID_TYPE_NOSPACE;
183 - }
184 - memcpy(object, *PValue+1, value_type * 16);
185 - break;
186 - default:
187 - uv_rwlock_rdunlock(&global_lock);
188 - return GUID_TYPE_NOTFOUND;
189 - }
190 - }
191 -
192 -#ifdef NETDATA_INTERNAL_CHECKS
193 - dump_object(uuid, *PValue);
194 -#endif
195 - uv_rwlock_rdunlock(&global_lock);
196 - return value_type;
197 -}
198 -
199 -/*
200 - * Find a GUID of an object
201 - * - Optionally return the GUID
202 - *
203 - */
204 -
205 -int find_guid_by_object(char *object, uuid_t *uuid, GUID_TYPE object_type)
206 -{
207 - Pvoid_t *PValue;
208 -
209 - uv_rwlock_rdlock(&global_lock);
210 - PValue = JudyHSGet(JGUID_object_map, (void *)object, (Word_t)object_type?object_type*16+1:strlen(object+1)+2);
211 - if (unlikely(!PValue)) {
212 - uv_rwlock_rdunlock(&global_lock);
213 - return 1;
214 - }
215 -
216 - if (likely(uuid))
217 - uuid_copy(*uuid, *PValue);
218 - uv_rwlock_rdunlock(&global_lock);
219 - return 0;
220 -}
221 -
222 -int find_or_generate_guid(void *object, uuid_t *uuid, GUID_TYPE object_type, int replace_instead_of_generate)
223 -{
224 - char *target_object;
225 - uuid_t temp_uuid;
226 - int rc;
227 -
228 - switch (object_type) {
229 - case GUID_TYPE_DIMENSION:
230 - if (unlikely(find_or_generate_guid((void *) ((RRDDIM *)object)->id, &temp_uuid, GUID_TYPE_CHAR, 0)))
231 - return 1;
232 - target_object = mallocz(49);
233 - target_object[0] = object_type;
234 - memcpy(target_object + 1, ((RRDDIM *)object)->rrdset->rrdhost->host_uuid, 16);
235 - memcpy(target_object + 17, ((RRDDIM *)object)->rrdset->chart_uuid, 16);
236 - memcpy(target_object + 33, temp_uuid, 16);
237 - break;
238 - case GUID_TYPE_CHART:
239 - if (unlikely(find_or_generate_guid((void *) ((RRDSET *)object)->id, &temp_uuid, GUID_TYPE_CHAR, 0)))
240 - return 1;
241 - target_object = mallocz(33);
242 - target_object[0] = object_type;
243 - memcpy(target_object + 1, (((RRDSET *)object))->rrdhost->host_uuid, 16);
244 - memcpy(target_object + 17, temp_uuid, 16);
245 - break;
246 - case GUID_TYPE_HOST:
247 - target_object = mallocz(17);
248 - target_object[0] = object_type;
249 - memcpy(target_object + 1, (((RRDHOST *)object))->host_uuid, 16);
250 - break;
251 - case GUID_TYPE_CHAR:
252 - target_object = mallocz(strlen((char *) object)+2);
253 - target_object[0] = object_type;
254 - strcpy(target_object+1, (char *) object);
255 - break;
256 - default:
257 - return 1;
258 - }
259 - rc = find_guid_by_object(target_object, uuid, object_type);
260 - if (rc) {
261 - if (!replace_instead_of_generate) /* else take *uuid as user input */
262 - uuid_generate(*uuid);
263 - uv_rwlock_wrlock(&global_lock);
264 - rc = guid_store_nolock(uuid, target_object, object_type);
265 - uv_rwlock_wrunlock(&global_lock);
266 - if (rc)
267 - freez(target_object);
268 - return rc;
269 - }
270 -#ifdef NETDATA_INTERNAL_CHECKS
271 - dump_object(uuid, target_object);
272 -#endif
273 - freez(target_object);
274 - return 0;
275 -}
276 -
277 -void init_global_guid_map()
278 -{
279 - static int init = 0;
280 -
281 - if (init)
282 - return;
283 -
284 - init = 1;
285 - info("Configuring locking mechanism for global GUID map");
286 - fatal_assert(0 == uv_rwlock_init(&guid_lock));
287 - fatal_assert(0 == uv_rwlock_init(&object_lock));
288 - fatal_assert(0 == uv_rwlock_init(&global_lock));
289 - return;
290 -}
291 -
292 -
database/engine/global_uuid_map/global_uuid_map.h deleted
-25
@@ -1,25 +0,0 @@
1 -// SPDX-License-Identifier: GPL-3.0-or-later
2 -
3 -#ifndef NETDATA_GLOBAL_UUID_MAP_H
4 -#define NETDATA_GLOBAL_UUID_MAP_H
5 -
6 -#include "libnetdata/libnetdata.h"
7 -#include <Judy.h>
8 -#include "../../rrd.h"
9 -
10 -typedef enum guid_type {
11 - GUID_TYPE_CHAR,
12 - GUID_TYPE_HOST,
13 - GUID_TYPE_CHART,
14 - GUID_TYPE_DIMENSION,
15 - GUID_TYPE_NOTFOUND,
16 - GUID_TYPE_NOSPACE
17 -} GUID_TYPE;
18 -
19 -extern GUID_TYPE find_object_by_guid(uuid_t *uuid, char *object, size_t max_bytes);
20 -extern int find_guid_by_object(char *object, uuid_t *uuid, GUID_TYPE);
21 -extern void init_global_guid_map();
22 -extern int find_or_generate_guid(void *object, uuid_t *uuid, GUID_TYPE object_type, int replace_instead_of_generate);
23 -extern void free_uuid(uuid_t *uuid);
24 -extern void free_global_guid_map();
25 -#endif //NETDATA_GLOBAL_UUID_MAP_H
database/engine/metadata_log/compaction.c
-313
@@ -3,319 +3,6 @@
3
4 #include "metadatalog.h"
5
6 -void after_compact_old_records(struct metalog_worker_config* wc)
7 -{
8 - struct metalog_instance *ctx = wc->ctx;
9 - int error;
10 -
11 - mlf_flush_records_buffer(wc, &ctx->compaction_state.records_log, &ctx->compaction_state.new_metadata_logfiles);
12 - uv_run(wc->loop, UV_RUN_DEFAULT);
13 -
14 - error = uv_thread_join(wc->now_compacting_files);
15 - if (error) {
16 - error("uv_thread_join(): %s", uv_strerror(error));
17 - }
18 - freez(wc->now_compacting_files);
19 - /* unfreeze command processing */
20 - wc->now_compacting_files = NULL;
21 -
22 - wc->cleanup_thread_compacting_files = 0;
23 -
24 - /* interrupt event loop */
25 - uv_stop(wc->loop);
26 -
27 - info("Finished metadata log compaction (id:%"PRIu32").", ctx->current_compaction_id);
28 -}
29 -
30 -static void metalog_flush_compaction_records(struct metalog_instance *ctx)
31 -{
32 - struct metalog_cmd cmd;
33 - struct completion compaction_completion;
34 -
35 - init_completion(&compaction_completion);
36 -
37 - cmd.opcode = METALOG_COMPACTION_FLUSH;
38 - cmd.record_io_descr.completion = &compaction_completion;
39 - metalog_enq_cmd(&ctx->worker_config, &cmd);
40 -
41 - wait_for_completion(&compaction_completion);
42 - destroy_completion(&compaction_completion);
43 -}
44 -
45 -/* The caller must have called metalog_flush_compaction_records() before to synchronize and quiesce the event loop. */
46 -static void compaction_test_quota(struct metalog_worker_config *wc)
47 -{
48 - struct metalog_instance *ctx = wc->ctx;
49 - struct logfile_compaction_state *compaction_state;
50 - struct metadata_logfile *oldmetalogfile, *newmetalogfile;
51 - unsigned current_size;
52 - int ret;
53 -
54 - compaction_state = &ctx->compaction_state;
55 - newmetalogfile = compaction_state->new_metadata_logfiles.last;
56 -
57 - oldmetalogfile = ctx->metadata_logfiles.first;
58 -
59 - current_size = newmetalogfile->pos;
60 - if (unlikely(current_size >= MAX_METALOGFILE_SIZE && newmetalogfile->starting_fileno < oldmetalogfile->fileno)) {
61 - /* It's safe to finalize the compacted metadata log file and create a new one since it has already replaced
62 - * an older one. */
63 -
64 - /* Finalize as the immediately previous file than the currently compacted one. */
65 - ret = rename_metadata_logfile(newmetalogfile, 0, newmetalogfile->fileno - 1);
66 - if (ret < 0)
67 - return;
68 -
69 - ret = add_new_metadata_logfile(ctx, &compaction_state->new_metadata_logfiles,
70 - ctx->metadata_logfiles.first->fileno, ctx->metadata_logfiles.first->fileno);
71 -
72 - if (likely(!ret)) {
73 - compaction_state->fileno = ctx->metadata_logfiles.first->fileno;
74 - }
75 - }
76 -}
77 -
78 -
79 -static void compact_record_by_uuid(struct metalog_instance *ctx, uuid_t *uuid)
80 -{
81 - GUID_TYPE ret;
82 - RRDSET *st;
83 - RRDDIM *rd;
84 - BUFFER *buffer;
85 - RRDHOST *host = NULL;
86 -
87 - ret = find_object_by_guid(uuid, NULL, 0);
88 - switch (ret) {
89 - case GUID_TYPE_CHAR:
90 - error_with_guid(uuid, "Ignoring unexpected type GUID_TYPE_CHAR");
91 - break;
92 - case GUID_TYPE_CHART:
93 - st = metalog_get_chart_from_uuid(ctx, uuid);
94 - if (st) {
95 - if (ctx->current_compaction_id > st->rrdhost->compaction_id) {
96 - error("Forcing compaction of HOST %s from CHART %s", st->rrdhost->hostname, st->id);
97 - compact_record_by_uuid(ctx, &st->rrdhost->host_uuid);
98 - }
99 -
100 - if (ctx->current_compaction_id > st->compaction_id) {
101 - st->compaction_id = ctx->current_compaction_id;
102 - buffer = metalog_update_chart_buffer(st, ctx->current_compaction_id);
103 - metalog_commit_record(ctx, buffer, METALOG_COMMIT_CREATION_RECORD, uuid, 1);
104 - } else {
105 - debug(D_METADATALOG, "Chart has already been compacted, ignoring record.");
106 - }
107 - } else {
108 - debug(D_METADATALOG, "Ignoring nonexistent chart metadata record.");
109 - }
110 - break;
111 - case GUID_TYPE_DIMENSION:
112 - rd = metalog_get_dimension_from_uuid(ctx, uuid);
113 - if (rd) {
114 - if (ctx->current_compaction_id > rd->rrdset->rrdhost->compaction_id) {
115 - error("Forcing compaction of HOST %s", rd->rrdset->rrdhost->hostname);
116 - compact_record_by_uuid(ctx, &rd->rrdset->rrdhost->host_uuid);
117 - }
118 - if (ctx->current_compaction_id > rd->rrdset->compaction_id) {
119 - error("Forcing compaction of CHART %s", rd->rrdset->id);
120 - compact_record_by_uuid(ctx, rd->rrdset->chart_uuid);
121 - } else if (ctx->current_compaction_id > rd->state->compaction_id) {
122 - rd->state->compaction_id = ctx->current_compaction_id;
123 - buffer = metalog_update_dimension_buffer(rd);
124 - metalog_commit_record(ctx, buffer, METALOG_COMMIT_CREATION_RECORD, uuid, 1);
125 - } else {
126 - debug(D_METADATALOG, "Dimension has already been compacted, ignoring record.");
127 - }
128 - } else {
129 - debug(D_METADATALOG, "Ignoring nonexistent dimension metadata record.");
130 - }
131 - break;
132 - case GUID_TYPE_HOST:
133 - host = metalog_get_host_from_uuid(ctx, uuid);
134 - if (unlikely(!host))
135 - break;
136 - if (ctx->current_compaction_id > host->compaction_id) {
137 - host->compaction_id = ctx->current_compaction_id;
138 - buffer = metalog_update_host_buffer(host);
139 - metalog_commit_record(ctx, buffer, METALOG_COMMIT_CREATION_RECORD, uuid, 1);
140 - } else {
141 - debug(D_METADATALOG, "Host has already been compacted, ignoring record.");
142 - }
143 - break;
144 - case GUID_TYPE_NOTFOUND:
145 - debug(D_METADATALOG, "Ignoring nonexistent metadata record.");
146 - break;
147 - case GUID_TYPE_NOSPACE:
148 - error_with_guid(uuid, "Not enough space for object retrieval");
149 - break;
150 - default:
151 - error("Unknown return code %u from find_object_by_guid", ret);
152 - break;
153 - }
154 -}
155 -
156 -/* Returns 0 on success. */
157 -static int compact_metadata_logfile_records(struct metalog_instance *ctx, struct metadata_logfile *metalogfile)
158 -{
159 - struct metalog_worker_config* wc = &ctx->worker_config;
160 - struct logfile_compaction_state *compaction_state;
161 - struct metalog_record *record;
162 - struct metalog_record_block *record_block, *prev_record_block;
163 - int ret;
164 - unsigned iterated_records;
165 -#define METADATA_LOG_RECORD_BATCH 128 /* Flush I/O and check sizes whenever this many records have been iterated */
166 -
167 - info("Compacting metadata log file \"%s/"METALOG_PREFIX METALOG_FILE_NUMBER_PRINT_TMPL METALOG_EXTENSION"\".",
168 - ctx->rrdeng_ctx->dbfiles_path, metalogfile->starting_fileno, metalogfile->fileno);
169 -
170 - compaction_state = &ctx->compaction_state;
171 - record_block = prev_record_block = NULL;
172 - iterated_records = 0;
173 - for (record = mlf_record_get_first(metalogfile) ; record != NULL ; record = mlf_record_get_next(metalogfile)) {
174 - if ((record_block = metalogfile->records.iterator.current) != prev_record_block) {
175 - if (prev_record_block) { /* Deallocate iterated record blocks */
176 - rrd_atomic_fetch_add(&ctx->records_nr, -prev_record_block->records_nr);
177 - freez(prev_record_block);
178 - }
179 - prev_record_block = record_block;
180 - }
181 - compact_record_by_uuid(ctx, &record->uuid);
182 - if (0 == ++iterated_records % METADATA_LOG_RECORD_BATCH) {
183 - metalog_flush_compaction_records(ctx);
184 - if (compaction_state->throttle) {
185 - (void)sleep_usec(10000); /* 10 msec throttle compaction */
186 - }
187 - compaction_test_quota(wc);
188 - }
189 - }
190 - if (prev_record_block) { /* Deallocate iterated record blocks */
191 - rrd_atomic_fetch_add(&ctx->records_nr, -prev_record_block->records_nr);
192 - freez(prev_record_block);
193 - }
194 -
195 - info("Compacted metadata log file \"%s/"METALOG_PREFIX METALOG_FILE_NUMBER_PRINT_TMPL METALOG_EXTENSION"\".",
196 - ctx->rrdeng_ctx->dbfiles_path, metalogfile->starting_fileno, metalogfile->fileno);
197 -
198 - metadata_logfile_list_delete(&ctx->metadata_logfiles, metalogfile);
199 - ret = destroy_metadata_logfile(metalogfile);
200 - if (!ret) {
201 - info("Deleted file \"%s/"METALOG_PREFIX METALOG_FILE_NUMBER_PRINT_TMPL METALOG_EXTENSION"\".",
202 - ctx->rrdeng_ctx->dbfiles_path, metalogfile->starting_fileno, metalogfile->fileno);
203 - rrd_atomic_fetch_add(&ctx->disk_space, -metalogfile->pos);
204 - } else {
205 - error("Failed to delete file \"%s/"METALOG_PREFIX METALOG_FILE_NUMBER_PRINT_TMPL METALOG_EXTENSION"\".",
206 - ctx->rrdeng_ctx->dbfiles_path, metalogfile->starting_fileno, metalogfile->fileno);
207 - }
208 - freez(metalogfile);
209 -
210 - return ret;
211 -}
212 -
213 -static void compact_old_records(void *arg)
214 -{
215 - struct metalog_instance *ctx = arg;
216 - struct metalog_worker_config* wc = &ctx->worker_config;
217 - struct logfile_compaction_state *compaction_state;
218 - struct metadata_logfile *metalogfile, *nextmetalogfile, *newmetalogfile;
219 - int ret;
220 -
221 - compaction_state = &ctx->compaction_state;
222 -
223 - nextmetalogfile = NULL;
224 - for (metalogfile = ctx->metadata_logfiles.first ;
225 - metalogfile != compaction_state->last_original_logfile ;
226 - metalogfile = nextmetalogfile) {
227 - nextmetalogfile = metalogfile->next;
228 -
229 - newmetalogfile = compaction_state->new_metadata_logfiles.last;
230 - ret = rename_metadata_logfile(newmetalogfile, newmetalogfile->starting_fileno, metalogfile->fileno);
231 - if (ret < 0) {
232 - error("Failed to rename file \"%s/"METALOG_PREFIX METALOG_FILE_NUMBER_PRINT_TMPL METALOG_EXTENSION"\".",
233 - ctx->rrdeng_ctx->dbfiles_path, newmetalogfile->starting_fileno, newmetalogfile->fileno);
234 - }
235 -
236 - ret = compact_metadata_logfile_records(ctx, metalogfile);
237 - if (ret) {
238 - error("Metadata log compaction failed, cancelling.");
239 - break;
240 - }
241 - }
242 - fatal_assert(nextmetalogfile); /* There are always more than 1 metadata log files during compaction */
243 -
244 - newmetalogfile = compaction_state->new_metadata_logfiles.last;
245 - if (newmetalogfile->starting_fileno != 0) { /* Must rename the last compacted file */
246 - ret = rename_metadata_logfile(newmetalogfile, 0, nextmetalogfile->fileno - 1);
247 - if (ret < 0) {
248 - error("Failed to rename file \"%s/"METALOG_PREFIX METALOG_FILE_NUMBER_PRINT_TMPL METALOG_EXTENSION"\".",
249 - ctx->rrdeng_ctx->dbfiles_path, newmetalogfile->starting_fileno, newmetalogfile->fileno);
250 - }
251 - }
252 - /* Connect the compacted files to the metadata log */
253 - newmetalogfile->next = nextmetalogfile;
254 - ctx->metadata_logfiles.first = compaction_state->new_metadata_logfiles.first;
255 -
256 - wc->cleanup_thread_compacting_files = 1;
257 - /* wake up event loop */
258 - fatal_assert(0 == uv_async_send(&wc->async));
259 -}
260 -
261 -/* Returns 0 on success. */
262 -static int init_compaction_state(struct metalog_instance *ctx)
263 -{
264 - struct metadata_logfile *newmetalogfile;
265 - struct logfile_compaction_state *compaction_state;
266 - int ret;
267 -
268 - compaction_state = &ctx->compaction_state;
269 - compaction_state->new_metadata_logfiles.first = NULL;
270 - compaction_state->new_metadata_logfiles.last = NULL;
271 - compaction_state->starting_fileno = ctx->metadata_logfiles.first->fileno;
272 - compaction_state->fileno = ctx->metadata_logfiles.first->fileno;
273 - compaction_state->last_original_logfile = ctx->metadata_logfiles.last;
274 - compaction_state->throttle = 0;
275 -
276 - ret = add_new_metadata_logfile(ctx, &compaction_state->new_metadata_logfiles, compaction_state->starting_fileno,
277 - compaction_state->fileno);
278 - if (unlikely(ret)) {
279 - error("Cannot create new metadata log files, compaction aborted.");
280 - return ret;
281 - }
282 - newmetalogfile = compaction_state->new_metadata_logfiles.first;
283 - fatal_assert(newmetalogfile == compaction_state->new_metadata_logfiles.last);
284 - init_metadata_record_log(&compaction_state->records_log);
285 -
286 - return 0;
287 -}
288 -
289 -void metalog_do_compaction(struct metalog_worker_config *wc)
290 -{
291 - struct metalog_instance *ctx = wc->ctx;
292 - int error;
293 -
294 - if (wc->now_compacting_files) {
295 - /* already compacting metadata log files */
296 - return;
297 - }
298 - wc->now_compacting_files = mallocz(sizeof(*wc->now_compacting_files));
299 - wc->cleanup_thread_compacting_files = 0;
300 - metalog_try_link_new_metadata_logfile(wc);
301 -
302 - error = init_compaction_state(ctx);
303 - if (unlikely(error)) {
304 - error("Cannot create new metadata log files, compaction aborted.");
305 - return;
306 - }
307 - ++ctx->current_compaction_id; /* Signify a new compaction */
308 -
309 - info("Starting metadata log compaction (id:%"PRIu32").", ctx->current_compaction_id);
310 - error = uv_thread_create(wc->now_compacting_files, compact_old_records, ctx);
311 - if (error) {
312 - error("uv_thread_create(): %s", uv_strerror(error));
313 - freez(wc->now_compacting_files);
314 - wc->now_compacting_files = NULL;
315 - }
316 -
317 -}
318 -
6 /* Return 0 on success. */
7 int compaction_failure_recovery(struct metalog_instance *ctx, struct metadata_logfile **metalogfiles,
8 unsigned *matched_files)
database/engine/metadata_log/compaction.h
-12
@@ -8,19 +8,7 @@
8 #endif
9 #include "../rrdengine.h"
10
11 -struct logfile_compaction_state {
12 - unsigned fileno; /* Starts at 1 */
13 - unsigned starting_fileno; /* 0 for normal files, staring number during compaction */
14 -
15 - struct metadata_record_commit_log records_log;
16 - struct metadata_logfile_list new_metadata_logfiles;
17 - struct metadata_logfile *last_original_logfile; /* Marks the end of compaction */
18 - uint8_t throttle; /* set non-zero to throttle compaction */
19 -};
20 -
11 extern int compaction_failure_recovery(struct metalog_instance *ctx, struct metadata_logfile **metalogfiles,
12 unsigned *matched_files);
23 -extern void metalog_do_compaction(struct metalog_worker_config *wc);
24 -extern void after_compact_old_records(struct metalog_worker_config* wc);
13
14 #endif /* NETDATA_COMPACTION_H */
database/engine/metadata_log/logfile.c
+32 -394
@@ -1,184 +1,8 @@
1 // SPDX-License-Identifier: GPL-3.0-or-later
2 +#include <database/sqlite/sqlite_functions.h>
3 #include "metadatalog.h"
4 #include "metalogpluginsd.h"
5
5 -static void mlf_record_block_insert(struct metadata_logfile *metalogfile, struct metalog_record_block *record_block)
6 -{
7 -
8 - if (likely(NULL != metalogfile->records.last)) {
9 - metalogfile->records.last->next = record_block;
10 - }
11 - if (unlikely(NULL == metalogfile->records.first)) {
12 - metalogfile->records.first = record_block;
13 - }
14 - metalogfile->records.last = record_block;
15 -}
16 -
17 -void mlf_record_insert(struct metadata_logfile *metalogfile, struct metalog_record *record)
18 -{
19 - struct metalog_record_block *record_block;
20 - struct metalog_instance *ctx = metalogfile->ctx;
21 -
22 - record_block = metalogfile->records.last;
23 - if (likely(NULL != record_block && record_block->records_nr < MAX_METALOG_RECORDS_PER_BLOCK)) {
24 - record_block->record_array[record_block->records_nr++] = *record;
25 - } else { /* Create new record block, the last one filled up */
26 - record_block = mallocz(sizeof(*record_block));
27 - record_block->records_nr = 1;
28 - record_block->record_array[0] = *record;
29 - record_block->next = NULL;
30 -
31 - mlf_record_block_insert(metalogfile, record_block);
32 - }
33 - rrd_atomic_fetch_add(&ctx->records_nr, 1);
34 -}
35 -
36 -struct metalog_record *mlf_record_get_first(struct metadata_logfile *metalogfile)
37 -{
38 - struct metalog_records *records = &metalogfile->records;
39 - struct metalog_record_block *record_block = metalogfile->records.first;
40 -
41 - records->iterator.current = record_block;
42 - records->iterator.record_i = 0;
43 -
44 - if (unlikely(NULL == record_block || !record_block->records_nr)) {
45 - error("Cannot iterate empty metadata log file %u-%u.", metalogfile->starting_fileno, metalogfile->fileno);
46 - return NULL;
47 - }
48 -
49 - return &record_block->record_array[0];
50 -}
51 -
52 -/* Must have called mlf_record_get_first before calling this function. */
53 -struct metalog_record *mlf_record_get_next(struct metadata_logfile *metalogfile)
54 -{
55 - struct metalog_records *records = &metalogfile->records;
56 - struct metalog_record_block *record_block = records->iterator.current;
57 -
58 - if (unlikely(NULL == record_block)) {
59 - return NULL;
60 - }
61 - if (++records->iterator.record_i >= record_block->records_nr) {
62 - record_block = record_block->next;
63 - if (unlikely(NULL == record_block || !record_block->records_nr)) {
64 - return NULL;
65 - }
66 - records->iterator.current = record_block;
67 - records->iterator.record_i = 0;
68 - return &record_block->record_array[0];
69 - }
70 - return &record_block->record_array[records->iterator.record_i];
71 -}
72 -
73 -static void flush_records_buffer_cb(uv_fs_t* req)
74 -{
75 - struct generic_io_descriptor *io_descr = req->data;
76 - struct metalog_worker_config *wc = req->loop->data;
77 - struct metalog_instance *ctx = wc->ctx;
78 -
79 - debug(D_METADATALOG, "%s: Metadata log file block was written to disk.", __func__);
80 - if (req->result < 0) {
81 - ++ctx->stats.io_errors;
82 - rrd_stat_atomic_add(&global_io_errors, 1);
83 - error("%s: uv_fs_write: %s", __func__, uv_strerror((int)req->result));
84 - } else {
85 - debug(D_METADATALOG, "%s: Metadata log file block was written to disk.", __func__);
86 - }
87 -
88 - uv_fs_req_cleanup(req);
89 - free(io_descr->buf);
90 - freez(io_descr);
91 -}
92 -
93 -/* Careful to always call this before creating a new metadata log file to finish writing the old one */
94 -void mlf_flush_records_buffer(struct metalog_worker_config *wc, struct metadata_record_commit_log *records_log,
95 - struct metadata_logfile_list *metadata_logfiles)
96 -{
97 - struct metalog_instance *ctx = wc->ctx;
98 - int ret;
99 - struct generic_io_descriptor *io_descr;
100 - unsigned pos, size;
101 - struct metadata_logfile *metalogfile;
102 -
103 - if (unlikely(NULL == records_log->buf || 0 == records_log->buf_pos)) {
104 - return;
105 - }
106 - /* care with outstanding records when switching metadata log files */
107 - metalogfile = metadata_logfiles->last;
108 -
109 - io_descr = mallocz(sizeof(*io_descr));
110 - pos = records_log->buf_pos;
111 - size = pos; /* no need to align the I/O when doing buffered writes */
112 - io_descr->buf = records_log->buf;
113 - io_descr->bytes = size;
114 - io_descr->pos = metalogfile->pos;
115 - io_descr->req.data = io_descr;
116 - io_descr->completion = NULL;
117 -
118 - io_descr->iov = uv_buf_init((void *)io_descr->buf, size);
119 - ret = uv_fs_write(wc->loop, &io_descr->req, metalogfile->file, &io_descr->iov, 1,
120 - metalogfile->pos, flush_records_buffer_cb);
121 - fatal_assert(-1 != ret);
122 - metalogfile->pos += size;
123 - rrd_atomic_fetch_add(&ctx->disk_space, size);
124 - records_log->buf = NULL;
125 - ctx->stats.io_write_bytes += size;
126 - ++ctx->stats.io_write_requests;
127 -}
128 -
129 -void *mlf_get_records_buffer(struct metalog_worker_config *wc, struct metadata_record_commit_log *records_log,
130 - struct metadata_logfile_list *metadata_logfiles, unsigned size)
131 -{
132 - int ret;
133 - unsigned buf_pos = 0, buf_size;
134 -
135 - fatal_assert(size);
136 - if (records_log->buf) {
137 - unsigned remaining;
138 -
139 - buf_pos = records_log->buf_pos;
140 - buf_size = records_log->buf_size;
141 - remaining = buf_size - buf_pos;
142 - if (size > remaining) {
143 - /* we need a new buffer */
144 - mlf_flush_records_buffer(wc, records_log, metadata_logfiles);
145 - }
146 - }
147 - if (NULL == records_log->buf) {
148 - buf_size = ALIGN_BYTES_CEILING(size);
149 - ret = posix_memalign((void *)&records_log->buf, RRDFILE_ALIGNMENT, buf_size);
150 - if (unlikely(ret)) {
151 - fatal("posix_memalign:%s", strerror(ret));
152 - }
153 - buf_pos = records_log->buf_pos = 0;
154 - records_log->buf_size = buf_size;
155 - }
156 - records_log->buf_pos += size;
157 -
158 - return records_log->buf + buf_pos;
159 -}
160 -
161 -
162 -void metadata_logfile_list_insert(struct metadata_logfile_list *metadata_logfiles, struct metadata_logfile *metalogfile)
163 -{
164 - if (likely(NULL != metadata_logfiles->last)) {
165 - metadata_logfiles->last->next = metalogfile;
166 - }
167 - if (unlikely(NULL == metadata_logfiles->first)) {
168 - metadata_logfiles->first = metalogfile;
169 - }
170 - metadata_logfiles->last = metalogfile;
171 -}
172 -
173 -void metadata_logfile_list_delete(struct metadata_logfile_list *metadata_logfiles, struct metadata_logfile *metalogfile)
174 -{
175 - struct metadata_logfile *next;
176 -
177 - next = metalogfile->next;
178 - fatal_assert((NULL != next) && (metadata_logfiles->first == metalogfile) &&
179 - (metadata_logfiles->last != metalogfile));
180 - metadata_logfiles->first = next;
181 -}
6
7 void generate_metadata_logfile_path(struct metadata_logfile *metalogfile, char *str, size_t maxlen)
8 {
@@ -193,14 +17,13 @@ void metadata_logfile_init(struct metadata_logfile *metalogfile, struct metalog_
17 metalogfile->fileno = fileno;
18 metalogfile->file = (uv_file)0;
19 metalogfile->pos = 0;
196 - metalogfile->records.first = metalogfile->records.last = NULL;
20 metalogfile->next = NULL;
21 metalogfile->ctx = ctx;
22 }
23
24 int rename_metadata_logfile(struct metadata_logfile *metalogfile, unsigned new_starting_fileno, unsigned new_fileno)
25 {
203 - struct metalog_instance *ctx = metalogfile->ctx;
26 + //struct metalog_instance *ctx = metalogfile->ctx;
27 uv_fs_t req;
28 int ret;
29 char oldpath[RRDENG_PATH_MAX], newpath[RRDENG_PATH_MAX];
@@ -217,7 +40,7 @@ int rename_metadata_logfile(struct metadata_logfile *metalogfile, unsigned new_s
40 ret = uv_fs_rename(NULL, &req, oldpath, newpath, NULL);
41 if (ret < 0) {
42 error("uv_fs_rename(%s): %s", oldpath, uv_strerror(ret));
220 - ++ctx->stats.fs_errors; /* this is racy, may miss some errors */
43 + //++ctx->stats.fs_errors; /* this is racy, may miss some errors */
44 rrd_stat_atomic_add(&global_fs_errors, 1);
45 /* restore previous values */
46 metalogfile->starting_fileno = backup_starting_fileno;
@@ -228,49 +51,9 @@ int rename_metadata_logfile(struct metadata_logfile *metalogfile, unsigned new_s
51 return ret;
52 }
53
231 -int close_metadata_logfile(struct metadata_logfile *metalogfile)
232 -{
233 - struct metalog_instance *ctx = metalogfile->ctx;
234 - uv_fs_t req;
235 - int ret;
236 - char path[RRDENG_PATH_MAX];
237 -
238 - generate_metadata_logfile_path(metalogfile, path, sizeof(path));
239 -
240 - ret = uv_fs_close(NULL, &req, metalogfile->file, NULL);
241 - if (ret < 0) {
242 - error("uv_fs_close(%s): %s", path, uv_strerror(ret));
243 - ++ctx->stats.fs_errors;
244 - rrd_stat_atomic_add(&global_fs_errors, 1);
245 - }
246 - uv_fs_req_cleanup(&req);
247 -
248 - return ret;
249 -}
250 -
251 -int fsync_metadata_logfile(struct metadata_logfile *metalogfile)
252 -{
253 - struct metalog_instance *ctx = metalogfile->ctx;
254 - uv_fs_t req;
255 - int ret;
256 - char path[RRDENG_PATH_MAX];
257 -
258 - generate_metadata_logfile_path(metalogfile, path, sizeof(path));
259 -
260 - ret = uv_fs_fsync(NULL, &req, metalogfile->file, NULL);
261 - if (ret < 0) {
262 - error("uv_fs_close(%s): %s", path, uv_strerror(ret));
263 - ++ctx->stats.fs_errors;
264 - rrd_stat_atomic_add(&global_fs_errors, 1);
265 - }
266 - uv_fs_req_cleanup(&req);
267 -
268 - return ret;
269 -}
270 -
54 int unlink_metadata_logfile(struct metadata_logfile *metalogfile)
55 {
273 - struct metalog_instance *ctx = metalogfile->ctx;
56 + //struct metalog_instance *ctx = metalogfile->ctx;
57 uv_fs_t req;
58 int ret;
59 char path[RRDENG_PATH_MAX];
@@ -280,7 +63,7 @@ int unlink_metadata_logfile(struct metadata_logfile *metalogfile)
63 ret = uv_fs_unlink(NULL, &req, path, NULL);
64 if (ret < 0) {
65 error("uv_fs_fsunlink(%s): %s", path, uv_strerror(ret));
283 - ++ctx->stats.fs_errors;
66 +// ++ctx->stats.fs_errors;
67 rrd_stat_atomic_add(&global_fs_errors, 1);
68 }
69 uv_fs_req_cleanup(&req);
@@ -288,104 +71,6 @@ int unlink_metadata_logfile(struct metadata_logfile *metalogfile)
71 return ret;
72 }
73
291 -int destroy_metadata_logfile(struct metadata_logfile *metalogfile)
292 -{
293 - struct metalog_instance *ctx = metalogfile->ctx;
294 - uv_fs_t req;
295 - int ret;
296 - char path[RRDENG_PATH_MAX];
297 -
298 - generate_metadata_logfile_path(metalogfile, path, sizeof(path));
299 -
300 - ret = uv_fs_ftruncate(NULL, &req, metalogfile->file, 0, NULL);
301 - if (ret < 0) {
302 - error("uv_fs_ftruncate(%s): %s", path, uv_strerror(ret));
303 - ++ctx->stats.fs_errors;
304 - rrd_stat_atomic_add(&global_fs_errors, 1);
305 - }
306 - uv_fs_req_cleanup(&req);
307 -
308 - ret = uv_fs_close(NULL, &req, metalogfile->file, NULL);
309 - if (ret < 0) {
310 - error("uv_fs_close(%s): %s", path, uv_strerror(ret));
311 - ++ctx->stats.fs_errors;
312 - rrd_stat_atomic_add(&global_fs_errors, 1);
313 - }
314 - uv_fs_req_cleanup(&req);
315 -
316 - ret = uv_fs_unlink(NULL, &req, path, NULL);
317 - if (ret < 0) {
318 - error("uv_fs_fsunlink(%s): %s", path, uv_strerror(ret));
319 - ++ctx->stats.fs_errors;
320 - rrd_stat_atomic_add(&global_fs_errors, 1);
321 - }
322 - uv_fs_req_cleanup(&req);
323 -
324 -// ++ctx->stats.metadata_logfile_deletions;
325 -
326 - return ret;
327 -}
328 -
329 -int create_metadata_logfile(struct metadata_logfile *metalogfile)
330 -{
331 - struct metalog_instance *ctx = metalogfile->ctx;
332 - uv_fs_t req;
333 - uv_file file;
334 - int ret, fd;
335 - struct rrdeng_metalog_sb *superblock;
336 - uv_buf_t iov;
337 - char path[RRDENG_PATH_MAX];
338 -
339 - generate_metadata_logfile_path(metalogfile, path, sizeof(path));
340 - fd = open_file_buffered_io(path, O_CREAT | O_RDWR | O_TRUNC, &file);
341 - if (fd < 0) {
342 - ++ctx->stats.fs_errors;
343 - rrd_stat_atomic_add(&global_fs_errors, 1);
344 - return fd;
345 - }
346 - metalogfile->file = file;
347 -// ++ctx->stats.metadata_logfile_creations;
348 -
349 - ret = posix_memalign((void *)&superblock, RRDFILE_ALIGNMENT, sizeof(*superblock));
350 - if (unlikely(ret)) {
351 - fatal("posix_memalign:%s", strerror(ret));
352 - }
353 - memset(superblock, 0, sizeof(*superblock));
354 - (void) strncpy(superblock->magic_number, RRDENG_METALOG_MAGIC, RRDENG_MAGIC_SZ);
355 - superblock->version = RRDENG_METALOG_VER;
356 -
357 - iov = uv_buf_init((void *)superblock, sizeof(*superblock));
358 -
359 - ret = uv_fs_write(NULL, &req, file, &iov, 1, 0, NULL);
360 - if (ret < 0) {
361 - fatal_assert(req.result < 0);
362 - error("uv_fs_write: %s", uv_strerror(ret));
363 - ++ctx->stats.io_errors;
364 - rrd_stat_atomic_add(&global_io_errors, 1);
365 - }
366 - uv_fs_req_cleanup(&req);
367 -
368 - ret = uv_fs_fsync(NULL, &req, metalogfile->file, NULL);
369 - if (ret < 0) {
370 - error("uv_fs_close(%s): %s", path, uv_strerror(ret));
371 - ++ctx->stats.fs_errors;
372 - rrd_stat_atomic_add(&global_fs_errors, 1);
373 - }
374 - uv_fs_req_cleanup(&req);
375 -
376 - free(superblock);
377 - if (ret < 0) {
378 - destroy_metadata_logfile(metalogfile);
379 - return ret;
380 - }
381 -
382 - metalogfile->pos = sizeof(*superblock);
383 - ctx->stats.io_write_bytes += sizeof(*superblock);
384 - ++ctx->stats.io_write_requests;
385 -
386 - return 0;
387 -}
388 -
74 static int check_metadata_logfile_superblock(uv_file file)
75 {
76 int ret;
@@ -447,13 +132,13 @@ void replay_record(struct metadata_logfile *metalogfile, struct rrdeng_metalog_r
132 /* This function only works with buffered I/O */
133 static inline int metalogfile_read(struct metadata_logfile *metalogfile, void *buf, size_t len, uint64_t offset)
134 {
450 - struct metalog_instance *ctx;
135 +// struct metalog_instance *ctx;
136 uv_file file;
137 uv_buf_t iov;
138 uv_fs_t req;
139 int ret;
140
456 - ctx = metalogfile->ctx;
141 +// ctx = metalogfile->ctx;
142 file = metalogfile->file;
143 iov = uv_buf_init(buf, len);
144 ret = uv_fs_read(NULL, &req, file, &iov, 1, offset, NULL);
@@ -461,14 +146,14 @@ static inline int metalogfile_read(struct metadata_logfile *metalogfile, void *b
146 fatal("uv_fs_read: %s", uv_strerror(ret));
147 }
148 if (req.result < 0) {
464 - ++ctx->stats.io_errors;
149 +// ++ctx->stats.io_errors;
150 rrd_stat_atomic_add(&global_io_errors, 1);
151 error("%s: uv_fs_read - %s - record at offset %"PRIu64"(%u) in metadata logfile %u-%u.", __func__,
152 uv_strerror((int)req.result), offset, (unsigned)len, metalogfile->starting_fileno, metalogfile->fileno);
153 }
154 uv_fs_req_cleanup(&req);
470 - ctx->stats.io_read_bytes += len;
471 - ++ctx->stats.io_read_requests;
155 +// ctx->stats.io_read_bytes += len;
156 +// ++ctx->stats.io_read_requests;
157
158 return ret;
159 }
@@ -561,6 +246,7 @@ static void iterate_records(struct metadata_logfile *metalogfile)
246
247 int load_metadata_logfile(struct metalog_instance *ctx, struct metadata_logfile *metalogfile)
248 {
249 + UNUSED(ctx);
250 uv_fs_t req;
251 uv_file file;
252 int ret, fd, error;
@@ -568,9 +254,12 @@ int load_metadata_logfile(struct metalog_instance *ctx, struct metadata_logfile
254 char path[RRDENG_PATH_MAX];
255
256 generate_metadata_logfile_path(metalogfile, path, sizeof(path));
257 + if (file_is_migrated(path))
258 + return 0;
259 +
260 fd = open_file_buffered_io(path, O_RDWR, &file);
261 if (fd < 0) {
573 - ++ctx->stats.fs_errors;
262 +// ++ctx->stats.fs_errors;
263 rrd_stat_atomic_add(&global_fs_errors, 1);
264 return fd;
265 }
@@ -583,15 +272,16 @@ int load_metadata_logfile(struct metalog_instance *ctx, struct metadata_logfile
272 ret = check_metadata_logfile_superblock(file);
273 if (ret)
274 goto error;
586 - ctx->stats.io_read_bytes += sizeof(struct rrdeng_jf_sb);
587 - ++ctx->stats.io_read_requests;
275 +// ctx->stats.io_read_bytes += sizeof(struct rrdeng_jf_sb);
276 +// ++ctx->stats.io_read_requests;
277
278 metalogfile->file = file;
279 metalogfile->pos = file_size;
280
281 iterate_records(metalogfile);
282
594 - info("Metadata log \"%s\" loaded (size:%"PRIu64").", path, file_size);
283 + info("Metadata log \"%s\" migrated to the database (size:%"PRIu64").", path, file_size);
284 + add_migrated_file(path, file_size);
285 return 0;
286
287 error:
@@ -599,20 +289,13 @@ error:
289 ret = uv_fs_close(NULL, &req, file, NULL);
290 if (ret < 0) {
291 error("uv_fs_close(%s): %s", path, uv_strerror(ret));
602 - ++ctx->stats.fs_errors;
292 +// ++ctx->stats.fs_errors;
293 rrd_stat_atomic_add(&global_fs_errors, 1);
294 }
295 uv_fs_req_cleanup(&req);
296 return error;
297 }
298
609 -void init_metadata_record_log(struct metadata_record_commit_log *records_log)
610 -{
611 - records_log->buf = NULL;
612 - records_log->buf_pos = 0;
613 - records_log->record_id = 1;
614 -}
615 -
299 static int scan_metalog_files_cmp(const void *a, const void *b)
300 {
301 struct metadata_logfile *file1, *file2;
@@ -640,7 +323,7 @@ static int scan_metalog_files(struct metalog_instance *ctx)
323 fatal_assert(req.result < 0);
324 uv_fs_req_cleanup(&req);
325 error("uv_fs_scandir(%s): %s", dbfiles_path, uv_strerror(ret));
643 - ++ctx->stats.fs_errors;
326 +// ++ctx->stats.fs_errors;
327 rrd_stat_atomic_add(&global_fs_errors, 1);
328 return ret;
329 }
@@ -675,7 +358,7 @@ static int scan_metalog_files(struct metalog_instance *ctx)
358 freez(metalogfiles);
359 return UV_EINVAL;
360 }
678 - ctx->last_fileno = metalogfiles[matched_files - 1]->fileno;
361 + //ctx->last_fileno = metalogfiles[matched_files - 1]->fileno;
362
363 struct plugind cd = {
364 .enabled = 1,
@@ -722,24 +405,27 @@ static int scan_metalog_files(struct metalog_instance *ctx)
405
406 for (failed_to_load = 0, i = 0 ; i < matched_files ; ++i) {
407 metalogfile = metalogfiles[i];
408 + db_lock();
409 + db_execute("BEGIN TRANSACTION;");
410 ret = load_metadata_logfile(ctx, metalogfile);
411 if (0 != ret) {
412 error("Deleting invalid metadata log file \"%s/"METALOG_PREFIX METALOG_FILE_NUMBER_PRINT_TMPL
413 METALOG_EXTENSION"\"", dbfiles_path, metalogfile->starting_fileno, metalogfile->fileno);
414 unlink_metadata_logfile(metalogfile);
730 - freez(metalogfile);
415 ++failed_to_load;
732 - continue;
416 + db_execute("ROLLBACK TRANSACTION;");
417 }
734 - metadata_logfile_list_insert(&ctx->metadata_logfiles, metalogfile);
735 - rrd_atomic_fetch_add(&ctx->disk_space, metalogfile->pos);
418 + else
419 + db_execute("COMMIT TRANSACTION;");
420 + db_unlock();
421 + freez(metalogfile);
422 }
423 matched_files -= failed_to_load;
424 debug(D_METADATALOG, "PARSER ended");
425
426 parser_destroy(parser);
427
742 - size_t count = metalog_parser_object.count;
428 + size_t count __maybe_unused = metalog_parser_object.count;
429
430 debug(D_METADATALOG, "Parsing count=%u", (unsigned)count);
431 after_failed_to_parse:
@@ -749,31 +435,6 @@ after_failed_to_parse:
435 return matched_files;
436 }
437
752 -/* Creates a metadata log file */
753 -int add_new_metadata_logfile(struct metalog_instance *ctx, struct metadata_logfile_list *logfile_list,
754 - unsigned starting_fileno, unsigned fileno)
755 -{
756 - struct metadata_logfile *metalogfile;
757 - int ret;
758 - char path[RRDENG_PATH_MAX];
759 -
760 - info("Creating new metadata log file in path %s", ctx->rrdeng_ctx->dbfiles_path);
761 - metalogfile = mallocz(sizeof(*metalogfile));
762 - metadata_logfile_init(metalogfile, ctx, starting_fileno, fileno);
763 - ret = create_metadata_logfile(metalogfile);
764 - if (!ret) {
765 - generate_metadata_logfile_path(metalogfile, path, sizeof(path));
766 - info("Created metadata log file \"%s\".", path);
767 - } else {
768 - freez(metalogfile);
769 - return ret;
770 - }
771 - metadata_logfile_list_insert(logfile_list, metalogfile);
772 - rrd_atomic_fetch_add(&ctx->disk_space, metalogfile->pos);
773 -
774 - return 0;
775 -}
776 -
438 /* Return 0 on success. */
439 int init_metalog_files(struct metalog_instance *ctx)
440 {
@@ -784,32 +445,9 @@ int init_metalog_files(struct metalog_instance *ctx)
445 if (ret < 0) {
446 error("Failed to scan path \"%s\".", dbfiles_path);
447 return ret;
787 - } else if (0 == ret) {
788 - info("Metadata log files not found, creating in path \"%s\".", dbfiles_path);
789 - ret = add_new_metadata_logfile(ctx, &ctx->metadata_logfiles, 0, 1);
790 - if (ret) {
791 - error("Failed to create metadata log file in path \"%s\".", dbfiles_path);
792 - return ret;
793 - }
448 + }/* else if (0 == ret) {
449 ctx->last_fileno = 1;
795 - }
450 + }*/
451
452 return 0;
453 }
799 -
800 -void finalize_metalog_files(struct metalog_instance *ctx)
801 -{
802 - struct metadata_logfile *metalogfile, *next_metalogfile;
803 - struct metalog_record_block *record_block, *next_record_block;
804 -
805 - for (metalogfile = ctx->metadata_logfiles.first ; metalogfile != NULL ; metalogfile = next_metalogfile) {
806 - next_metalogfile = metalogfile->next;
807 -
808 - for (record_block = metalogfile->records.first ; record_block != NULL ; record_block = next_record_block) {
809 - next_record_block = record_block->next;
810 - freez(record_block);
811 - }
812 - close_metadata_logfile(metalogfile);
813 - freez(metalogfile);
814 - }
815 -}
database/engine/metadata_log/logfile.h
-59
@@ -13,34 +13,6 @@ struct metalog_worker_config;
13 #define METALOG_PREFIX "metadatalog-"
14 #define METALOG_EXTENSION ".mlf"
15
16 -#define MAX_METALOGFILE_SIZE (524288LU)
17 -
18 -/* Deletions are ignored during compaction, so only creation UUIDs are stored */
19 -struct metalog_record {
20 - uuid_t uuid;
21 -};
22 -
23 -#define MAX_METALOG_RECORDS_PER_BLOCK (1024LU)
24 -struct metalog_record_block {
25 - uint64_t file_offset;
26 - uint32_t io_size;
27 -
28 - struct metalog_record record_array[MAX_METALOG_RECORDS_PER_BLOCK];
29 - uint16_t records_nr;
30 -
31 - struct metalog_record_block *next;
32 -};
33 -
34 -struct metalog_records {
35 - /* the record block list is sorted based on disk offset */
36 - struct metalog_record_block *first;
37 - struct metalog_record_block *last;
38 - struct {
39 - struct metalog_record_block *current;
40 - uint16_t record_i;
41 - } iterator;
42 -};
43 -
16 /* only one event loop is supported for now */
17 struct metadata_logfile {
18 unsigned fileno; /* Starts at 1 */
@@ -48,7 +20,6 @@ struct metadata_logfile {
20 uv_file file;
21 uint64_t pos;
22 struct metalog_instance *ctx;
51 - struct metalog_records records;
23 struct metadata_logfile *next;
24 };
25
@@ -57,42 +28,12 @@ struct metadata_logfile_list {
28 struct metadata_logfile *last; /* newest */
29 };
30
60 -struct metadata_record_commit_log {
61 - uint64_t record_id;
62 -
63 - /* outstanding record buffer */
64 - void *buf;
65 - unsigned buf_pos;
66 - unsigned buf_size;
67 -};
68 -
69 -extern void mlf_record_insert(struct metadata_logfile *metalogfile, struct metalog_record *record);
70 -extern struct metalog_record *mlf_record_get_first(struct metadata_logfile *metalogfile);
71 -extern struct metalog_record *mlf_record_get_next(struct metadata_logfile *metalogfile);
72 -extern void mlf_flush_records_buffer(struct metalog_worker_config *wc, struct metadata_record_commit_log *records_log,
73 - struct metadata_logfile_list *metadata_logfiles);
74 -extern void *mlf_get_records_buffer(struct metalog_worker_config *wc, struct metadata_record_commit_log *records_log,
75 - struct metadata_logfile_list *metadata_logfiles, unsigned size);
76 -extern void metadata_logfile_list_insert(struct metadata_logfile_list *metadata_logfiles,
77 - struct metadata_logfile *metalogfile);
78 -extern void metadata_logfile_list_delete(struct metadata_logfile_list *metadata_logfiles,
79 - struct metadata_logfile *metalogfile);
31 extern void generate_metadata_logfile_path(struct metadata_logfile *metadatalog, char *str, size_t maxlen);
81 -extern void metadata_logfile_init(struct metadata_logfile *metadatalog, struct metalog_instance *ctx,
82 - unsigned tier, unsigned fileno);
32 extern int rename_metadata_logfile(struct metadata_logfile *metalogfile, unsigned new_starting_fileno,
33 unsigned new_fileno);
85 -extern int close_metadata_logfile(struct metadata_logfile *metadatalog);
86 -extern int fsync_metadata_logfile(struct metadata_logfile *metalogfile);
34 extern int unlink_metadata_logfile(struct metadata_logfile *metalogfile);
88 -extern int destroy_metadata_logfile(struct metadata_logfile *metalogfile);
89 -extern int create_metadata_logfile(struct metadata_logfile *metalogfile);
35 extern int load_metadata_logfile(struct metalog_instance *ctx, struct metadata_logfile *logfile);
91 -extern void init_metadata_record_log(struct metadata_record_commit_log *records_log);
92 -extern int add_new_metadata_logfile(struct metalog_instance *ctx, struct metadata_logfile_list *logfile_list,
93 - unsigned tier, unsigned fileno);
36 extern int init_metalog_files(struct metalog_instance *ctx);
95 -extern void finalize_metalog_files(struct metalog_instance *ctx);
37
38
39 #endif /* NETDATA_LOGFILE_H */
database/engine/metadata_log/metadatalog.c deleted
-427
@@ -1,427 +0,0 @@
1 -// SPDX-License-Identifier: GPL-3.0-or-later
2 -#define NETDATA_RRD_INTERNALS
3 -
4 -#include "metadatalog.h"
5 -
6 -static void sanity_check(void)
7 -{
8 - /* Magic numbers must fit in the super-blocks */
9 - BUILD_BUG_ON(strlen(RRDENG_METALOG_MAGIC) > RRDENG_MAGIC_SZ);
10 -
11 - /* Metadata log file super-block cannot be larger than RRDENG_BLOCK_SIZE */
12 - BUILD_BUG_ON(RRDENG_METALOG_SB_PADDING_SZ < 0);
13 -
14 - /* Object duplication factor cannot be less than 1, or too close to 1 */
15 - BUILD_BUG_ON(MAX_DUPLICATION_PERCENTAGE < 110);
16 -}
17 -
18 -char *get_metalog_statistics(struct metalog_instance *ctx, char *str, size_t size)
19 -{
20 - snprintfz(str, size,
21 - "io_write_bytes: %ld\n"
22 - "io_write_requests: %ld\n"
23 - "io_read_bytes: %ld\n"
24 - "io_read_requests: %ld\n"
25 - "io_write_record_bytes: %ld\n"
26 - "io_write_records: %ld\n"
27 - "io_read_record_bytes: %ld\n"
28 - "io_read_records: %ld\n"
29 - "metadata_logfile_creations: %ld\n"
30 - "metadata_logfile_deletions: %ld\n"
31 - "io_errors: %ld\n"
32 - "fs_errors: %ld\n",
33 - (long)ctx->stats.io_write_bytes,
34 - (long)ctx->stats.io_write_requests,
35 - (long)ctx->stats.io_read_bytes,
36 - (long)ctx->stats.io_read_requests,
37 - (long)ctx->stats.io_write_record_bytes,
38 - (long)ctx->stats.io_write_records,
39 - (long)ctx->stats.io_read_record_bytes,
40 - (long)ctx->stats.io_read_records,
41 - (long)ctx->stats.metadata_logfile_creations,
42 - (long)ctx->stats.metadata_logfile_deletions,
43 - (long)ctx->stats.io_errors,
44 - (long)ctx->stats.fs_errors
45 - );
46 - return str;
47 -}
48 -
49 -/* The buffer must not be empty */
50 -void metalog_commit_record(struct metalog_instance *ctx, BUFFER *buffer, enum metalog_opcode opcode, uuid_t *uuid,
51 - int compacting)
52 -{
53 - struct metalog_cmd cmd;
54 -
55 - fatal_assert(buffer_strlen(buffer));
56 - fatal_assert(opcode == METALOG_COMMIT_CREATION_RECORD || opcode == METALOG_COMMIT_DELETION_RECORD);
57 -
58 - cmd.opcode = opcode;
59 - cmd.record_io_descr.buffer = buffer;
60 - cmd.record_io_descr.compacting = compacting;
61 - if (!uuid)
62 - uuid_clear(cmd.record_io_descr.uuid);
63 - else
64 - uuid_copy(cmd.record_io_descr.uuid, *uuid);
65 - metalog_enq_cmd(&ctx->worker_config, &cmd);
66 -}
67 -
68 -static void commit_record(struct metalog_worker_config* wc, struct metalog_record_io_descr *io_descr, uint8_t type)
69 -{
70 - struct metalog_instance *ctx = wc->ctx;
71 - unsigned payload_length, size_bytes;
72 - void *buf, *mlf_payload;
73 - /* persistent structures */
74 - struct rrdeng_metalog_record_header *mlf_header;
75 - struct rrdeng_metalog_record_trailer *mlf_trailer;
76 - uLong crc;
77 -
78 - payload_length = buffer_strlen(io_descr->buffer);
79 - size_bytes = sizeof(*mlf_header) + payload_length + sizeof(*mlf_trailer);
80 -
81 - if (io_descr->compacting)
82 - buf = mlf_get_records_buffer(wc, &ctx->compaction_state.records_log,
83 - &ctx->compaction_state.new_metadata_logfiles, size_bytes);
84 - else
85 - buf = mlf_get_records_buffer(wc, &ctx->records_log, &ctx->metadata_logfiles, size_bytes);
86 -
87 - mlf_header = buf;
88 - mlf_header->type = type;
89 - mlf_header->header_length = sizeof(*mlf_header);
90 - mlf_header->payload_length = payload_length;
91 -
92 - mlf_payload = buf + sizeof(*mlf_header);
93 - memcpy(mlf_payload, buffer_tostring(io_descr->buffer), payload_length);
94 -
95 - mlf_trailer = buf + sizeof(*mlf_header) + payload_length;
96 - crc = crc32(0L, Z_NULL, 0);
97 - crc = crc32(crc, buf, sizeof(*mlf_header) + payload_length);
98 - crc32set(mlf_trailer->checksum, crc);
99 -
100 - buffer_free(io_descr->buffer);
101 -}
102 -
103 -static void do_commit_record(struct metalog_worker_config* wc, uint8_t type, void *data)
104 -{
105 - struct metalog_record_io_descr *io_descr = (struct metalog_record_io_descr *)data;
106 - switch (type) {
107 - case METALOG_CREATE_OBJECT:
108 - if (!uuid_is_null(io_descr->uuid)) { /* It's a valid object */
109 - struct metalog_record record;
110 -
111 - uuid_copy(record.uuid, io_descr->uuid);
112 - if (io_descr->compacting)
113 - mlf_record_insert(wc->ctx->compaction_state.new_metadata_logfiles.last, &record);
114 - else
115 - mlf_record_insert(wc->ctx->metadata_logfiles.last, &record);
116 - } /* fall through */
117 - case METALOG_DELETE_OBJECT:
118 - commit_record(wc, (struct metalog_record_io_descr *)data, type);
119 - break;
120 - default:
121 - fatal("Unknown metadata log file record type, possible memory corruption.");
122 - break;
123 - }
124 -}
125 -
126 -/* Only creates a new metadata file and links it to the metadata log if the last one is non empty. */
127 -void metalog_try_link_new_metadata_logfile(struct metalog_worker_config *wc)
128 -{
129 - struct metalog_instance *ctx = wc->ctx;
130 - struct metadata_logfile *metalogfile;
131 - int ret;
132 -
133 - metalogfile = ctx->metadata_logfiles.last;
134 - if (metalogfile->records.first) { /* it has records */
135 - /* Finalize metadata log file and create a new one */
136 - mlf_flush_records_buffer(wc, &ctx->records_log, &ctx->metadata_logfiles);
137 - fsync_metadata_logfile(ctx->metadata_logfiles.last);
138 - ret = add_new_metadata_logfile(ctx, &ctx->metadata_logfiles, 0, ctx->last_fileno + 1);
139 - if (likely(!ret)) {
140 - ++ctx->last_fileno;
141 - }
142 - }
143 -}
144 -
145 -void metalog_test_quota(struct metalog_worker_config *wc)
146 -{
147 - struct metalog_instance *ctx = wc->ctx;
148 - struct metadata_logfile *metalogfile;
149 - unsigned current_size;
150 - uint8_t only_one_metalogfile;
151 -
152 - metalogfile = ctx->metadata_logfiles.last;
153 - current_size = metalogfile->pos;
154 - if (unlikely(current_size >= MAX_METALOGFILE_SIZE)) {
155 - metalog_try_link_new_metadata_logfile(wc);
156 - }
157 -
158 - metalogfile = ctx->metadata_logfiles.last;
159 - only_one_metalogfile = (metalogfile == ctx->metadata_logfiles.first) ? 1 : 0;
160 - debug(D_METADATALOG, "records=%lu objects=%lu", (long unsigned)ctx->records_nr,
161 - (long unsigned)ctx->objects_nr);
162 - if (unlikely(!only_one_metalogfile &&
163 - ctx->records_nr > (ctx->objects_nr * (uint64_t)MAX_DUPLICATION_PERCENTAGE) / 100) &&
164 - NO_QUIESCE == ctx->quiesce) {
165 - metalog_do_compaction(wc);
166 - }
167 -}
168 -
169 -static inline int metalog_threads_alive(struct metalog_worker_config* wc)
170 -{
171 - if (wc->cleanup_thread_compacting_files) {
172 - return 1;
173 - }
174 -
175 - return 0;
176 -}
177 -
178 -static void metalog_cleanup_finished_threads(struct metalog_worker_config *wc)
179 -{
180 - struct metalog_instance *ctx = wc->ctx;
181 -
182 - if (unlikely(wc->cleanup_thread_compacting_files)) {
183 - after_compact_old_records(wc);
184 - }
185 - if (unlikely(SET_QUIESCE == ctx->quiesce && !metalog_threads_alive(wc))) {
186 - ctx->quiesce = QUIESCED;
187 - complete(&ctx->metalog_completion);
188 - }
189 -}
190 -
191 -static void metalog_init_cmd_queue(struct metalog_worker_config *wc)
192 -{
193 - wc->cmd_queue.head = wc->cmd_queue.tail = 0;
194 - wc->queue_size = 0;
195 - fatal_assert(0 == uv_cond_init(&wc->cmd_cond));
196 - fatal_assert(0 == uv_mutex_init(&wc->cmd_mutex));
197 -}
198 -
199 -void metalog_enq_cmd(struct metalog_worker_config *wc, struct metalog_cmd *cmd)
200 -{
201 - unsigned queue_size;
202 -
203 - /* wait for free space in queue */
204 - uv_mutex_lock(&wc->cmd_mutex);
205 - while ((queue_size = wc->queue_size) == METALOG_CMD_Q_MAX_SIZE) {
206 - uv_cond_wait(&wc->cmd_cond, &wc->cmd_mutex);
207 - }
208 - fatal_assert(queue_size < METALOG_CMD_Q_MAX_SIZE);
209 - /* enqueue command */
210 - wc->cmd_queue.cmd_array[wc->cmd_queue.tail] = *cmd;
211 - wc->cmd_queue.tail = wc->cmd_queue.tail != METALOG_CMD_Q_MAX_SIZE - 1 ?
212 - wc->cmd_queue.tail + 1 : 0;
213 - wc->queue_size = queue_size + 1;
214 - uv_mutex_unlock(&wc->cmd_mutex);
215 -
216 - /* wake up event loop */
217 - fatal_assert(0 == uv_async_send(&wc->async));
218 -}
219 -
220 -struct metalog_cmd metalog_deq_cmd(struct metalog_worker_config *wc)
221 -{
222 - struct metalog_cmd ret;
223 - unsigned queue_size;
224 -
225 - uv_mutex_lock(&wc->cmd_mutex);
226 - queue_size = wc->queue_size;
227 - if (queue_size == 0) {
228 - ret.opcode = METALOG_NOOP;
229 - } else {
230 - /* dequeue command */
231 - ret = wc->cmd_queue.cmd_array[wc->cmd_queue.head];
232 - if (queue_size == 1) {
233 - wc->cmd_queue.head = wc->cmd_queue.tail = 0;
234 - } else {
235 - wc->cmd_queue.head = wc->cmd_queue.head != RRDENG_CMD_Q_MAX_SIZE - 1 ?
236 - wc->cmd_queue.head + 1 : 0;
237 - }
238 - wc->queue_size = queue_size - 1;
239 -
240 - /* wake up producers */
241 - uv_cond_signal(&wc->cmd_cond);
242 - }
243 - uv_mutex_unlock(&wc->cmd_mutex);
244 -
245 - return ret;
246 -}
247 -
248 -static void async_cb(uv_async_t *handle)
249 -{
250 - uv_stop(handle->loop);
251 - uv_update_time(handle->loop);
252 - debug(D_METADATALOG, "%s called, active=%d.", __func__, uv_is_active((uv_handle_t *)handle));
253 -}
254 -
255 -/* Flushes metadata log when timer expires */
256 -#define TIMER_PERIOD_MS (5000)
257 -
258 -static void timer_cb(uv_timer_t* handle)
259 -{
260 - struct metalog_worker_config* wc = handle->data;
261 - struct metalog_instance *ctx = wc->ctx;
262 -
263 - uv_stop(handle->loop);
264 - uv_update_time(handle->loop);
265 - metalog_test_quota(wc);
266 - debug(D_METADATALOG, "%s: timeout reached.", __func__);
267 -#ifdef NETDATA_INTERNAL_CHECKS
268 - {
269 - char buf[4096];
270 - debug(D_METADATALOG, "%s", get_metalog_statistics(wc->ctx, buf, sizeof(buf)));
271 - }
272 -#endif
273 - mlf_flush_records_buffer(wc, &ctx->records_log, &ctx->metadata_logfiles);
274 -}
275 -
276 -#define MAX_CMD_BATCH_SIZE (256)
277 -
278 -void metalog_worker(void* arg)
279 -{
280 - struct metalog_worker_config *wc = arg;
281 - struct metalog_instance *ctx = wc->ctx;
282 - uv_loop_t* loop;
283 - int shutdown, ret;
284 - enum metalog_opcode opcode;
285 - uv_timer_t timer_req;
286 - struct metalog_cmd cmd;
287 - unsigned cmd_batch_size;
288 -
289 - sanity_check();
290 - metalog_init_cmd_queue(wc);
291 -
292 - loop = wc->loop = mallocz(sizeof(uv_loop_t));
293 - ret = uv_loop_init(loop);
294 - if (ret) {
295 - error("uv_loop_init(): %s", uv_strerror(ret));
296 - goto error_after_loop_init;
297 - }
298 - loop->data = wc;
299 -
300 - ret = uv_async_init(wc->loop, &wc->async, async_cb);
301 - if (ret) {
302 - error("uv_async_init(): %s", uv_strerror(ret));
303 - goto error_after_async_init;
304 - }
305 - wc->async.data = wc;
306 -
307 - wc->now_compacting_files = NULL;
308 - wc->cleanup_thread_compacting_files = 0;
309 -
310 - /* quota check timer */
311 - ret = uv_timer_init(loop, &timer_req);
312 - if (ret) {
313 - error("uv_timer_init(): %s", uv_strerror(ret));
314 - goto error_after_timer_init;
315 - }
316 - timer_req.data = wc;
317 -
318 - wc->error = 0;
319 - /* wake up initialization thread */
320 - complete(&ctx->metalog_completion);
321 -
322 - fatal_assert(0 == uv_timer_start(&timer_req, timer_cb, TIMER_PERIOD_MS, TIMER_PERIOD_MS));
323 - shutdown = 0;
324 - while (likely(shutdown == 0 || metalog_threads_alive(wc))) {
325 - uv_run(loop, UV_RUN_DEFAULT);
326 - metalog_cleanup_finished_threads(wc);
327 -
328 - /* wait for commands */
329 - cmd_batch_size = 0;
330 - do {
331 - /*
332 - * Avoid starving the loop when there are too many commands coming in.
333 - * timer_cb will interrupt the loop again to allow serving more commands.
334 - */
335 - if (unlikely(cmd_batch_size >= MAX_CMD_BATCH_SIZE))
336 - break;
337 -
338 - cmd = metalog_deq_cmd(wc);
339 - opcode = cmd.opcode;
340 - ++cmd_batch_size;
341 -
342 - switch (opcode) {
343 - case METALOG_NOOP:
344 - /* the command queue was empty, do nothing */
345 - break;
346 - case METALOG_SHUTDOWN:
347 - shutdown = 1;
348 - break;
349 - case METALOG_QUIESCE:
350 - ctx->quiesce = SET_QUIESCE;
351 - fatal_assert(0 == uv_timer_stop(&timer_req));
352 - uv_close((uv_handle_t *)&timer_req, NULL);
353 - mlf_flush_records_buffer(wc, &ctx->records_log, &ctx->metadata_logfiles);
354 - if (!metalog_threads_alive(wc)) {
355 - ctx->quiesce = QUIESCED;
356 - complete(&ctx->metalog_completion);
357 - }
358 - break;
359 - case METALOG_COMMIT_CREATION_RECORD:
360 - do_commit_record(wc, METALOG_CREATE_OBJECT, &cmd.record_io_descr);
361 - break;
362 - case METALOG_COMMIT_DELETION_RECORD:
363 - do_commit_record(wc, METALOG_DELETE_OBJECT, &cmd.record_io_descr);
364 - break;
365 - case METALOG_COMPACTION_FLUSH:
366 - mlf_flush_records_buffer(wc, &ctx->compaction_state.records_log,
367 - &ctx->compaction_state.new_metadata_logfiles);
368 - fsync_metadata_logfile(ctx->compaction_state.new_metadata_logfiles.last);
369 - complete(cmd.record_io_descr.completion);
370 - break;
371 - default:
372 - debug(D_METADATALOG, "%s: default.", __func__);
373 - break;
374 - }
375 - } while (opcode != METALOG_NOOP);
376 - }
377 -
378 - /* cleanup operations of the event loop */
379 - info("Shutting down RRD metadata log event loop.");
380 -
381 - /*
382 - * uv_async_send after uv_close does not seem to crash in linux at the moment,
383 - * it is however undocumented behaviour and we need to be aware if this becomes
384 - * an issue in the future.
385 - */
386 - uv_close((uv_handle_t *)&wc->async, NULL);
387 -
388 - mlf_flush_records_buffer(wc, &ctx->records_log, &ctx->metadata_logfiles);
389 - uv_run(loop, UV_RUN_DEFAULT);
390 -
391 - info("Shutting down RRD metadata log loop complete.");
392 - /* TODO: don't let the API block by waiting to enqueue commands */
393 - uv_cond_destroy(&wc->cmd_cond);
394 -/* uv_mutex_destroy(&wc->cmd_mutex); */
395 - fatal_assert(0 == uv_loop_close(loop));
396 - freez(loop);
397 -
398 - return;
399 -
400 -error_after_timer_init:
401 - uv_close((uv_handle_t *)&wc->async, NULL);
402 -error_after_async_init:
403 - fatal_assert(0 == uv_loop_close(loop));
404 -error_after_loop_init:
405 - freez(loop);
406 -
407 - wc->error = UV_EAGAIN;
408 - /* wake up initialization thread */
409 - complete(&ctx->metalog_completion);
410 -}
411 -
412 -void error_with_guid(uuid_t *uuid, char *reason)
413 -{
414 - char uuid_str[37];
415 -
416 - uuid_unparse_lower(*uuid, uuid_str);
417 - errno = 0;
418 - error("%s (GUID = %s)", reason, uuid_str);
419 -}
420 -
421 -void info_with_guid(uuid_t *uuid, char *reason)
422 -{
423 - char uuid_str[37];
424 -
425 - uuid_unparse_lower(*uuid, uuid_str);
426 - info("%s (GUID = %s)", reason, uuid_str);
427 -}
database/engine/metadata_log/metadatalog.h
-111
@@ -16,124 +16,13 @@
16 struct metalog_instance;
17 struct parser_user_object;
18
19 -#define MAX_PAGES_PER_EXTENT (64) /* TODO: can go higher only when journal supports bigger than 4KiB transactions */
20 -
19 #define METALOG_FILE_NUMBER_SCAN_TMPL "%5u-%5u"
20 #define METALOG_FILE_NUMBER_PRINT_TMPL "%5.5u-%5.5u"
21
24 -#define MAX_DUPLICATION_PERCENTAGE 150 /* the maximum duplication factor of objects in metadata log records */
25 -
26 -typedef enum {
27 - METALOG_STATUS_UNINITIALIZED = 0,
28 - METALOG_STATUS_INITIALIZING,
29 - METALOG_STATUS_INITIALIZED
30 -} metalog_state_t;
31 -
32 -struct metalog_record_io_descr {
33 - BUFFER *buffer;
34 - struct completion *completion;
35 - int compacting; /* When 0 append at the end of the metadata log file list.
36 - When 1 append to the temporary compaction metadata log file list. */
37 - uuid_t uuid;
38 -};
39 -
40 -enum metalog_opcode {
41 - /* can be used to return empty status or flush the command queue */
42 - METALOG_NOOP = 0,
43 -
44 - METALOG_SHUTDOWN,
45 - METALOG_COMMIT_CREATION_RECORD,
46 - METALOG_COMMIT_DELETION_RECORD,
47 - METALOG_COMPACTION_FLUSH,
48 - METALOG_QUIESCE,
49 -
50 - METALOG_MAX_OPCODE
51 -};
52 -
53 -struct metalog_cmd {
54 - enum metalog_opcode opcode;
55 - struct metalog_record_io_descr record_io_descr;
56 -};
57 -
58 -#define METALOG_CMD_Q_MAX_SIZE (2048)
59 -
60 -struct metalog_cmdqueue {
61 - unsigned head, tail;
62 - struct metalog_cmd cmd_array[METALOG_CMD_Q_MAX_SIZE];
63 -};
64 -
65 -struct metalog_worker_config {
66 - struct metalog_instance *ctx;
67 -
68 - uv_thread_t thread;
69 - uv_loop_t *loop;
70 - uv_async_t async;
71 -
72 - /* metadata log file comapaction thread */
73 - uv_thread_t *now_compacting_files;
74 - unsigned long cleanup_thread_compacting_files; /* set to 0 when now_compacting_files is still running */
75 -
76 - /* FIFO command queue */
77 - uv_mutex_t cmd_mutex;
78 - uv_cond_t cmd_cond;
79 - volatile unsigned queue_size;
80 - struct metalog_cmdqueue cmd_queue;
81 -
82 - int error;
83 -};
84 -
85 -/*
86 - * Debug statistics not used by code logic.
87 - * They only describe operations since DB engine instance load time.
88 - */
89 -struct metalog_statistics {
90 - rrdeng_stats_t io_write_bytes;
91 - rrdeng_stats_t io_write_requests;
92 - rrdeng_stats_t io_read_bytes;
93 - rrdeng_stats_t io_read_requests;
94 - rrdeng_stats_t io_write_record_bytes;
95 - rrdeng_stats_t io_write_records;
96 - rrdeng_stats_t io_read_record_bytes;
97 - rrdeng_stats_t io_read_records;
98 - rrdeng_stats_t metadata_logfile_creations;
99 - rrdeng_stats_t metadata_logfile_deletions;
100 - rrdeng_stats_t io_errors;
101 - rrdeng_stats_t fs_errors;
102 -};
103 -
22 struct metalog_instance {
23 struct rrdengine_instance *rrdeng_ctx;
106 - struct metalog_worker_config worker_config;
107 - struct completion metalog_completion;
108 - struct metadata_record_commit_log records_log;
109 - struct metadata_logfile_list metadata_logfiles;
24 struct parser_user_object *metalog_parser_object;
111 - struct logfile_compaction_state compaction_state;
112 - uint32_t current_compaction_id; /* Every compaction run increments this by 1 */
113 - unsigned long disk_space;
114 - unsigned long records_nr;
115 - unsigned long objects_nr; /* total objects (hosts, charts, dimensions) monitored in this context */
25 uint8_t initialized; /* set to 1 to mark context initialized */
117 - unsigned last_fileno; /* newest index of metadata log file */
118 -
119 - uint8_t quiesce; /*
120 - * 0 initial state when all operations function normally
121 - * 1 set it before shutting down the instance, quiesce long running operations
122 - * 2 is set after all threads have finished running
123 - */
124 -
125 - struct metalog_statistics stats;
26 };
27
128 -extern void metalog_commit_record(struct metalog_instance *ctx, BUFFER *buffer, enum metalog_opcode opcode,
129 - uuid_t *uuid, int compacting);
130 - extern int init_metadata_logfiles(struct metalog_instance *ctx);
131 -extern void finalize_metadata_logfiles(struct metalog_instance *ctx);
132 -extern void metalog_try_link_new_metadata_logfile(struct metalog_worker_config *wc);
133 -extern void metalog_test_quota(struct metalog_worker_config *wc);
134 -extern void metalog_worker(void* arg);
135 -extern void metalog_enq_cmd(struct metalog_worker_config *wc, struct metalog_cmd *cmd);
136 -extern struct metalog_cmd metalog_deq_cmd(struct metalog_worker_config *wc);
137 -extern void error_with_guid(uuid_t *uuid, char *reason);
138 -extern void info_with_guid(uuid_t *uuid, char *reason);
28 #endif /* NETDATA_METADATALOG_H */
database/engine/metadata_log/metadatalogapi.c
+6 -509
@@ -3,461 +3,6 @@
3
4 #include "metadatalog.h"
5
6 -static inline struct metalog_instance *get_metalog_ctx(RRDHOST *host)
7 -{
8 - if (host->rrdeng_ctx)
9 - return host->rrdeng_ctx->metalog_ctx;
10 -
11 - return NULL;
12 -}
13 -
14 -static inline int metalog_is_initialized(struct metalog_instance *ctx)
15 -{
16 - return ctx->rrdeng_ctx->metalog_ctx != NULL;
17 -}
18 -
19 -static inline void metalog_commit_creation_record(struct metalog_instance *ctx, BUFFER *buffer, uuid_t *uuid)
20 -{
21 - metalog_commit_record(ctx, buffer, METALOG_COMMIT_CREATION_RECORD, uuid, 0);
22 -}
23 -
24 -static inline void metalog_commit_deletion_record(struct metalog_instance *ctx, BUFFER *buffer)
25 -{
26 - metalog_commit_record(ctx, buffer, METALOG_COMMIT_DELETION_RECORD, NULL, 0);
27 -}
28 -
29 -void metalog_upd_objcount(RRDHOST *host, int count)
30 -{
31 - struct metalog_instance *ctx = get_metalog_ctx(host);
32 -
33 - if (unlikely(!ctx))
34 - return;
35 -
36 - rrd_atomic_fetch_add(&ctx->objects_nr, count);
37 -}
38 -
39 -BUFFER *metalog_update_host_buffer(RRDHOST *host)
40 -{
41 - BUFFER *buffer;
42 - buffer = buffer_create(4096); /* This will be freed after it has been committed to the metadata log buffer */
43 -
44 - rrdhost_rdlock(host);
45 -
46 - buffer_sprintf(buffer,
47 - "HOST \"%s\" \"%s\" \"%s\" %d \"%s\" \"%s\" \"%s\"\n",
48 -// "\"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\"" /* system */
49 -// "\"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\"", /* info */
50 - host->machine_guid,
51 - host->hostname,
52 - host->registry_hostname,
53 - default_rrd_update_every,
54 - host->os,
55 - host->timezone,
56 - (host->tags) ? host->tags : "");
57 -
58 - netdata_rwlock_rdlock(&host->labels_rwlock);
59 - struct label *labels = host->labels;
60 - while (labels) {
61 - buffer_sprintf(buffer
62 - , "LABEL \"%s\" = %d %s\n"
63 - , labels->key
64 - , (int)labels->label_source
65 - , labels->value);
66 -
67 - labels = labels->next;
68 - }
69 - netdata_rwlock_unlock(&host->labels_rwlock);
70 -
71 - buffer_strcat(buffer, "OVERWRITE labels\n");
72 -
73 - rrdhost_unlock(host);
74 - return buffer;
75 -}
76 -
77 -void metalog_commit_update_host(RRDHOST *host)
78 -{
79 - struct metalog_instance *ctx;
80 - BUFFER *buffer;
81 -
82 - /* Metadata are only available with dbengine */
83 - ctx = get_metalog_ctx(host);
84 - if (!ctx)
85 - return;
86 - if (!ctx->initialized) /* metadata log has not been initialized yet */
87 - return;
88 -
89 - buffer = metalog_update_host_buffer(host);
90 -
91 - metalog_commit_creation_record(ctx, buffer, &host->host_uuid);
92 -}
93 -
94 -/* compaction_id 0 means it was not called by compaction logic */
95 -BUFFER *metalog_update_chart_buffer(RRDSET *st, uint32_t compaction_id)
96 -{
97 - BUFFER *buffer;
98 - RRDHOST *host = st->rrdhost;
99 -
100 - buffer = buffer_create(1024); /* This will be freed after it has been committed to the metadata log buffer */
101 -
102 - rrdset_rdlock(st);
103 -
104 - buffer_sprintf(buffer, "CONTEXT %s\n", host->machine_guid);
105 -
106 - char uuid_str[37];
107 - uuid_unparse_lower(*st->chart_uuid, uuid_str);
108 - buffer_sprintf(buffer, "GUID %s\n", uuid_str);
109 -
110 - // properly set the name for the remote end to parse it
111 - char *name = "";
112 - if(likely(st->name)) {
113 - if(unlikely(strcmp(st->id, st->name))) {
114 - // they differ
115 - name = strchr(st->name, '.');
116 - if(name)
117 - name++;
118 - else
119 - name = "";
120 - }
121 - }
122 -
123 - // send the chart
124 - buffer_sprintf(
125 - buffer
126 - , "CHART \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" \"%s\" %ld %d \"%s %s %s %s\" \"%s\" \"%s\"\n"
127 - , st->id
128 - , name
129 - , st->title
130 - , st->units
131 - , st->family
132 - , st->context
133 - , rrdset_type_name(st->chart_type)
134 - , st->priority
135 - , st->update_every
136 - , "" /* archived charts cannot be obsolete */
137 - , rrdset_flag_check(st, RRDSET_FLAG_DETAIL)?"detail":""
138 - , rrdset_flag_check(st, RRDSET_FLAG_STORE_FIRST)?"store_first":""
139 - , rrdset_flag_check(st, RRDSET_FLAG_HIDDEN)?"hidden":""
140 - , (st->plugin_name)?st->plugin_name:""
141 - , (st->module_name)?st->module_name:""
142 - );
143 -
144 - // send the dimensions
145 - RRDDIM *rd;
146 - rrddim_foreach_read(rd, st) {
147 - char uuid_str[37];
148 -
149 - uuid_unparse_lower(*rd->state->metric_uuid, uuid_str);
150 - buffer_sprintf(buffer, "GUID %s\n", uuid_str);
151 -
152 - buffer_sprintf(
153 - buffer
154 - , "DIMENSION \"%s\" \"%s\" \"%s\" " COLLECTED_NUMBER_FORMAT " " COLLECTED_NUMBER_FORMAT " \"%s %s %s\"\n"
155 - , rd->id
156 - , rd->name
157 - , rrd_algorithm_name(rd->algorithm)
158 - , rd->multiplier
159 - , rd->divisor
160 - , "" /* archived dimensions cannot be obsolete */
161 - , rrddim_flag_check(rd, RRDDIM_FLAG_HIDDEN)?"hidden":""
162 - , rrddim_flag_check(rd, RRDDIM_FLAG_DONT_DETECT_RESETS_OR_OVERFLOWS)?"noreset":""
163 - );
164 - if (compaction_id && compaction_id > rd->state->compaction_id) {
165 - /* No need to use this dimension again during this compaction cycle */
166 - rd->state->compaction_id = compaction_id;
167 - }
168 - }
169 - rrdset_unlock(st);
170 - return buffer;
171 -}
172 -
173 -void metalog_commit_update_chart(RRDSET *st)
174 -{
175 - struct metalog_instance *ctx;
176 - BUFFER *buffer;
177 -
178 - /* Metadata are only available with dbengine */
179 - if (RRD_MEMORY_MODE_DBENGINE != st->rrd_memory_mode)
180 - return;
181 -
182 - ctx = get_metalog_ctx(st->rrdhost);
183 - if (!ctx)
184 - return;
185 - if (!ctx->initialized) /* metadata log has not been initialized yet */
186 - return;
187 -
188 - buffer = metalog_update_chart_buffer(st, 0);
189 -
190 - metalog_commit_creation_record(ctx, buffer, st->chart_uuid);
191 -}
192 -
193 -void metalog_commit_delete_chart(RRDSET *st)
194 -{
195 - struct metalog_instance *ctx;
196 - BUFFER *buffer;
197 - char uuid_str[37];
198 -
199 - /* Metadata are only available with dbengine */
200 - if (RRD_MEMORY_MODE_DBENGINE != st->rrd_memory_mode)
201 - return;
202 -
203 - ctx = get_metalog_ctx(st->rrdhost);
204 - if (!ctx)
205 - return;
206 - if (!ctx->initialized) /* metadata log has not been initialized yet */
207 - return;
208 - buffer = buffer_create(64); /* This will be freed after it has been committed to the metadata log buffer */
209 -
210 - uuid_unparse_lower(*st->chart_uuid, uuid_str);
211 - buffer_sprintf(buffer, "TOMBSTONE %s\n", uuid_str);
212 -
213 - metalog_commit_deletion_record(ctx, buffer);
214 -}
215 -
216 -BUFFER *metalog_update_dimension_buffer(RRDDIM *rd)
217 -{
218 - BUFFER *buffer;
219 - RRDSET *st = rd->rrdset;
220 - char uuid_str[37];
221 -
222 - buffer = buffer_create(128); /* This will be freed after it has been committed to the metadata log buffer */
223 -
224 - uuid_unparse_lower(*st->chart_uuid, uuid_str);
225 - buffer_sprintf(buffer, "CONTEXT %s\n", uuid_str);
226 - // Activate random GUID
227 - uuid_unparse_lower(*rd->state->metric_uuid, uuid_str);
228 - buffer_sprintf(buffer, "GUID %s\n", uuid_str);
229 -
230 - buffer_sprintf(
231 - buffer
232 - , "DIMENSION \"%s\" \"%s\" \"%s\" " COLLECTED_NUMBER_FORMAT " " COLLECTED_NUMBER_FORMAT " \"%s %s %s\"\n"
233 - , rd->id
234 - , rd->name
235 - , rrd_algorithm_name(rd->algorithm)
236 - , rd->multiplier
237 - , rd->divisor
238 - , "" /* archived dimensions cannot be obsolete */
239 - , rrddim_flag_check(rd, RRDDIM_FLAG_HIDDEN)?"hidden":""
240 - , rrddim_flag_check(rd, RRDDIM_FLAG_DONT_DETECT_RESETS_OR_OVERFLOWS)?"noreset":""
241 - );
242 - return buffer;
243 -}
244 -
245 -void metalog_commit_update_dimension(RRDDIM *rd)
246 -{
247 - struct metalog_instance *ctx;
248 - BUFFER *buffer;
249 - RRDSET *st = rd->rrdset;
250 -
251 - /* Metadata are only available with dbengine */
252 - if (RRD_MEMORY_MODE_DBENGINE != st->rrd_memory_mode)
253 - return;
254 -
255 - ctx = get_metalog_ctx(st->rrdhost);
256 - if (!ctx)
257 - return;
258 - if (!ctx->initialized) /* metadata log has not been initialized yet */
259 - return;
260 -
261 - buffer = metalog_update_dimension_buffer(rd);
262 -
263 - metalog_commit_creation_record(ctx, buffer, rd->state->metric_uuid);
264 -}
265 -
266 -void metalog_commit_delete_dimension(RRDDIM *rd)
267 -{
268 - struct metalog_instance *ctx;
269 - BUFFER *buffer;
270 - RRDSET *st = rd->rrdset;
271 - char uuid_str[37];
272 -
273 - /* Metadata are only available with dbengine */
274 - if (RRD_MEMORY_MODE_DBENGINE != st->rrd_memory_mode)
275 - return;
276 -
277 - ctx = get_metalog_ctx(st->rrdhost);
278 - if (!ctx)
279 - return;
280 - if (!ctx->initialized) /* metadata log has not been initialized yet */
281 - return;
282 - buffer = buffer_create(64); /* This will be freed after it has been committed to the metadata log buffer */
283 -
284 - uuid_unparse_lower(*rd->state->metric_uuid, uuid_str);
285 - buffer_sprintf(buffer, "TOMBSTONE %s\n", uuid_str);
286 -
287 - metalog_commit_deletion_record(ctx, buffer);
288 -}
289 -
290 -RRDHOST *metalog_get_host_from_uuid(struct metalog_instance *ctx, uuid_t *host_guid)
291 -{
292 - UNUSED(ctx);
293 - GUID_TYPE ret;
294 - char machine_guid[37];
295 -
296 - uuid_unparse_lower(*host_guid, machine_guid);
297 - RRDHOST *host = rrdhost_find_by_guid(machine_guid, 0);
298 - ret = find_object_by_guid(host_guid, NULL, 0);
299 - if (unlikely(GUID_TYPE_HOST != ret)) {
300 - errno = 0;
301 - if (unlikely(!host))
302 - error("Host with GUID %s not found in the global map or in the list of hosts", machine_guid);
303 - else
304 - error("Host with GUID %s not found in the global map", machine_guid);
305 - }
306 - return host;
307 -}
308 -
309 -RRDSET *metalog_get_chart_from_uuid(struct metalog_instance *ctx, uuid_t *chart_uuid)
310 -{
311 - GUID_TYPE ret;
312 - char chart_object[33], chart_fullid[RRD_ID_LENGTH_MAX + 1];
313 - uuid_t *machine_guid, *chart_char_guid;
314 -
315 - ret = find_object_by_guid(chart_uuid, chart_object, 33);
316 - if (unlikely(GUID_TYPE_CHART != ret))
317 - return NULL;
318 -
319 - machine_guid = (uuid_t *)chart_object;
320 - RRDHOST *host = metalog_get_host_from_uuid(ctx, machine_guid);
321 - if (unlikely(!host))
322 - return NULL;
323 - if (unlikely(uuid_compare(host->host_uuid, *machine_guid))) {
324 - errno = 0;
325 - error("Metadata host machine GUID does not match the one assosiated with the chart");
326 - return NULL;
327 - }
328 -
329 - chart_char_guid = (uuid_t *)(chart_object + 16);
330 -
331 - ret = find_object_by_guid(chart_char_guid, chart_fullid, RRD_ID_LENGTH_MAX + 1);
332 - if (unlikely(GUID_TYPE_CHAR != ret))
333 - return NULL;
334 - RRDSET *st = rrdset_find(host, chart_fullid);
335 -
336 - return st;
337 -}
338 -
339 -RRDDIM *metalog_get_dimension_from_uuid(struct metalog_instance *ctx, uuid_t *metric_uuid)
340 -{
341 - UNUSED(ctx);
342 -
343 - GUID_TYPE ret;
344 - char dim_object[49], chart_object[33], id_str[PLUGINSD_LINE_MAX], chart_fullid[RRD_ID_LENGTH_MAX + 1];
345 - uuid_t *machine_guid, *chart_guid, *chart_char_guid, *dim_char_guid;
346 -
347 - ret = find_object_by_guid(metric_uuid, dim_object, sizeof(dim_object));
348 - if (GUID_TYPE_DIMENSION != ret) /* not found */
349 - return NULL;
350 -
351 - machine_guid = (uuid_t *)dim_object;
352 -
353 - RRDHOST *host = metalog_get_host_from_uuid(ctx, machine_guid);
354 - if (unlikely(!host))
355 - return NULL;
356 - if (unlikely(uuid_compare(host->host_uuid, *machine_guid))) {
357 - errno = 0;
358 - error("Metadata host machine GUID does not match the one assosiated with the dimension");
359 - return NULL;
360 - }
361 -
362 - chart_guid = (uuid_t *)(dim_object + 16);
363 - dim_char_guid = (uuid_t *)(dim_object + 16 + 16);
364 -
365 - ret = find_object_by_guid(dim_char_guid, id_str, sizeof(id_str));
366 - if (unlikely(GUID_TYPE_CHAR != ret))
367 - return NULL;
368 -
369 - ret = find_object_by_guid(chart_guid, chart_object, sizeof(chart_object));
370 - if (unlikely(GUID_TYPE_CHART != ret))
371 - return NULL;
372 - chart_char_guid = (uuid_t *)(chart_object + 16);
373 -
374 - ret = find_object_by_guid(chart_char_guid, chart_fullid, RRD_ID_LENGTH_MAX + 1);
375 - if (unlikely(GUID_TYPE_CHAR != ret))
376 - return NULL;
377 - RRDSET *st = rrdset_find(host, chart_fullid);
378 - if (!st)
379 - return NULL;
380 -
381 - RRDDIM *rd = rrddim_find(st, id_str);
382 -
383 - return rd;
384 -}
385 -
386 -/* This function is called by dbengine rotation logic when the metric has no writers */
387 -void metalog_delete_dimension_by_uuid(struct metalog_instance *ctx, uuid_t *metric_uuid)
388 -{
389 - RRDDIM *rd;
390 - RRDSET *st;
391 - RRDHOST *host;
392 - uint8_t empty_chart;
393 -
394 - rd = metalog_get_dimension_from_uuid(ctx, metric_uuid);
395 - if (!rd) { /* in the case of legacy UUID convert to multihost and try again */
396 - uuid_t multihost_uuid;
397 -
398 - rrdeng_convert_legacy_uuid_to_multihost(ctx->rrdeng_ctx->machine_guid, metric_uuid, &multihost_uuid);
399 - rd = metalog_get_dimension_from_uuid(ctx, &multihost_uuid);
400 - }
401 - if(!rd) {
402 - info("Rotated unknown archived metric.");
403 - return;
404 - }
405 - st = rd->rrdset;
406 - host = st->rrdhost;
407 -
408 - /* In case there are active metrics in a different database engine do not delete the dimension object */
409 - if (unlikely(host->rrd_memory_mode != RRD_MEMORY_MODE_DBENGINE))
410 - return;
411 -
412 - /* Since the metric has no writer it will not be commited to the metadata log by rrddim_free_custom().
413 - * It must be commited explicitly before calling rrddim_free_custom(). */
414 - metalog_commit_delete_dimension(rd);
415 -
416 - rrdset_wrlock(st);
417 - rrddim_free_custom(st, rd, 1);
418 - empty_chart = (NULL == st->dimensions);
419 - rrdset_unlock(st);
420 -
421 - if (empty_chart) {
422 - rrdhost_wrlock(host);
423 - rrdset_rdlock(st);
424 - rrdset_delete_custom(st, 1);
425 - rrdset_unlock(st);
426 - rrdset_free(st);
427 - rrdhost_unlock(host);
428 - }
429 -}
430 -
431 -void metalog_print_dimension_by_uuid(struct metalog_instance *ctx, uuid_t *metric_uuid)
432 -{
433 - RRDDIM *rd;
434 - RRDSET *st;
435 - RRDHOST *host;
436 -
437 - if (!ctx || !ctx->initialized)
438 - return;
439 -
440 - rd = metalog_get_dimension_from_uuid(ctx, metric_uuid);
441 - if (!rd) { /* in the case of legacy UUID convert to multihost and try again */
442 - uuid_t multihost_uuid;
443 -
444 - rrdeng_convert_legacy_uuid_to_multihost(ctx->rrdeng_ctx->machine_guid, metric_uuid, &multihost_uuid);
445 - rd = metalog_get_dimension_from_uuid(ctx, &multihost_uuid);
446 - }
447 - if(!rd) {
448 - error_with_guid(metric_uuid, "GUID not found, unknown metric.");
449 - return;
450 - }
451 - st = rd->rrdset;
452 - host = st->rrdhost;
453 -
454 - error_with_guid(metric_uuid, "Host - Chart - Dimension are the below:");
455 - error("%s %s %s.", host->hostname, st->id, rd->id);
456 -
457 - if (unlikely(host->rrd_memory_mode != RRD_MEMORY_MODE_DBENGINE))
458 - error_with_guid(metric_uuid, "UUID does not belong to RRD_MEMORY_MODE_DBENGINE.");
459 -}
460 -
6 /*
7 * Returns 0 on success, negative on error
8 */
@@ -467,76 +12,28 @@ int metalog_init(struct rrdengine_instance *rrdeng_parent_ctx)
12 int error;
13
14 ctx = callocz(1, sizeof(*ctx));
470 - ctx->records_nr = 0;
471 - ctx->objects_nr = 0;
472 - ctx->current_compaction_id = 0;
473 - ctx->quiesce = NO_QUIESCE;
15 ctx->initialized = 0;
16 rrdeng_parent_ctx->metalog_ctx = ctx;
17
477 - memset(&ctx->worker_config, 0, sizeof(ctx->worker_config));
18 ctx->rrdeng_ctx = rrdeng_parent_ctx;
479 - ctx->worker_config.ctx = ctx;
480 - init_metadata_record_log(&ctx->records_log);
19 error = init_metalog_files(ctx);
20 if (error) {
21 goto error_after_init_rrd_files;
22 }
485 -
486 - init_completion(&ctx->metalog_completion);
487 - fatal_assert(0 == uv_thread_create(&ctx->worker_config.thread, metalog_worker, &ctx->worker_config));
488 - /* wait for worker thread to initialize */
489 - wait_for_completion(&ctx->metalog_completion);
490 - destroy_completion(&ctx->metalog_completion);
491 - uv_thread_set_name_np(ctx->worker_config.thread, "METALOG");
492 - if (ctx->worker_config.error) {
493 - goto error_after_rrdeng_worker;
494 - }
23 ctx->initialized = 1; /* notify dbengine that the metadata log has finished initializing */
24 return 0;
25
498 -error_after_rrdeng_worker:
499 - finalize_metalog_files(ctx);
26 error_after_init_rrd_files:
27 freez(ctx);
28 return UV_EIO;
29 }
30
505 -/*
506 - * Returns 0 on success, 1 on error
507 - */
508 -int metalog_exit(struct metalog_instance *ctx)
509 -{
510 - struct metalog_cmd cmd;
511 -
512 - if (NULL == ctx) {
513 - return 1;
514 - }
515 -
516 - cmd.opcode = METALOG_SHUTDOWN;
517 - metalog_enq_cmd(&ctx->worker_config, &cmd);
518 -
519 - fatal_assert(0 == uv_thread_join(&ctx->worker_config.thread));
520 -
521 - finalize_metalog_files(ctx);
522 - freez(ctx);
523 -
524 - return 0;
525 -}
526 -
527 -void metalog_prepare_exit(struct metalog_instance *ctx)
31 +/* This function is called by dbengine rotation logic when the metric has no writers */
32 +void metalog_delete_dimension_by_uuid(struct metalog_instance *ctx, uuid_t *metric_uuid)
33 {
529 - struct metalog_cmd cmd;
530 -
531 - if (NULL == ctx) {
532 - return;
533 - }
534 -
535 - init_completion(&ctx->metalog_completion);
536 - cmd.opcode = METALOG_QUIESCE;
537 - metalog_enq_cmd(&ctx->worker_config, &cmd);
34 + uuid_t multihost_uuid;
35
539 - /* wait for metadata log to quiesce */
540 - wait_for_completion(&ctx->metalog_completion);
541 - destroy_completion(&ctx->metalog_completion);
36 + delete_dimension_uuid(metric_uuid);
37 + rrdeng_convert_legacy_uuid_to_multihost(ctx->rrdeng_ctx->machine_guid, metric_uuid, &multihost_uuid);
38 + delete_dimension_uuid(&multihost_uuid);
39 }
database/engine/metadata_log/metadatalogapi.h
-17
@@ -3,27 +3,10 @@
3 #ifndef NETDATA_METADATALOGAPI_H
4 #define NETDATA_METADATALOGAPI_H
5
6 -#include "metadatalog.h"
7 -
8 -extern BUFFER *metalog_update_host_buffer(RRDHOST *host);
9 -extern void metalog_commit_update_host(RRDHOST *host);
10 -extern BUFFER *metalog_update_chart_buffer(RRDSET *st, uint32_t compaction_id);
11 -extern void metalog_commit_update_chart(RRDSET *st);
6 extern void metalog_commit_delete_chart(RRDSET *st);
13 -extern BUFFER *metalog_update_dimension_buffer(RRDDIM *rd);
14 -extern void metalog_commit_update_dimension(RRDDIM *rd);
15 -extern void metalog_commit_delete_dimension(RRDDIM *rd);
16 -extern void metalog_upd_objcount(RRDHOST *host, int count);
17 -
18 -extern RRDSET *metalog_get_chart_from_uuid(struct metalog_instance *ctx, uuid_t *chart_uuid);
19 -extern RRDDIM *metalog_get_dimension_from_uuid(struct metalog_instance *ctx, uuid_t *metric_uuid);
20 -extern RRDHOST *metalog_get_host_from_uuid(struct metalog_instance *ctx, uuid_t *uuid);
7 extern void metalog_delete_dimension_by_uuid(struct metalog_instance *ctx, uuid_t *metric_uuid);
22 -extern void metalog_print_dimension_by_uuid(struct metalog_instance *ctx, uuid_t *metric_uuid);
8
9 /* must call once before using anything */
10 extern int metalog_init(struct rrdengine_instance *rrdeng_parent_ctx);
26 -extern int metalog_exit(struct metalog_instance *ctx);
27 -extern void metalog_prepare_exit(struct metalog_instance *ctx);
11
12 #endif /* NETDATA_METADATALOGAPI_H */
database/engine/metadata_log/metalogpluginsd.c
+48 -224
@@ -10,13 +10,6 @@ PARSER_RC metalog_pluginsd_host_action(
10 void *user, char *machine_guid, char *hostname, char *registry_hostname, int update_every, char *os, char *timezone,
11 char *tags)
12 {
13 - int history = 5;
14 - RRD_MEMORY_MODE mode = RRD_MEMORY_MODE_DBENGINE;
15 - int rrdpush_enabled = default_rrdpush_enabled;
16 - char *rrdpush_destination = default_rrdpush_destination;
17 - char *rrdpush_api_key = default_rrdpush_api_key;
18 - char *rrdpush_send_charts_matching = default_rrdpush_send_charts_matching;
19 -
13 struct metalog_pluginsd_state *state = ((PARSER_USER_OBJECT *)user)->private;
14
15 RRDHOST *host = rrdhost_find_by_guid(machine_guid, 0);
@@ -26,72 +19,28 @@ PARSER_RC metalog_pluginsd_host_action(
19 host->hostname, rrd_memory_mode_name(host->rrd_memory_mode),
20 rrd_memory_mode_name(RRD_MEMORY_MODE_DBENGINE));
21 ((PARSER_USER_OBJECT *) user)->host = NULL; /* Ignore objects if memory mode is not dbengine */
29 - return PARSER_RC_OK;
22 }
31 - goto write_replay;
23 + ((PARSER_USER_OBJECT *) user)->host = host;
24 + return PARSER_RC_OK;
25 }
26
27 if (strcmp(machine_guid, registry_get_this_machine_guid()) == 0) {
35 - struct metalog_record record;
36 - struct metadata_logfile *metalogfile = state->metalogfile;
37 -
38 - uuid_parse(machine_guid, record.uuid);
39 - mlf_record_insert(metalogfile, &record);
40 - if (localhost->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE)
41 - ((PARSER_USER_OBJECT *) user)->host = localhost;
42 - else
43 - ((PARSER_USER_OBJECT *) user)->host = NULL;
28 + ((PARSER_USER_OBJECT *) user)->host = host;
29 return PARSER_RC_OK;
30 }
31
47 - // Fetch configuration options from streaming config
48 - update_every = (int)appconfig_get_number(&stream_config, machine_guid, "update every", update_every);
49 - if(update_every < 0) update_every = 1;
50 -
51 - //rrdpush_enabled = appconfig_get_boolean(&stream_config, rpt->key, "default proxy enabled", rrdpush_enabled);
52 - rrdpush_enabled = appconfig_get_boolean(&stream_config, machine_guid, "proxy enabled", rrdpush_enabled);
53 -
54 - //rrdpush_destination = appconfig_get(&stream_config, rpt->key, "default proxy destination", rrdpush_destination);
55 - rrdpush_destination = appconfig_get(&stream_config, machine_guid, "proxy destination", rrdpush_destination);
56 -
57 - //rrdpush_api_key = appconfig_get(&stream_config, rpt->key, "default proxy api key", rrdpush_api_key);
58 - rrdpush_api_key = appconfig_get(&stream_config, machine_guid, "proxy api key", rrdpush_api_key);
59 -
60 - //rrdpush_send_charts_matching = appconfig_get(&stream_config, rpt->key, "default proxy send charts matching", rrdpush_send_charts_matching);
61 - rrdpush_send_charts_matching = appconfig_get(&stream_config, machine_guid, "proxy send charts matching", rrdpush_send_charts_matching);
62 -
63 -
64 - host = rrdhost_create(
65 - hostname
66 - , registry_hostname
67 - , machine_guid
68 - , os
69 - , timezone
70 - , tags
71 - , NULL
72 - , NULL
73 - , update_every
74 - , history // entries
75 - , mode
76 - , 0 // health enabled
77 - , rrdpush_enabled // Push enabled
78 - , rrdpush_destination //destination
79 - , rrdpush_api_key // api key
80 - , rrdpush_send_charts_matching // charts matching
81 - , callocz(1, sizeof(struct rrdhost_system_info))
82 - , 0 // localhost
83 - , 1 // archived
84 - );
85 -
86 -write_replay:
87 - if (host) { /* It's a valid object */
88 - struct metalog_record record;
89 - struct metadata_logfile *metalogfile = state->metalogfile;
90 -
91 - uuid_copy(record.uuid, host->host_uuid);
92 - mlf_record_insert(metalogfile, &record);
32 + if (likely(!uuid_parse(machine_guid, state->host_uuid))) {
33 + int rc = sql_store_host(&state->host_uuid, hostname, registry_hostname, update_every, os, timezone, tags);
34 + if (unlikely(rc)) {
35 + errno = 0;
36 + error("Failed to store host %s with UUID %s in the database", hostname, machine_guid);
37 + }
38 + }
39 + else {
40 + errno = 0;
41 + error("Host machine GUID %s is not valid", machine_guid);
42 }
94 - ((PARSER_USER_OBJECT *) user)->host = host;
43 +
44 return PARSER_RC_OK;
45 }
46
@@ -99,51 +48,23 @@ PARSER_RC metalog_pluginsd_chart_action(void *user, char *type, char *id, char *
48 char *title, char *units, char *plugin, char *module, int priority,
49 int update_every, RRDSET_TYPE chart_type, char *options)
50 {
51 + UNUSED(options);
52 +
53 struct metalog_pluginsd_state *state = ((PARSER_USER_OBJECT *)user)->private;
103 - RRDSET *st = NULL;
54 RRDHOST *host = ((PARSER_USER_OBJECT *) user)->host;
105 - uuid_t *chart_uuid;
55
107 - if (unlikely(!host)) {
56 + if (unlikely(uuid_is_null(state->host_uuid))) {
57 debug(D_METADATALOG, "Ignoring chart belonging to missing or ignored host.");
58 return PARSER_RC_OK;
59 }
111 - chart_uuid = uuid_is_null(state->uuid) ? NULL : &state->uuid;
112 - st = rrdset_create_custom(
113 - host, type, id, name, family, context, title, units,
60 + uuid_copy(state->chart_uuid, state->uuid);
61 + uuid_clear(state->uuid); /* Consume UUID */
62 + (void) sql_store_chart(&state->chart_uuid, &state->host_uuid,
63 + type, id, name, family, context, title, units,
64 plugin, module, priority, update_every,
115 - chart_type, RRD_MEMORY_MODE_DBENGINE, (host)->rrd_history_entries, 1, chart_uuid);
116 -
117 - rrdset_isnot_obsolete(st); /* archived charts cannot be obsolete */
118 - if (options && *options) {
119 - if (strstr(options, "detail"))
120 - rrdset_flag_set(st, RRDSET_FLAG_DETAIL);
121 - else
122 - rrdset_flag_clear(st, RRDSET_FLAG_DETAIL);
123 -
124 - if (strstr(options, "hidden"))
125 - rrdset_flag_set(st, RRDSET_FLAG_HIDDEN);
126 - else
127 - rrdset_flag_clear(st, RRDSET_FLAG_HIDDEN);
65 + chart_type, RRD_MEMORY_MODE_DBENGINE, host ? host->rrd_history_entries : 1);
66 + ((PARSER_USER_OBJECT *)user)->st_exists = 1;
67
129 - if (strstr(options, "store_first"))
130 - rrdset_flag_set(st, RRDSET_FLAG_STORE_FIRST);
131 - else
132 - rrdset_flag_clear(st, RRDSET_FLAG_STORE_FIRST);
133 - } else {
134 - rrdset_flag_clear(st, RRDSET_FLAG_DETAIL);
135 - rrdset_flag_clear(st, RRDSET_FLAG_STORE_FIRST);
136 - }
137 - ((PARSER_USER_OBJECT *)user)->st = st;
138 -
139 - if (chart_uuid) { /* It's a valid object */
140 - struct metalog_record record;
141 - struct metadata_logfile *metalogfile = state->metalogfile;
142 -
143 - uuid_copy(record.uuid, state->uuid);
144 - mlf_record_insert(metalogfile, &record);
145 - uuid_clear(state->uuid); /* Consume UUID */
146 - }
68 return PARSER_RC_OK;
69 }
70
@@ -152,36 +73,25 @@ PARSER_RC metalog_pluginsd_dimension_action(void *user, RRDSET *st, char *id, ch
73 {
74 struct metalog_pluginsd_state *state = ((PARSER_USER_OBJECT *)user)->private;
75 UNUSED(user);
76 + UNUSED(options);
77 UNUSED(algorithm);
156 - uuid_t *dim_uuid;
78 + UNUSED(st);
79
158 - if (unlikely(!st)) {
80 + if (unlikely(uuid_is_null(state->chart_uuid))) {
81 debug(D_METADATALOG, "Ignoring dimension belonging to missing or ignored chart.");
82 + info("Ignoring dimension belonging to missing or ignored chart.");
83 return PARSER_RC_OK;
84 }
162 - dim_uuid = uuid_is_null(state->uuid) ? NULL : &state->uuid;
85
164 - RRDDIM *rd = rrddim_add_custom(st, id, name, multiplier, divisor, algorithm_type, RRD_MEMORY_MODE_DBENGINE, 1,
165 - dim_uuid);
166 - rrddim_flag_clear(rd, RRDDIM_FLAG_HIDDEN);
167 - rrddim_flag_clear(rd, RRDDIM_FLAG_DONT_DETECT_RESETS_OR_OVERFLOWS);
168 - rrddim_isnot_obsolete(st, rd); /* archived dimensions cannot be obsolete */
169 - if (options && *options) {
170 - if (strstr(options, "hidden") != NULL)
171 - rrddim_flag_set(rd, RRDDIM_FLAG_HIDDEN);
172 - if (strstr(options, "noreset") != NULL)
173 - rrddim_flag_set(rd, RRDDIM_FLAG_DONT_DETECT_RESETS_OR_OVERFLOWS);
174 - if (strstr(options, "nooverflow") != NULL)
175 - rrddim_flag_set(rd, RRDDIM_FLAG_DONT_DETECT_RESETS_OR_OVERFLOWS);
86 + if (unlikely(uuid_is_null(state->uuid))) {
87 + debug(D_METADATALOG, "Ignoring dimension without unknown UUID");
88 + info("Ignoring dimension without unknown UUID");
89 + return PARSER_RC_OK;
90 }
177 - if (dim_uuid) { /* It's a valid object */
178 - struct metalog_record record;
179 - struct metadata_logfile *metalogfile = state->metalogfile;
91
181 - uuid_copy(record.uuid, state->uuid);
182 - mlf_record_insert(metalogfile, &record);
183 - uuid_clear(state->uuid); /* Consume UUID */
184 - }
92 + (void) sql_store_dimension(&state->uuid, &state->chart_uuid, id, name, multiplier, divisor, algorithm_type);
93 + uuid_clear(state->uuid); /* Consume UUID */
94 +
95 return PARSER_RC_OK;
96 }
97
@@ -196,113 +106,27 @@ PARSER_RC metalog_pluginsd_guid_action(void *user, uuid_t *uuid)
106
107 PARSER_RC metalog_pluginsd_context_action(void *user, uuid_t *uuid)
108 {
199 - GUID_TYPE ret;
200 - //struct metalog_pluginsd_state *state = ((PARSER_USER_OBJECT *)user)->private;
201 - //struct metalog_instance *ctx = state->ctx;
202 - char object[49], chart_object[33], id_str[1024];
203 - uuid_t *chart_guid, *chart_char_guid;
204 - RRDHOST *host;
205 -
206 - ret = find_object_by_guid(uuid, object, 49);
207 - switch (ret) {
208 - case GUID_TYPE_NOTFOUND:
209 - error_with_guid(uuid, "Failed to find valid context");
210 - break;
211 - case GUID_TYPE_CHAR:
212 - error_with_guid(uuid, "Ignoring unexpected type GUID_TYPE_CHAR");
213 - break;
214 - case GUID_TYPE_CHART:
215 - case GUID_TYPE_DIMENSION:
216 - host = metalog_get_host_from_uuid(NULL, (uuid_t *) &object);
217 - if (unlikely(!host))
218 - break;
219 - switch (ret) {
220 - case GUID_TYPE_CHART:
221 - chart_char_guid = (uuid_t *)(object + 16);
222 -
223 - ret = find_object_by_guid(chart_char_guid, id_str, RRD_ID_LENGTH_MAX + 1);
224 - if (unlikely(GUID_TYPE_CHAR != ret))
225 - error_with_guid(uuid, "Failed to find valid chart name");
226 - else
227 - ((PARSER_USER_OBJECT *)user)->st = rrdset_find(host, id_str);
228 - break;
229 - case GUID_TYPE_DIMENSION:
230 - chart_guid = (uuid_t *)(object + 16);
109 + struct metalog_pluginsd_state *state = ((PARSER_USER_OBJECT *)user)->private;
110
232 - ret = find_object_by_guid(chart_guid, chart_object, 33);
233 - if (unlikely(GUID_TYPE_CHART != ret)) {
234 - error_with_guid(uuid, "Failed to find valid chart");
235 - break;
236 - }
237 - chart_char_guid = (uuid_t *)(object + 16);
111 + int rc = find_uuid_type(uuid);
112
239 - ret = find_object_by_guid(chart_char_guid, id_str, RRD_ID_LENGTH_MAX + 1);
240 - if (unlikely(GUID_TYPE_CHAR != ret))
241 - error_with_guid(uuid, "Failed to find valid chart name");
242 - else
243 - ((PARSER_USER_OBJECT *)user)->st = rrdset_find(host, id_str);
244 - break;
245 - default:
246 - break;
247 - }
248 - break;
249 - case GUID_TYPE_HOST:
250 - ((PARSER_USER_OBJECT *)user)->host = metalog_get_host_from_uuid(NULL, (uuid_t *) &object);
251 - break;
252 - case GUID_TYPE_NOSPACE:
253 - error_with_guid(uuid, "Not enough space for object retrieval");
254 - break;
255 - default:
256 - error("Unknown return code %u from find_object_by_guid", ret);
257 - break;
258 - }
113 + if (rc == 1) {
114 + uuid_copy(state->host_uuid, *uuid);
115 + ((PARSER_USER_OBJECT *)user)->st_exists = 0;
116 + ((PARSER_USER_OBJECT *)user)->host_exists = 1;
117 + } else if (rc == 2) {
118 + uuid_copy(state->chart_uuid, *uuid);
119 + ((PARSER_USER_OBJECT *)user)->st_exists = 1;
120 + } else
121 + uuid_copy(state->uuid, *uuid);
122
123 return PARSER_RC_OK;
124 }
125
126 PARSER_RC metalog_pluginsd_tombstone_action(void *user, uuid_t *uuid)
127 {
265 - GUID_TYPE ret;
266 - struct metalog_pluginsd_state *state = ((PARSER_USER_OBJECT *)user)->private;
267 - struct metalog_instance *ctx = state->ctx;
268 - RRDHOST *host = NULL;
269 - RRDSET *st;
270 - RRDDIM *rd;
271 -
272 - ret = find_object_by_guid(uuid, NULL, 0);
273 - switch (ret) {
274 - case GUID_TYPE_CHAR:
275 - fatal_assert(0);
276 - break;
277 - case GUID_TYPE_CHART:
278 - st = metalog_get_chart_from_uuid(ctx, uuid);
279 - if (st) {
280 - host = st->rrdhost;
281 - rrdhost_wrlock(host);
282 - rrdset_free(st);
283 - rrdhost_unlock(host);
284 - } else {
285 - debug(D_METADATALOG, "Ignoring nonexistent chart metadata record.");
286 - }
287 - break;
288 - case GUID_TYPE_DIMENSION:
289 - rd = metalog_get_dimension_from_uuid(ctx, uuid);
290 - if (rd) {
291 - st = rd->rrdset;
292 - rrdset_wrlock(st);
293 - rrddim_free_custom(st, rd, 0);
294 - rrdset_unlock(st);
295 - }
296 - else {
297 - debug(D_METADATALOG, "Ignoring nonexistent dimension metadata record.");
298 - }
299 - break;
300 - case GUID_TYPE_HOST:
301 - /* Ignore for now */
302 - break;
303 - default:
304 - break;
305 - }
128 + UNUSED(user);
129 + UNUSED(uuid);
130
131 return PARSER_RC_OK;
132 }
@@ -313,4 +137,4 @@ void metalog_pluginsd_state_init(struct metalog_pluginsd_state *state, struct me
137 state->skip_record = 0;
138 uuid_clear(state->uuid);
139 state->metalogfile = NULL;
316 -}
\ No newline at end of file
140 +}
database/engine/metadata_log/metalogpluginsd.h
+2
@@ -10,6 +10,8 @@
10 struct metalog_pluginsd_state {
11 struct metalog_instance *ctx;
12 uuid_t uuid;
13 + uuid_t host_uuid;
14 + uuid_t chart_uuid;
15 uint8_t skip_record; /* skip this record due to errors in parsing */
16 struct metadata_logfile *metalogfile; /* current metadata log file being replayed */
17 };
database/engine/rrdengineapi.c
+20 -32
@@ -54,9 +54,10 @@ void rrdeng_metric_init(RRDDIM *rd, uuid_t *dim_uuid)
54 struct page_cache *pg_cache;
55 struct rrdengine_instance *ctx;
56 uuid_t legacy_uuid;
57 + uuid_t multihost_legacy_uuid;
58 Pvoid_t *PValue;
59 struct pg_cache_page_index *page_index = NULL;
59 - int replace_instead_of_generate = 0, is_multihost_child = 0;
60 + int is_multihost_child = 0;
61 RRDHOST *host = rd->rrdset->rrdhost;
62
63 ctx = get_rrdeng_ctx_from_host(rd->rrdset->rrdhost);
@@ -67,7 +68,7 @@ void rrdeng_metric_init(RRDDIM *rd, uuid_t *dim_uuid)
68 pg_cache = &ctx->pg_cache;
69
70 rrdeng_generate_legacy_uuid(rd->id, rd->rrdset->id, &legacy_uuid);
70 - rd->state->metric_uuid = callocz(1, sizeof(uuid_t));
71 + rd->state->metric_uuid = dim_uuid;
72 if (host != localhost && host->rrdeng_ctx == &multidb_ctx)
73 is_multihost_child = 1;
74
@@ -81,22 +82,8 @@ void rrdeng_metric_init(RRDDIM *rd, uuid_t *dim_uuid)
82 /* First time we see the legacy UUID or metric belongs to child host in multi-host DB.
83 * Drop legacy support, normal path */
84
84 - if (NULL != dim_uuid) {
85 - replace_instead_of_generate = 1;
86 - uuid_copy(*rd->state->metric_uuid, *dim_uuid);
87 - }
88 - if (unlikely(find_or_generate_guid(rd, rd->state->metric_uuid, GUID_TYPE_DIMENSION,
89 - replace_instead_of_generate))) {
90 - errno = 0;
91 - error("FAILED to reuse GUID for %s", rd->id);
92 - if (unlikely(find_or_generate_guid(rd, rd->state->metric_uuid, GUID_TYPE_DIMENSION, 0))) {
93 - errno = 0;
94 - error("FAILED to generate GUID for %s", rd->id);
95 - freez(rd->state->metric_uuid);
96 - rd->state->metric_uuid = NULL;
97 - fatal_assert(0);
98 - }
99 - }
85 + if (unlikely(!rd->state->metric_uuid))
86 + rd->state->metric_uuid = create_dimension_uuid(rd->rrdset, rd);
87
88 uv_rwlock_rdlock(&pg_cache->metrics_index.lock);
89 PValue = JudyHSGet(pg_cache->metrics_index.JudyHS_array, rd->state->metric_uuid, sizeof(uuid_t));
@@ -116,19 +103,20 @@ void rrdeng_metric_init(RRDDIM *rd, uuid_t *dim_uuid)
103 } else {
104 /* There are legacy UUIDs in the database, implement backward compatibility */
105
119 -
106 rrdeng_convert_legacy_uuid_to_multihost(rd->rrdset->rrdhost->machine_guid, &legacy_uuid,
121 - rd->state->metric_uuid);
122 - if (dim_uuid && uuid_compare(*rd->state->metric_uuid, *dim_uuid)) {
123 - error("Mismatch of metadata log DIMENSION GUID with dbengine metric GUID.");
124 - }
125 - if (unlikely(find_or_generate_guid(rd, rd->state->metric_uuid, GUID_TYPE_DIMENSION, 1))) {
126 - errno = 0;
127 - error("FAILED to generate GUID for %s", rd->id);
128 - freez(rd->state->metric_uuid);
129 - rd->state->metric_uuid = NULL;
130 - fatal_assert(0);
131 - }
107 + &multihost_legacy_uuid);
108 +
109 + if (unlikely(!rd->state->metric_uuid))
110 + rd->state->metric_uuid = mallocz(sizeof(uuid_t));
111 +
112 + int need_to_store = (dim_uuid == NULL || uuid_compare(*rd->state->metric_uuid, multihost_legacy_uuid));
113 +
114 + uuid_copy(*rd->state->metric_uuid, multihost_legacy_uuid);
115 +
116 + if (unlikely(need_to_store))
117 + (void)sql_store_dimension(rd->state->metric_uuid, rd->rrdset->chart_uuid, rd->id, rd->name, rd->multiplier, rd->divisor,
118 + rd->algorithm);
119 +
120 }
121 rd->state->rrdeng_uuid = &page_index->id;
122 rd->state->page_index = page_index;
@@ -981,7 +969,7 @@ int rrdeng_exit(struct rrdengine_instance *ctx)
969 fatal_assert(0 == uv_thread_join(&ctx->worker_config.thread));
970
971 finalize_rrd_files(ctx);
984 - metalog_exit(ctx->metalog_ctx);
972 + //metalog_exit(ctx->metalog_ctx);
973 free_page_cache(ctx);
974
975 if (ctx != &multidb_ctx) {
@@ -1007,6 +995,6 @@ void rrdeng_prepare_exit(struct rrdengine_instance *ctx)
995 wait_for_completion(&ctx->rrdengine_completion);
996 destroy_completion(&ctx->rrdengine_completion);
997
1010 - metalog_prepare_exit(ctx->metalog_ctx);
998 + //metalog_prepare_exit(ctx->metalog_ctx);
999 }
1000
database/rrd.h
+12 -8
@@ -950,12 +950,10 @@ extern RRDSET *rrdset_create_custom(RRDHOST *host
950 , int update_every
951 , RRDSET_TYPE chart_type
952 , RRD_MEMORY_MODE memory_mode
953 - , long history_entries
954 - , int is_archived
955 - , uuid_t *chart_uuid);
953 + , long history_entries);
954
955 #define rrdset_create(host, type, id, name, family, context, title, units, plugin, module, priority, update_every, chart_type) \
958 - rrdset_create_custom(host, type, id, name, family, context, title, units, plugin, module, priority, update_every, chart_type, (host)->rrd_memory_mode, (host)->rrd_history_entries, 0, NULL)
956 + rrdset_create_custom(host, type, id, name, family, context, title, units, plugin, module, priority, update_every, chart_type, (host)->rrd_memory_mode, (host)->rrd_history_entries)
957
958 #define rrdset_create_localhost(type, id, name, family, context, title, units, plugin, module, priority, update_every, chart_type) \
959 rrdset_create(localhost, type, id, name, family, context, title, units, plugin, module, priority, update_every, chart_type)
@@ -1161,10 +1159,10 @@ static inline time_t rrdset_slot2time(RRDSET *st, size_t slot) {
1159
1160 extern void rrdcalc_link_to_rrddim(RRDDIM *rd, RRDSET *st, RRDHOST *host);
1161 extern RRDDIM *rrddim_add_custom(RRDSET *st, const char *id, const char *name, collected_number multiplier,
1164 - collected_number divisor, RRD_ALGORITHM algorithm, RRD_MEMORY_MODE memory_mode,
1165 - int is_archived, uuid_t *dim_uuid);
1162 + collected_number divisor, RRD_ALGORITHM algorithm, RRD_MEMORY_MODE memory_mode);//,
1163 + //int is_archived, uuid_t *dim_uuid);
1164 #define rrddim_add(st, id, name, multiplier, divisor, algorithm) rrddim_add_custom(st, id, name, multiplier, divisor, \
1167 - algorithm, (st)->rrd_memory_mode, 0, NULL)
1165 + algorithm, (st)->rrd_memory_mode)//, 0, NULL)
1166
1167 extern int rrddim_set_name(RRDSET *st, RRDDIM *rd, const char *name);
1168 extern int rrddim_set_algorithm(RRDSET *st, RRDDIM *rd, RRD_ALGORITHM algorithm);
@@ -1237,15 +1235,21 @@ extern RRDHOST *rrdhost_create(
1235 const char *tags, const char *program_name, const char *program_version, int update_every, long entries,
1236 RRD_MEMORY_MODE memory_mode, unsigned int health_enabled, unsigned int rrdpush_enabled, char *rrdpush_destination,
1237 char *rrdpush_api_key, char *rrdpush_send_charts_matching, struct rrdhost_system_info *system_info,
1240 - int is_localhost, int is_archived);
1238 + int is_localhost); //TODO: Remove , int is_archived);
1239
1240 #endif /* NETDATA_RRD_INTERNALS */
1241
1242 +extern void set_host_properties(
1243 + RRDHOST *host, int update_every, RRD_MEMORY_MODE memory_mode, const char *hostname, const char *registry_hostname,
1244 + const char *guid, const char *os, const char *tags, const char *tzone, const char *program_name,
1245 + const char *program_version);
1246 +
1247 // ----------------------------------------------------------------------------
1248 // RRD DB engine declarations
1249
1250 #ifdef ENABLE_DBENGINE
1251 #include "database/engine/rrdengineapi.h"
1252 +#include "sqlite/sqlite_functions.h"
1253 #endif
1254
1255 #endif /* NETDATA_RRD_H */
database/rrddim.c
+15 -29
@@ -216,8 +216,8 @@ void rrdcalc_link_to_rrddim(RRDDIM *rd, RRDSET *st, RRDHOST *host) {
216 }
217
218 RRDDIM *rrddim_add_custom(RRDSET *st, const char *id, const char *name, collected_number multiplier,
219 - collected_number divisor, RRD_ALGORITHM algorithm, RRD_MEMORY_MODE memory_mode,
220 - int is_archived, uuid_t *dim_uuid) {
219 + collected_number divisor, RRD_ALGORITHM algorithm, RRD_MEMORY_MODE memory_mode)
220 +{
221 RRDHOST *host = st->rrdhost;
222 rrdset_wrlock(st);
223
@@ -232,7 +232,10 @@ RRDDIM *rrddim_add_custom(RRDSET *st, const char *id, const char *name, collecte
232 rc += rrddim_set_algorithm(st, rd, algorithm);
233 rc += rrddim_set_multiplier(st, rd, multiplier);
234 rc += rrddim_set_divisor(st, rd, divisor);
235 - if (!is_archived && rrddim_flag_check(rd, RRDDIM_FLAG_ARCHIVED)) {
235 + if (rrddim_flag_check(rd, RRDDIM_FLAG_ARCHIVED)) {
236 +#ifdef ENABLE_DBENGINE
237 + store_active_dimension(rd->state->metric_uuid);
238 +#endif
239 rd->state->collect_ops.init(rd);
240 rrddim_flag_clear(rd, RRDDIM_FLAG_ARCHIVED);
241 rrddimvar_create(rd, RRDVAR_TYPE_CALCULATED, NULL, NULL, &rd->last_stored_value, RRDVAR_OPTION_DEFAULT);
@@ -242,9 +245,10 @@ RRDDIM *rrddim_add_custom(RRDSET *st, const char *id, const char *name, collecte
245 }
246 // DBENGINE available and activated?
247 #ifdef ENABLE_DBENGINE
245 - if (likely(!is_archived && rd->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE) && unlikely(rc)) {
248 + if (likely(rd->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE) && unlikely(rc)) {
249 debug(D_METADATALOG, "DIMENSION [%s] metadata updated", rd->id);
247 - metalog_commit_update_dimension(rd);
250 + (void)sql_store_dimension(rd->state->metric_uuid, rd->rrdset->chart_uuid, rd->id, rd->name, rd->multiplier, rd->divisor,
251 + rd->algorithm);
252 }
253 #endif
254 rrdset_unlock(st);
@@ -391,7 +395,9 @@ RRDDIM *rrddim_add_custom(RRDSET *st, const char *id, const char *name, collecte
395 rd->state = mallocz(sizeof(*rd->state));
396 if(memory_mode == RRD_MEMORY_MODE_DBENGINE) {
397 #ifdef ENABLE_DBENGINE
398 + uuid_t *dim_uuid = find_dimension_uuid(st, rd);
399 rrdeng_metric_init(rd, dim_uuid);
400 + store_active_dimension(rd->state->metric_uuid);
401 rd->state->collect_ops.init = rrdeng_store_metric_init;
402 rd->state->collect_ops.store_metric = rrdeng_store_metric_next;
403 rd->state->collect_ops.finalize = rrdeng_store_metric_finalize;
@@ -413,10 +419,7 @@ RRDDIM *rrddim_add_custom(RRDSET *st, const char *id, const char *name, collecte
419 rd->state->query_ops.latest_time = rrddim_query_latest_time;
420 rd->state->query_ops.oldest_time = rrddim_query_oldest_time;
421 }
416 - if (is_archived)
417 - rrddim_flag_set(rd, RRDDIM_FLAG_ARCHIVED);
418 - else
419 - rd->state->collect_ops.init(rd); // only initialize if a collector created this dimension
422 + rd->state->collect_ops.init(rd);
423 // append this dimension
424 if(!st->dimensions)
425 st->dimensions = rd;
@@ -443,7 +446,7 @@ RRDDIM *rrddim_add_custom(RRDSET *st, const char *id, const char *name, collecte
446 td->next = rd;
447 }
448
446 - if(host->health_enabled && !is_archived) {
449 + if(host->health_enabled) {
450 rrddimvar_create(rd, RRDVAR_TYPE_CALCULATED, NULL, NULL, &rd->last_stored_value, RRDVAR_OPTION_DEFAULT);
451 rrddimvar_create(rd, RRDVAR_TYPE_COLLECTED, NULL, "_raw", &rd->last_collected_value, RRDVAR_OPTION_DEFAULT);
452 rrddimvar_create(rd, RRDVAR_TYPE_TIME_T, NULL, "_last_collected_t", &rd->last_collected_time.tv_sec, RRDVAR_OPTION_DEFAULT);
@@ -452,19 +455,13 @@ RRDDIM *rrddim_add_custom(RRDSET *st, const char *id, const char *name, collecte
455 if(unlikely(rrddim_index_add(st, rd) != rd))
456 error("RRDDIM: INTERNAL ERROR: attempt to index duplicate dimension '%s' on chart '%s'", rd->id, st->id);
457
455 - if (!is_archived)
456 - calc_link_to_rrddim(rd);
458 + calc_link_to_rrddim(rd);
459
460 rrdset_unlock(st);
461 #ifdef ENABLE_ACLK
462 if (netdata_cloud_setting)
463 aclk_update_chart(host, st->id, ACLK_CMD_CHART);
464 #endif
463 -#ifdef ENABLE_DBENGINE
464 - metalog_upd_objcount(st->rrdhost, 1);
465 - metalog_commit_update_dimension(rd);
466 -#endif
467 -
465 return(rd);
466 }
467
@@ -483,7 +480,7 @@ void rrddim_free_custom(RRDSET *st, RRDDIM *rd, int db_rotated)
480 if (can_delete_metric && rd->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE) {
481 #ifdef ENABLE_DBENGINE
482 /* This metric has no data and no references */
486 - metalog_commit_delete_dimension(rd);
483 + delete_dimension_uuid(rd->state->metric_uuid);
484 #endif
485 }
486 }
@@ -529,7 +526,6 @@ void rrddim_free_custom(RRDSET *st, RRDDIM *rd, int db_rotated)
526 freez(rd->cache_filename);
527 #ifdef ENABLE_DBENGINE
528 if (rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE) {
532 - free_uuid(rd->state->metric_uuid);
529 freez(rd->state->metric_uuid);
530 }
531 #endif
@@ -541,9 +537,6 @@ void rrddim_free_custom(RRDSET *st, RRDDIM *rd, int db_rotated)
537 if ((netdata_cloud_setting) && (db_rotated || RRD_MEMORY_MODE_DBENGINE != rrd_memory_mode))
538 aclk_update_chart(st->rrdhost, st->id, ACLK_CMD_CHART);
539 #endif
544 -#ifdef ENABLE_DBENGINE
545 - metalog_upd_objcount(st->rrdhost, -1);
546 -#endif
540 }
541
542
@@ -600,10 +593,6 @@ inline void rrddim_is_obsolete(RRDSET *st, RRDDIM *rd) {
593 if (netdata_cloud_setting)
594 aclk_update_chart(st->rrdhost, st->id, ACLK_CMD_CHART);
595 #endif
603 -#ifdef ENABLE_DBENGINE
604 - metalog_commit_update_dimension(rd);
605 -#endif
606 -
596 }
597
598 inline void rrddim_isnot_obsolete(RRDSET *st __maybe_unused, RRDDIM *rd) {
@@ -614,9 +603,6 @@ inline void rrddim_isnot_obsolete(RRDSET *st __maybe_unused, RRDDIM *rd) {
603 if (netdata_cloud_setting)
604 aclk_update_chart(st->rrdhost, st->id, ACLK_CMD_CHART);
605 #endif
617 -#ifdef ENABLE_DBENGINE
618 - metalog_commit_update_dimension(rd);
619 -#endif
606 }
607
608 // ----------------------------------------------------------------------------
database/rrdhost.c
+49 -49
@@ -103,6 +103,28 @@ static inline void rrdhost_init_machine_guid(RRDHOST *host, const char *machine_
103 host->hash_machine_guid = simple_hash(host->machine_guid);
104 }
105
106 +void set_host_properties(RRDHOST *host, int update_every, RRD_MEMORY_MODE memory_mode, const char *hostname,
107 + const char *registry_hostname, const char *guid, const char *os, const char *tags,
108 + const char *tzone, const char *program_name, const char *program_version)
109 +{
110 +
111 + host->rrd_update_every = update_every;
112 + host->rrd_memory_mode = memory_mode;
113 +
114 + rrdhost_init_hostname(host, hostname);
115 +
116 + rrdhost_init_machine_guid(host, guid);
117 +
118 + rrdhost_init_os(host, os);
119 + rrdhost_init_timezone(host, tzone);
120 + rrdhost_init_tags(host, tags);
121 +
122 + host->program_name = strdupz((program_name && *program_name) ? program_name : "unknown");
123 + host->program_version = strdupz((program_version && *program_version) ? program_version : "unknown");
124 +
125 + host->registry_hostname = strdupz((registry_hostname && *registry_hostname) ? registry_hostname : host->hostname);
126 +}
127 +
128 // ----------------------------------------------------------------------------
129 // RRDHOST - add a host
130
@@ -123,13 +145,12 @@ RRDHOST *rrdhost_create(const char *hostname,
145 char *rrdpush_api_key,
146 char *rrdpush_send_charts_matching,
147 struct rrdhost_system_info *system_info,
126 - int is_localhost,
127 - int is_archived
148 + int is_localhost
149 ) {
150 debug(D_RRDHOST, "Host '%s': adding with guid '%s'", hostname, guid);
151
152 #ifdef ENABLE_DBENGINE
132 - int is_legacy = is_archived ? 0 : (memory_mode == RRD_MEMORY_MODE_DBENGINE) && is_legacy_child(guid);
153 + int is_legacy = (memory_mode == RRD_MEMORY_MODE_DBENGINE) && is_legacy_child(guid);
154 #else
155 int is_legacy = 1;
156 #endif
@@ -138,10 +159,11 @@ RRDHOST *rrdhost_create(const char *hostname,
159 int is_in_multihost = (memory_mode == RRD_MEMORY_MODE_DBENGINE && !is_legacy);
160 RRDHOST *host = callocz(1, sizeof(RRDHOST));
161
141 - host->rrd_update_every = (update_every > 0)?update_every:1;
162 + set_host_properties(host, (update_every > 0)?update_every:1, memory_mode, hostname, registry_hostname, guid, os,
163 + tags, timezone, program_name, program_version);
164 +
165 host->rrd_history_entries = align_entries_to_pagesize(memory_mode, entries);
143 - host->rrd_memory_mode = memory_mode;
144 - host->health_enabled = ((memory_mode == RRD_MEMORY_MODE_NONE) || is_archived) ? 0 : health_enabled;
166 + host->health_enabled = ((memory_mode == RRD_MEMORY_MODE_NONE)) ? 0 : health_enabled;
167
168 host->sender = mallocz(sizeof(*host->sender));
169 sender_init(host->sender, host);
@@ -169,17 +191,6 @@ RRDHOST *rrdhost_create(const char *hostname,
191
192 netdata_mutex_init(&host->claimed_id_lock);
193
172 - rrdhost_init_hostname(host, hostname);
173 - rrdhost_init_machine_guid(host, guid);
174 -
175 - rrdhost_init_os(host, os);
176 - rrdhost_init_timezone(host, timezone);
177 - rrdhost_init_tags(host, tags);
178 -
179 - host->program_name = strdupz((program_name && *program_name)?program_name:"unknown");
180 - host->program_version = strdupz((program_version && *program_version)?program_version:"unknown");
181 - host->registry_hostname = strdupz((registry_hostname && *registry_hostname)?registry_hostname:hostname);
182 -
194 host->system_info = system_info;
195
196 avl_init_lock(&(host->rrdset_root_index), rrdset_compare);
@@ -187,10 +198,6 @@ RRDHOST *rrdhost_create(const char *hostname,
198 avl_init_lock(&(host->rrdfamily_root_index), rrdfamily_compare);
199 avl_init_lock(&(host->rrdvar_root_index), rrdvar_compare);
200
190 - if (is_archived) {
191 - rrdhost_flag_set(host, RRDHOST_FLAG_ARCHIVED);
192 - info("Host %s is created in archived mode", hostname);
193 - }
201 if(config_get_boolean(CONFIG_SECTION_GLOBAL, "delete obsolete charts files", 1))
202 rrdhost_flag_set(host, RRDHOST_FLAG_DELETE_OBSOLETE_CHARTS);
203
@@ -248,7 +255,7 @@ RRDHOST *rrdhost_create(const char *hostname,
255 snprintfz(filename, FILENAME_MAX, "%s/%s", netdata_configured_varlib_dir, host->machine_guid);
256 host->varlib_dir = strdupz(filename);
257
251 - if(!is_archived && host->health_enabled) {
258 + if(host->health_enabled) {
259 int r = mkdir(host->varlib_dir, 0775);
260 if(r != 0 && errno != EEXIST)
261 error("Host '%s': cannot create directory '%s'", host->hostname, host->varlib_dir);
@@ -256,7 +263,7 @@ RRDHOST *rrdhost_create(const char *hostname,
263
264 }
265
259 - if(!is_archived && host->health_enabled) {
266 + if(host->health_enabled) {
267 snprintfz(filename, FILENAME_MAX, "%s/health", host->varlib_dir);
268 int r = mkdir(filename, 0775);
269 if(r != 0 && errno != EEXIST)
@@ -274,7 +281,7 @@ RRDHOST *rrdhost_create(const char *hostname,
281 // ------------------------------------------------------------------------
282 // load health configuration
283
277 - if(!is_archived && host->health_enabled) {
284 + if(host->health_enabled) {
285 rrdhost_wrlock(host);
286 health_readdir(host, health_user_config_dir(), health_stock_config_dir(), NULL);
287 rrdhost_unlock(host);
@@ -293,13 +300,13 @@ RRDHOST *rrdhost_create(const char *hostname,
300
301 if (host->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE) {
302 #ifdef ENABLE_DBENGINE
296 - if (unlikely(-1 == uuid_parse(host->machine_guid, host->host_uuid))) {
297 - error("Host machine GUID is not valid.");
303 + if (likely(!uuid_parse(host->machine_guid, host->host_uuid))) {
304 + int rc = sql_store_host(&host->host_uuid, hostname, registry_hostname, update_every, os, timezone, tags);
305 + if (unlikely(rc))
306 + error_report("Failed to store machine GUID to the database");
307 }
299 - if (unlikely(find_or_generate_guid((void *) host, &host->host_uuid, GUID_TYPE_HOST, 1)))
300 - error("Failed to store machine GUID to global map");
308 else
302 - info("Added %s to global map for host %s", host->machine_guid, host->hostname);
309 + error_report("Host machine GUID %s is not valid", host->machine_guid);
310 host->compaction_id = 0;
311 char dbenginepath[FILENAME_MAX + 1];
312 int ret;
@@ -325,7 +332,6 @@ RRDHOST *rrdhost_create(const char *hostname,
332 return host;
333 }
334
328 - metalog_upd_objcount(host, 1);
335 #else
336 fatal("RRD_MEMORY_MODE_DBENGINE is not supported in this platform.");
337 #endif
@@ -385,13 +391,8 @@ RRDHOST *rrdhost_create(const char *hostname,
391 , host->health_default_recipient
392 );
393
388 - if (!is_archived)
389 - rrd_hosts_available++;
394 + rrd_hosts_available++;
395
391 -#ifdef ENABLE_DBENGINE
392 - if (likely(!is_localhost && !is_archived && host && host->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE))
393 - metalog_commit_update_host(host);
394 -#endif
396 return host;
397 }
398
@@ -493,10 +494,7 @@ void rrdhost_update(RRDHOST *host
494 rrd_hosts_available++;
495 info("Host %s is not in archived mode anymore", host->hostname);
496 }
496 -#ifdef ENABLE_DBENGINE
497 - if (likely(host->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE))
498 - metalog_commit_update_host(host);
499 -#endif
497 +
498 return;
499 }
500
@@ -550,7 +548,6 @@ RRDHOST *rrdhost_find_or_create(
548 , rrdpush_send_charts_matching
549 , system_info
550 , 0
553 - , 0
551 );
552 }
553 else {
@@ -633,6 +630,12 @@ int rrd_init(char *hostname, struct rrdhost_system_info *system_info) {
630 if (gap_when_lost_iterations_above < 1)
631 gap_when_lost_iterations_above = 1;
632
633 +#ifdef ENABLE_DBENGINE
634 + if (unlikely(sql_init_database())) {
635 + return 1;
636 + }
637 +#endif
638 +
639 health_init();
640
641 rrdpush_init();
@@ -658,7 +661,6 @@ int rrd_init(char *hostname, struct rrdhost_system_info *system_info) {
661 , default_rrdpush_send_charts_matching
662 , system_info
663 , 1
661 - , 0
664 );
665 if (unlikely(!localhost)) {
666 rrd_unlock();
@@ -800,8 +802,10 @@ void rrdhost_free(RRDHOST *host) {
802 // release its children resources
803
804 #ifdef ENABLE_DBENGINE
803 - if (host->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE && host->rrdeng_ctx != &multidb_ctx)
804 - rrdeng_prepare_exit(host->rrdeng_ctx);
805 + if (host->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE) {
806 + if (host->rrdeng_ctx != &multidb_ctx)
807 + rrdeng_prepare_exit(host->rrdeng_ctx);
808 + }
809 #endif
810 while(host->rrdset_root)
811 rrdset_free(host->rrdset_root);
@@ -890,9 +894,6 @@ void rrdhost_free(RRDHOST *host) {
894 netdata_rwlock_destroy(&host->health_log.alarm_log_rwlock);
895 netdata_rwlock_destroy(&host->rrdhost_rwlock);
896
893 -#ifdef ENABLE_DBENGINE
894 - free_uuid(&host->host_uuid);
895 -#endif
897 freez(host);
898
899 rrd_hosts_available--;
@@ -1544,7 +1545,7 @@ restart_after_removal:
1545 uint8_t can_delete_metric = rd->state->collect_ops.finalize(rd);
1546 if (can_delete_metric) {
1547 /* This metric has no data and no references */
1547 - metalog_commit_delete_dimension(rd);
1548 + delete_dimension_uuid(rd->state->metric_uuid);
1549 rrddim_free(st, rd);
1550 if (unlikely(!last)) {
1551 rd = st->dimensions;
@@ -1568,7 +1569,6 @@ restart_after_removal:
1569 /* If the chart still has dimensions don't delete it from the metadata log */
1570 continue;
1571 }
1571 - metalog_commit_delete_chart(st);
1572 }
1573 #endif
1574 rrdset_rdlock(st);
database/rrdset.c
+15 -44
@@ -320,7 +320,6 @@ void rrdset_free(RRDSET *st) {
320
321 rrdhost_check_wrlock(host); // make sure we have a write lock on the host
322 rrdset_wrlock(st); // lock this RRDSET
323 -
323 // info("Removing chart '%s' ('%s')", st->id, st->name);
324
325 // ------------------------------------------------------------------------
@@ -389,17 +388,12 @@ void rrdset_free(RRDSET *st) {
388 case RRD_MEMORY_MODE_NONE:
389 case RRD_MEMORY_MODE_DBENGINE:
390 #ifdef ENABLE_DBENGINE
392 - if (st->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE) {
393 - free_uuid(st->chart_uuid);
391 + if (st->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE)
392 freez(st->chart_uuid);
395 - }
393 #endif
394 freez(st);
395 break;
396 }
400 -#ifdef ENABLE_DBENGINE
401 - metalog_upd_objcount(host, -1);
402 -#endif
397
398 }
399
@@ -503,8 +497,6 @@ RRDSET *rrdset_create_custom(
497 , RRDSET_TYPE chart_type
498 , RRD_MEMORY_MODE memory_mode
499 , long history_entries
506 - , int is_archived
507 - , uuid_t *chart_uuid
500 ) {
501 if(!type || !type[0]) {
502 fatal("Cannot create rrd stats without a type: id '%s', name '%s', family '%s', context '%s', title '%s', units '%s', plugin '%s', module '%s'."
@@ -546,7 +538,7 @@ RRDSET *rrdset_create_custom(
538 int mark_rebuild = 0;
539 rrdset_flag_set(st, RRDSET_FLAG_SYNC_CLOCK);
540 rrdset_flag_clear(st, RRDSET_FLAG_UPSTREAM_EXPOSED);
549 - if (!is_archived && rrdset_flag_check(st, RRDSET_FLAG_ARCHIVED)) {
541 + if (rrdset_flag_check(st, RRDSET_FLAG_ARCHIVED)) {
542 rrdset_flag_clear(st, RRDSET_FLAG_ARCHIVED);
543 changed_from_archived_to_active = 1;
544 mark_rebuild |= META_CHART_ACTIVATED;
@@ -661,10 +653,12 @@ RRDSET *rrdset_create_custom(
653 }
654 }
655 #ifdef ENABLE_DBENGINE
664 - if (is_archived == 0 && st->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE &&
656 + if (st->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE &&
657 (mark_rebuild & (META_CHART_UPDATED | META_PLUGIN_UPDATED | META_MODULE_UPDATED))) {
658 debug(D_METADATALOG, "CHART [%s] metadata updated", st->id);
667 - metalog_commit_update_chart(st);
659 + int rc = update_chart_metadata(st->chart_uuid, st, id, name);
660 + if (unlikely(rc))
661 + error_report("Failed to update chart metadata in the database");
662 }
663 #endif
664 /* Fall-through during switch from archived to active so that the host lock is taken and health is linked */
@@ -689,9 +683,6 @@ RRDSET *rrdset_create_custom(
683 rrdhost_unlock(host);
684 rrdset_flag_set(st, RRDSET_FLAG_SYNC_CLOCK);
685 rrdset_flag_clear(st, RRDSET_FLAG_UPSTREAM_EXPOSED);
692 - if (!is_archived && rrdset_flag_check(st, RRDSET_FLAG_ARCHIVED)) {
693 - rrdset_flag_clear(st, RRDSET_FLAG_ARCHIVED);
694 - }
686 return st;
687 }
688
@@ -821,8 +812,6 @@ RRDSET *rrdset_create_custom(
812 else
813 st->rrd_memory_mode = (memory_mode == RRD_MEMORY_MODE_NONE) ? RRD_MEMORY_MODE_NONE : RRD_MEMORY_MODE_ALLOC;
814 }
824 - if (is_archived)
825 - rrdset_flag_set(st, RRDSET_FLAG_ARCHIVED);
815
816 st->plugin_name = plugin?strdupz(plugin):NULL;
817 st->module_name = module?strdupz(module):NULL;
@@ -915,7 +904,7 @@ RRDSET *rrdset_create_custom(
904 st->next = host->rrdset_root;
905 host->rrdset_root = st;
906
918 - if(host->health_enabled && !is_archived) {
907 + if(host->health_enabled) {
908 rrdsetvar_create(st, "last_collected_t", RRDVAR_TYPE_TIME_T, &st->last_collected_time.tv_sec, RRDVAR_OPTION_DEFAULT);
909 rrdsetvar_create(st, "collected_total_raw", RRDVAR_TYPE_TOTAL, &st->last_collected_total, RRDVAR_OPTION_DEFAULT);
910 rrdsetvar_create(st, "green", RRDVAR_TYPE_CALCULATED, &st->green, RRDVAR_OPTION_DEFAULT);
@@ -926,33 +915,20 @@ RRDSET *rrdset_create_custom(
915 if(unlikely(rrdset_index_add(host, st) != st))
916 error("RRDSET: INTERNAL ERROR: attempt to index duplicate chart '%s'", st->id);
917
929 - if (!is_archived) {
930 - rrdsetcalc_link_matching(st);
931 - rrdcalctemplate_link_matching(st);
932 - }
918 + rrdsetcalc_link_matching(st);
919 + rrdcalctemplate_link_matching(st);
920 #ifdef ENABLE_DBENGINE
921 if (st->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE) {
935 - int replace_instead_of_generate = 0;
922 + st->chart_uuid = find_chart_uuid(host, type, id, name);
923 + if (unlikely(!st->chart_uuid))
924 + st->chart_uuid = create_chart_uuid(st, id, name);
925
937 - st->chart_uuid = callocz(1, sizeof(uuid_t));
938 - if (NULL != chart_uuid) {
939 - replace_instead_of_generate = 1;
940 - uuid_copy(*st->chart_uuid, *chart_uuid);
941 - }
942 - if (unlikely(
943 - find_or_generate_guid((void *) st, st->chart_uuid, GUID_TYPE_CHART, replace_instead_of_generate))) {
944 - errno = 0;
945 - error("FAILED to generate GUID for %s", st->id);
946 - freez(st->chart_uuid);
947 - st->chart_uuid = NULL;
948 - fatal_assert(0);
949 - }
926 + store_active_chart(st->chart_uuid);
927 st->compaction_id = 0;
928 }
929 #endif
930
954 - if (!is_archived)
955 - rrdhost_cleanup_obsolete_charts(host);
931 + rrdhost_cleanup_obsolete_charts(host);
932
933 rrdhost_unlock(host);
934 #ifdef ENABLE_ACLK
@@ -961,11 +937,6 @@ RRDSET *rrdset_create_custom(
937 aclk_update_chart(host, st->id, ACLK_CMD_CHART);
938 }
939 #endif
964 -#ifdef ENABLE_DBENGINE
965 - metalog_upd_objcount(host, 1);
966 - metalog_commit_update_chart(st);
967 -#endif
968 -
940 return(st);
941 }
942
@@ -1898,7 +1869,7 @@ after_second_database_work:
1869 uint8_t can_delete_metric = rd->state->collect_ops.finalize(rd);
1870 if (can_delete_metric) {
1871 /* This metric has no data and no references */
1901 - metalog_commit_delete_dimension(rd);
1872 + delete_dimension_uuid(rd->state->metric_uuid);
1873 } else {
1874 /* Do not delete this dimension */
1875 last = rd;
database/sqlite/sqlite3.c new
+230536
@@ -0,0 +1,230536 @@
1 +/******************************************************************************
2 +** This file is an amalgamation of many separate C source files from SQLite
3 +** version 3.33.0. By combining all the individual C code files into this
4 +** single large file, the entire code can be compiled as a single translation
5 +** unit. This allows many compilers to do optimizations that would not be
6 +** possible if the files were compiled separately. Performance improvements
7 +** of 5% or more are commonly seen when SQLite is compiled as a single
8 +** translation unit.
9 +**
10 +** This file is all you need to compile SQLite. To use SQLite in other
11 +** programs, you need this file and the "sqlite3.h" header file that defines
12 +** the programming interface to the SQLite library. (If you do not have
13 +** the "sqlite3.h" header file at hand, you will find a copy embedded within
14 +** the text of this file. Search for "Begin file sqlite3.h" to find the start
15 +** of the embedded sqlite3.h header file.) Additional code files may be needed
16 +** if you want a wrapper to interface SQLite with your choice of programming
17 +** language. The code for the "sqlite3" command-line shell is also in a
18 +** separate file. This file contains only code for the core SQLite library.
19 +*/
20 +#define __maybe_unused __attribute__((unused))
21 +#define SQLITE_CORE 1
22 +#define SQLITE_AMALGAMATION 1
23 +#ifndef SQLITE_PRIVATE
24 +# define SQLITE_PRIVATE static
25 +#endif
26 +/************** Begin file ctime.c *******************************************/
27 +/*
28 +** 2010 February 23
29 +**
30 +** The author disclaims copyright to this source code. In place of
31 +** a legal notice, here is a blessing:
32 +**
33 +** May you do good and not evil.
34 +** May you find forgiveness for yourself and forgive others.
35 +** May you share freely, never taking more than you give.
36 +**
37 +*************************************************************************
38 +**
39 +** This file implements routines used to report what compile-time options
40 +** SQLite was built with.
41 +*/
42 +#define SQLITE_ENABLE_UPDATE_DELETE_LIMIT 1
43 +#define SQLITE_OMIT_LOAD_EXTENSION 1
44 +#define SQLITE_ENABLE_DBSTAT_VTAB 1
45 +#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS /* IMP: R-16824-07538 */
46 +
47 +/*
48 +** Include the configuration header output by 'configure' if we're using the
49 +** autoconf-based build
50 +*/
51 +#if defined(_HAVE_SQLITE_CONFIG_H) && !defined(SQLITECONFIG_H)
52 +#include "config.h"
53 +#define SQLITECONFIG_H 1
54 +#endif
55 +
56 +/* These macros are provided to "stringify" the value of the define
57 +** for those options in which the value is meaningful. */
58 +#define CTIMEOPT_VAL_(opt) #opt
59 +#define CTIMEOPT_VAL(opt) CTIMEOPT_VAL_(opt)
60 +
61 +/* Like CTIMEOPT_VAL, but especially for SQLITE_DEFAULT_LOOKASIDE. This
62 +** option requires a separate macro because legal values contain a single
63 +** comma. e.g. (-DSQLITE_DEFAULT_LOOKASIDE="100,100") */
64 +#define CTIMEOPT_VAL2_(opt1,opt2) #opt1 "," #opt2
65 +#define CTIMEOPT_VAL2(opt) CTIMEOPT_VAL2_(opt)
66 +
67 +/*
68 +** An array of names of all compile-time options. This array should
69 +** be sorted A-Z.
70 +**
71 +** This array looks large, but in a typical installation actually uses
72 +** only a handful of compile-time options, so most times this array is usually
73 +** rather short and uses little memory space.
74 +*/
75 +static const char * const sqlite3azCompileOpt[] = {
76 +
77 +/*
78 +** BEGIN CODE GENERATED BY tool/mkctime.tcl
79 +*/
80 +#if SQLITE_32BIT_ROWID
81 + "32BIT_ROWID",
82 +#endif
83 +#if SQLITE_4_BYTE_ALIGNED_MALLOC
84 + "4_BYTE_ALIGNED_MALLOC",
85 +#endif
86 +#if SQLITE_64BIT_STATS
87 + "64BIT_STATS",
88 +#endif
89 +#if SQLITE_ALLOW_COVERING_INDEX_SCAN
90 + "ALLOW_COVERING_INDEX_SCAN",
91 +#endif
92 +#if SQLITE_ALLOW_URI_AUTHORITY
93 + "ALLOW_URI_AUTHORITY",
94 +#endif
95 +#ifdef SQLITE_BITMASK_TYPE
96 + "BITMASK_TYPE=" CTIMEOPT_VAL(SQLITE_BITMASK_TYPE),
97 +#endif
98 +#if SQLITE_BUG_COMPATIBLE_20160819
99 + "BUG_COMPATIBLE_20160819",
100 +#endif
101 +#if SQLITE_CASE_SENSITIVE_LIKE
102 + "CASE_SENSITIVE_LIKE",
103 +#endif
104 +#if SQLITE_CHECK_PAGES
105 + "CHECK_PAGES",
106 +#endif
107 +#if defined(__clang__) && defined(__clang_major__)
108 + "COMPILER=clang-" CTIMEOPT_VAL(__clang_major__) "."
109 + CTIMEOPT_VAL(__clang_minor__) "."
110 + CTIMEOPT_VAL(__clang_patchlevel__),
111 +#elif defined(_MSC_VER)
112 + "COMPILER=msvc-" CTIMEOPT_VAL(_MSC_VER),
113 +#elif defined(__GNUC__) && defined(__VERSION__)
114 + "COMPILER=gcc-" __VERSION__,
115 +#endif
116 +#if SQLITE_COVERAGE_TEST
117 + "COVERAGE_TEST",
118 +#endif
119 +#if SQLITE_DEBUG
120 + "DEBUG",
121 +#endif
122 +#if SQLITE_DEFAULT_AUTOMATIC_INDEX
123 + "DEFAULT_AUTOMATIC_INDEX",
124 +#endif
125 +#if SQLITE_DEFAULT_AUTOVACUUM
126 + "DEFAULT_AUTOVACUUM",
127 +#endif
128 +#ifdef SQLITE_DEFAULT_CACHE_SIZE
129 + "DEFAULT_CACHE_SIZE=" CTIMEOPT_VAL(SQLITE_DEFAULT_CACHE_SIZE),
130 +#endif
131 +#if SQLITE_DEFAULT_CKPTFULLFSYNC
132 + "DEFAULT_CKPTFULLFSYNC",
133 +#endif
134 +#ifdef SQLITE_DEFAULT_FILE_FORMAT
135 + "DEFAULT_FILE_FORMAT=" CTIMEOPT_VAL(SQLITE_DEFAULT_FILE_FORMAT),
136 +#endif
137 +#ifdef SQLITE_DEFAULT_FILE_PERMISSIONS
138 + "DEFAULT_FILE_PERMISSIONS=" CTIMEOPT_VAL(SQLITE_DEFAULT_FILE_PERMISSIONS),
139 +#endif
140 +#if SQLITE_DEFAULT_FOREIGN_KEYS
141 + "DEFAULT_FOREIGN_KEYS",
142 +#endif
143 +#ifdef SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT
144 + "DEFAULT_JOURNAL_SIZE_LIMIT=" CTIMEOPT_VAL(SQLITE_DEFAULT_JOURNAL_SIZE_LIMIT),
145 +#endif
146 +#ifdef SQLITE_DEFAULT_LOCKING_MODE
147 + "DEFAULT_LOCKING_MODE=" CTIMEOPT_VAL(SQLITE_DEFAULT_LOCKING_MODE),
148 +#endif
149 +#ifdef SQLITE_DEFAULT_LOOKASIDE
150 + "DEFAULT_LOOKASIDE=" CTIMEOPT_VAL2(SQLITE_DEFAULT_LOOKASIDE),
151 +#endif
152 +#if SQLITE_DEFAULT_MEMSTATUS
153 + "DEFAULT_MEMSTATUS",
154 +#endif
155 +#ifdef SQLITE_DEFAULT_MMAP_SIZE
156 + "DEFAULT_MMAP_SIZE=" CTIMEOPT_VAL(SQLITE_DEFAULT_MMAP_SIZE),
157 +#endif
158 +#ifdef SQLITE_DEFAULT_PAGE_SIZE
159 + "DEFAULT_PAGE_SIZE=" CTIMEOPT_VAL(SQLITE_DEFAULT_PAGE_SIZE),
160 +#endif
161 +#ifdef SQLITE_DEFAULT_PCACHE_INITSZ
162 + "DEFAULT_PCACHE_INITSZ=" CTIMEOPT_VAL(SQLITE_DEFAULT_PCACHE_INITSZ),
163 +#endif
164 +#ifdef SQLITE_DEFAULT_PROXYDIR_PERMISSIONS
165 + "DEFAULT_PROXYDIR_PERMISSIONS=" CTIMEOPT_VAL(SQLITE_DEFAULT_PROXYDIR_PERMISSIONS),
166 +#endif
167 +#if SQLITE_DEFAULT_RECURSIVE_TRIGGERS
168 + "DEFAULT_RECURSIVE_TRIGGERS",
169 +#endif
170 +#ifdef SQLITE_DEFAULT_ROWEST
171 + "DEFAULT_ROWEST=" CTIMEOPT_VAL(SQLITE_DEFAULT_ROWEST),
172 +#endif
173 +#ifdef SQLITE_DEFAULT_SECTOR_SIZE
174 + "DEFAULT_SECTOR_SIZE=" CTIMEOPT_VAL(SQLITE_DEFAULT_SECTOR_SIZE),
175 +#endif
176 +#ifdef SQLITE_DEFAULT_SYNCHRONOUS
177 + "DEFAULT_SYNCHRONOUS=" CTIMEOPT_VAL(SQLITE_DEFAULT_SYNCHRONOUS),
178 +#endif
179 +#ifdef SQLITE_DEFAULT_WAL_AUTOCHECKPOINT
180 + "DEFAULT_WAL_AUTOCHECKPOINT=" CTIMEOPT_VAL(SQLITE_DEFAULT_WAL_AUTOCHECKPOINT),
181 +#endif
182 +#ifdef SQLITE_DEFAULT_WAL_SYNCHRONOUS
183 + "DEFAULT_WAL_SYNCHRONOUS=" CTIMEOPT_VAL(SQLITE_DEFAULT_WAL_SYNCHRONOUS),
184 +#endif
185 +#ifdef SQLITE_DEFAULT_WORKER_THREADS
186 + "DEFAULT_WORKER_THREADS=" CTIMEOPT_VAL(SQLITE_DEFAULT_WORKER_THREADS),
187 +#endif
188 +#if SQLITE_DIRECT_OVERFLOW_READ
189 + "DIRECT_OVERFLOW_READ",
190 +#endif
191 +#if SQLITE_DISABLE_DIRSYNC
192 + "DISABLE_DIRSYNC",
193 +#endif
194 +#if SQLITE_DISABLE_FTS3_UNICODE
195 + "DISABLE_FTS3_UNICODE",
196 +#endif
197 +#if SQLITE_DISABLE_FTS4_DEFERRED
198 + "DISABLE_FTS4_DEFERRED",
199 +#endif
200 +#if SQLITE_DISABLE_INTRINSIC
201 + "DISABLE_INTRINSIC",
202 +#endif
203 +#if SQLITE_DISABLE_LFS
204 + "DISABLE_LFS",
205 +#endif
206 +#if SQLITE_DISABLE_PAGECACHE_OVERFLOW_STATS
207 + "DISABLE_PAGECACHE_OVERFLOW_STATS",
208 +#endif
209 +#if SQLITE_DISABLE_SKIPAHEAD_DISTINCT
210 + "DISABLE_SKIPAHEAD_DISTINCT",
211 +#endif
212 +#ifdef SQLITE_ENABLE_8_3_NAMES
213 + "ENABLE_8_3_NAMES=" CTIMEOPT_VAL(SQLITE_ENABLE_8_3_NAMES),
214 +#endif
215 +#if SQLITE_ENABLE_API_ARMOR
216 + "ENABLE_API_ARMOR",
217 +#endif
218 +#if SQLITE_ENABLE_ATOMIC_WRITE
219 + "ENABLE_ATOMIC_WRITE",
220 +#endif
221 +#if SQLITE_ENABLE_BATCH_ATOMIC_WRITE
222 + "ENABLE_BATCH_ATOMIC_WRITE",
223 +#endif
224 +#if SQLITE_ENABLE_BYTECODE_VTAB
225 + "ENABLE_BYTECODE_VTAB",
226 +#endif
227 +#if SQLITE_ENABLE_CEROD
228 + "ENABLE_CEROD=" CTIMEOPT_VAL(SQLITE_ENABLE_CEROD),
229 +#endif
230 +#if SQLITE_ENABLE_COLUMN_METADATA
231 + "ENABLE_COLUMN_METADATA",
232 +#endif
233 +#if SQLITE_ENABLE_COLUMN_USED_MASK
234 + "ENABLE_COLUMN_USED_MASK",
235 +#endif
236 +#if SQLITE_ENABLE_COSTMULT
237 + "ENABLE_COSTMULT",
238 +#endif
239 +#if SQLITE_ENABLE_CURSOR_HINTS
240 + "ENABLE_CURSOR_HINTS",
241 +#endif
242 +#if SQLITE_ENABLE_DBSTAT_VTAB
243 + "ENABLE_DBSTAT_VTAB",
244 +#endif
245 +#if SQLITE_ENABLE_EXPENSIVE_ASSERT
246 + "ENABLE_EXPENSIVE_ASSERT",
247 +#endif
248 +#if SQLITE_ENABLE_FTS1
249 + "ENABLE_FTS1",
250 +#endif
251 +#if SQLITE_ENABLE_FTS2
252 + "ENABLE_FTS2",
253 +#endif
254 +#if SQLITE_ENABLE_FTS3
255 + "ENABLE_FTS3",
256 +#endif
257 +#if SQLITE_ENABLE_FTS3_PARENTHESIS
258 + "ENABLE_FTS3_PARENTHESIS",
259 +#endif
260 +#if SQLITE_ENABLE_FTS3_TOKENIZER
261 + "ENABLE_FTS3_TOKENIZER",
262 +#endif
263 +#if SQLITE_ENABLE_FTS4
264 + "ENABLE_FTS4",
265 +#endif
266 +#if SQLITE_ENABLE_FTS5
267 + "ENABLE_FTS5",
268 +#endif
269 +#if SQLITE_ENABLE_GEOPOLY
270 + "ENABLE_GEOPOLY",
271 +#endif
272 +#if SQLITE_ENABLE_HIDDEN_COLUMNS
273 + "ENABLE_HIDDEN_COLUMNS",
274 +#endif
275 +#if SQLITE_ENABLE_ICU
276 + "ENABLE_ICU",
277 +#endif
278 +#if SQLITE_ENABLE_IOTRACE
279 + "ENABLE_IOTRACE",
280 +#endif
281 +#if SQLITE_ENABLE_JSON1
282 + "ENABLE_JSON1",
283 +#endif
284 +#if SQLITE_ENABLE_LOAD_EXTENSION
285 + "ENABLE_LOAD_EXTENSION",
286 +#endif
287 +#ifdef SQLITE_ENABLE_LOCKING_STYLE
288 + "ENABLE_LOCKING_STYLE=" CTIMEOPT_VAL(SQLITE_ENABLE_LOCKING_STYLE),
289 +#endif
290 +#if SQLITE_ENABLE_MEMORY_MANAGEMENT
291 + "ENABLE_MEMORY_MANAGEMENT",
292 +#endif
293 +#if SQLITE_ENABLE_MEMSYS3
294 + "ENABLE_MEMSYS3",
295 +#endif
296 +#if SQLITE_ENABLE_MEMSYS5
297 + "ENABLE_MEMSYS5",
298 +#endif
299 +#if SQLITE_ENABLE_MULTIPLEX
300 + "ENABLE_MULTIPLEX",
301 +#endif
302 +#if SQLITE_ENABLE_NORMALIZE
303 + "ENABLE_NORMALIZE",
304 +#endif
305 +#if SQLITE_ENABLE_NULL_TRIM
306 + "ENABLE_NULL_TRIM",
307 +#endif
308 +#if SQLITE_ENABLE_OVERSIZE_CELL_CHECK
309 + "ENABLE_OVERSIZE_CELL_CHECK",
310 +#endif
311 +#if SQLITE_ENABLE_PREUPDATE_HOOK
312 + "ENABLE_PREUPDATE_HOOK",
313 +#endif
314 +#if SQLITE_ENABLE_QPSG
315 + "ENABLE_QPSG",
316 +#endif
317 +#if SQLITE_ENABLE_RBU
318 + "ENABLE_RBU",
319 +#endif
320 +#if SQLITE_ENABLE_RTREE
321 + "ENABLE_RTREE",
322 +#endif
323 +#if SQLITE_ENABLE_SELECTTRACE
324 + "ENABLE_SELECTTRACE",
325 +#endif
326 +#if SQLITE_ENABLE_SESSION
327 + "ENABLE_SESSION",
328 +#endif
329 +#if SQLITE_ENABLE_SNAPSHOT
330 + "ENABLE_SNAPSHOT",
331 +#endif
332 +#if SQLITE_ENABLE_SORTER_REFERENCES
333 + "ENABLE_SORTER_REFERENCES",
334 +#endif
335 +#if SQLITE_ENABLE_SQLLOG
336 + "ENABLE_SQLLOG",
337 +#endif
338 +#if defined(SQLITE_ENABLE_STAT4)
339 + "ENABLE_STAT4",
340 +#endif
341 +#if SQLITE_ENABLE_STMTVTAB
342 + "ENABLE_STMTVTAB",
343 +#endif
344 +#if SQLITE_ENABLE_STMT_SCANSTATUS
345 + "ENABLE_STMT_SCANSTATUS",
346 +#endif
347 +#if SQLITE_ENABLE_UNKNOWN_SQL_FUNCTION
348 + "ENABLE_UNKNOWN_SQL_FUNCTION",
349 +#endif
350 +#if SQLITE_ENABLE_UNLOCK_NOTIFY
351 + "ENABLE_UNLOCK_NOTIFY",
352 +#endif
353 +#if SQLITE_ENABLE_UPDATE_DELETE_LIMIT
354 + "ENABLE_UPDATE_DELETE_LIMIT",
355 +#endif
356 +#if SQLITE_ENABLE_URI_00_ERROR
357 + "ENABLE_URI_00_ERROR",
358 +#endif
359 +#if SQLITE_ENABLE_VFSTRACE
360 + "ENABLE_VFSTRACE",
361 +#endif
362 +#if SQLITE_ENABLE_WHERETRACE
363 + "ENABLE_WHERETRACE",
364 +#endif
365 +#if SQLITE_ENABLE_ZIPVFS
366 + "ENABLE_ZIPVFS",
367 +#endif
368 +#if SQLITE_EXPLAIN_ESTIMATED_ROWS
369 + "EXPLAIN_ESTIMATED_ROWS",
370 +#endif
371 +#if SQLITE_EXTRA_IFNULLROW
372 + "EXTRA_IFNULLROW",
373 +#endif
374 +#ifdef SQLITE_EXTRA_INIT
375 + "EXTRA_INIT=" CTIMEOPT_VAL(SQLITE_EXTRA_INIT),
376 +#endif
377 +#ifdef SQLITE_EXTRA_SHUTDOWN
378 + "EXTRA_SHUTDOWN=" CTIMEOPT_VAL(SQLITE_EXTRA_SHUTDOWN),
379 +#endif
380 +#ifdef SQLITE_FTS3_MAX_EXPR_DEPTH
381 + "FTS3_MAX_EXPR_DEPTH=" CTIMEOPT_VAL(SQLITE_FTS3_MAX_EXPR_DEPTH),
382 +#endif
383 +#if SQLITE_FTS5_ENABLE_TEST_MI
384 + "FTS5_ENABLE_TEST_MI",
385 +#endif
386 +#if SQLITE_FTS5_NO_WITHOUT_ROWID
387 + "FTS5_NO_WITHOUT_ROWID",
388 +#endif
389 +#if HAVE_ISNAN || SQLITE_HAVE_ISNAN
390 + "HAVE_ISNAN",
391 +#endif
392 +#if SQLITE_HOMEGROWN_RECURSIVE_MUTEX
393 + "HOMEGROWN_RECURSIVE_MUTEX",
394 +#endif
395 +#if SQLITE_IGNORE_AFP_LOCK_ERRORS
396 + "IGNORE_AFP_LOCK_ERRORS",
397 +#endif
398 +#if SQLITE_IGNORE_FLOCK_LOCK_ERRORS
399 + "IGNORE_FLOCK_LOCK_ERRORS",
400 +#endif
401 +#if SQLITE_INLINE_MEMCPY
402 + "INLINE_MEMCPY",
403 +#endif
404 +#if SQLITE_INT64_TYPE
405 + "INT64_TYPE",
406 +#endif
407 +#ifdef SQLITE_INTEGRITY_CHECK_ERROR_MAX
408 + "INTEGRITY_CHECK_ERROR_MAX=" CTIMEOPT_VAL(SQLITE_INTEGRITY_CHECK_ERROR_MAX),
409 +#endif
410 +#if SQLITE_LIKE_DOESNT_MATCH_BLOBS
411 + "LIKE_DOESNT_MATCH_BLOBS",
412 +#endif
413 +#if SQLITE_LOCK_TRACE
414 + "LOCK_TRACE",
415 +#endif
416 +#if SQLITE_LOG_CACHE_SPILL
417 + "LOG_CACHE_SPILL",
418 +#endif
419 +#ifdef SQLITE_MALLOC_SOFT_LIMIT
420 + "MALLOC_SOFT_LIMIT=" CTIMEOPT_VAL(SQLITE_MALLOC_SOFT_LIMIT),
421 +#endif
422 +#ifdef SQLITE_MAX_ATTACHED
423 + "MAX_ATTACHED=" CTIMEOPT_VAL(SQLITE_MAX_ATTACHED),
424 +#endif
425 +#ifdef SQLITE_MAX_COLUMN
426 + "MAX_COLUMN=" CTIMEOPT_VAL(SQLITE_MAX_COLUMN),
427 +#endif
428 +#ifdef SQLITE_MAX_COMPOUND_SELECT
429 + "MAX_COMPOUND_SELECT=" CTIMEOPT_VAL(SQLITE_MAX_COMPOUND_SELECT),
430 +#endif
431 +#ifdef SQLITE_MAX_DEFAULT_PAGE_SIZE
432 + "MAX_DEFAULT_PAGE_SIZE=" CTIMEOPT_VAL(SQLITE_MAX_DEFAULT_PAGE_SIZE),
433 +#endif
434 +#ifdef SQLITE_MAX_EXPR_DEPTH
435 + "MAX_EXPR_DEPTH=" CTIMEOPT_VAL(SQLITE_MAX_EXPR_DEPTH),
436 +#endif
437 +#ifdef SQLITE_MAX_FUNCTION_ARG
438 + "MAX_FUNCTION_ARG=" CTIMEOPT_VAL(SQLITE_MAX_FUNCTION_ARG),
439 +#endif
440 +#ifdef SQLITE_MAX_LENGTH
441 + "MAX_LENGTH=" CTIMEOPT_VAL(SQLITE_MAX_LENGTH),
442 +#endif
443 +#ifdef SQLITE_MAX_LIKE_PATTERN_LENGTH
444 + "MAX_LIKE_PATTERN_LENGTH=" CTIMEOPT_VAL(SQLITE_MAX_LIKE_PATTERN_LENGTH),
445 +#endif
446 +#ifdef SQLITE_MAX_MEMORY
447 + "MAX_MEMORY=" CTIMEOPT_VAL(SQLITE_MAX_MEMORY),
448 +#endif
449 +#ifdef SQLITE_MAX_MMAP_SIZE
450 + "MAX_MMAP_SIZE=" CTIMEOPT_VAL(SQLITE_MAX_MMAP_SIZE),
451 +#endif
452 +#ifdef SQLITE_MAX_MMAP_SIZE_
453 + "MAX_MMAP_SIZE_=" CTIMEOPT_VAL(SQLITE_MAX_MMAP_SIZE_),
454 +#endif
455 +#ifdef SQLITE_MAX_PAGE_COUNT
456 + "MAX_PAGE_COUNT=" CTIMEOPT_VAL(SQLITE_MAX_PAGE_COUNT),
457 +#endif
458 +#ifdef SQLITE_MAX_PAGE_SIZE
459 + "MAX_PAGE_SIZE=" CTIMEOPT_VAL(SQLITE_MAX_PAGE_SIZE),
460 +#endif
461 +#ifdef SQLITE_MAX_SCHEMA_RETRY
462 + "MAX_SCHEMA_RETRY=" CTIMEOPT_VAL(SQLITE_MAX_SCHEMA_RETRY),
463 +#endif
464 +#ifdef SQLITE_MAX_SQL_LENGTH
465 + "MAX_SQL_LENGTH=" CTIMEOPT_VAL(SQLITE_MAX_SQL_LENGTH),
466 +#endif
467 +#ifdef SQLITE_MAX_TRIGGER_DEPTH
468 + "MAX_TRIGGER_DEPTH=" CTIMEOPT_VAL(SQLITE_MAX_TRIGGER_DEPTH),
469 +#endif
470 +#ifdef SQLITE_MAX_VARIABLE_NUMBER
471 + "MAX_VARIABLE_NUMBER=" CTIMEOPT_VAL(SQLITE_MAX_VARIABLE_NUMBER),
472 +#endif
473 +#ifdef SQLITE_MAX_VDBE_OP
474 + "MAX_VDBE_OP=" CTIMEOPT_VAL(SQLITE_MAX_VDBE_OP),
475 +#endif
476 +#ifdef SQLITE_MAX_WORKER_THREADS
477 + "MAX_WORKER_THREADS=" CTIMEOPT_VAL(SQLITE_MAX_WORKER_THREADS),
478 +#endif
479 +#if SQLITE_MEMDEBUG
480 + "MEMDEBUG",
481 +#endif
482 +#if SQLITE_MIXED_ENDIAN_64BIT_FLOAT
483 + "MIXED_ENDIAN_64BIT_FLOAT",
484 +#endif
485 +#if SQLITE_MMAP_READWRITE
486 + "MMAP_READWRITE",
487 +#endif
488 +#if SQLITE_MUTEX_NOOP
489 + "MUTEX_NOOP",
490 +#endif
491 +#if SQLITE_MUTEX_NREF
492 + "MUTEX_NREF",
493 +#endif
494 +#if SQLITE_MUTEX_OMIT
495 + "MUTEX_OMIT",
496 +#endif
497 +#if SQLITE_MUTEX_PTHREADS
498 + "MUTEX_PTHREADS",
499 +#endif
500 +#if SQLITE_MUTEX_W32
501 + "MUTEX_W32",
502 +#endif
503 +#if SQLITE_NEED_ERR_NAME
504 + "NEED_ERR_NAME",
505 +#endif
506 +#if SQLITE_NOINLINE
507 + "NOINLINE",
508 +#endif
509 +#if SQLITE_NO_SYNC
510 + "NO_SYNC",
511 +#endif
512 +#if SQLITE_OMIT_ALTERTABLE
513 + "OMIT_ALTERTABLE",
514 +#endif
515 +#if SQLITE_OMIT_ANALYZE
516 + "OMIT_ANALYZE",
517 +#endif
518 +#if SQLITE_OMIT_ATTACH
519 + "OMIT_ATTACH",
520 +#endif
521 +#if SQLITE_OMIT_AUTHORIZATION
522 + "OMIT_AUTHORIZATION",
523 +#endif
524 +#if SQLITE_OMIT_AUTOINCREMENT
525 + "OMIT_AUTOINCREMENT",
526 +#endif
527 +#if SQLITE_OMIT_AUTOINIT
528 + "OMIT_AUTOINIT",
529 +#endif
530 +#if SQLITE_OMIT_AUTOMATIC_INDEX
531 + "OMIT_AUTOMATIC_INDEX",
532 +#endif
533 +#if SQLITE_OMIT_AUTORESET
534 + "OMIT_AUTORESET",
535 +#endif
536 +#if SQLITE_OMIT_AUTOVACUUM
537 + "OMIT_AUTOVACUUM",
538 +#endif
539 +#if SQLITE_OMIT_BETWEEN_OPTIMIZATION
540 + "OMIT_BETWEEN_OPTIMIZATION",
541 +#endif
542 +#if SQLITE_OMIT_BLOB_LITERAL
543 + "OMIT_BLOB_LITERAL",
544 +#endif
545 +#if SQLITE_OMIT_CAST
546 + "OMIT_CAST",
547 +#endif
548 +#if SQLITE_OMIT_CHECK
549 + "OMIT_CHECK",
550 +#endif
551 +#if SQLITE_OMIT_COMPLETE
552 + "OMIT_COMPLETE",
553 +#endif
554 +#if SQLITE_OMIT_COMPOUND_SELECT
555 + "OMIT_COMPOUND_SELECT",
556 +#endif
557 +#if SQLITE_OMIT_CONFLICT_CLAUSE
558 + "OMIT_CONFLICT_CLAUSE",
559 +#endif
560 +#if SQLITE_OMIT_CTE
561 + "OMIT_CTE",
562 +#endif
563 +#if SQLITE_OMIT_DATETIME_FUNCS
564 + "OMIT_DATETIME_FUNCS",
565 +#endif
566 +#if SQLITE_OMIT_DECLTYPE
567 + "OMIT_DECLTYPE",
568 +#endif
569 +#if SQLITE_OMIT_DEPRECATED
570 + "OMIT_DEPRECATED",
571 +#endif
572 +#if SQLITE_OMIT_DISKIO
573 + "OMIT_DISKIO",
574 +#endif
575 +#if SQLITE_OMIT_EXPLAIN
576 + "OMIT_EXPLAIN",
577 +#endif
578 +#if SQLITE_OMIT_FLAG_PRAGMAS
579 + "OMIT_FLAG_PRAGMAS",
580 +#endif
581 +#if SQLITE_OMIT_FLOATING_POINT
582 + "OMIT_FLOATING_POINT",
583 +#endif
584 +#if SQLITE_OMIT_FOREIGN_KEY
585 + "OMIT_FOREIGN_KEY",
586 +#endif
587 +#if SQLITE_OMIT_GET_TABLE
588 + "OMIT_GET_TABLE",
589 +#endif
590 +#if SQLITE_OMIT_HEX_INTEGER
591 + "OMIT_HEX_INTEGER",
592 +#endif
593 +#if SQLITE_OMIT_INCRBLOB
594 + "OMIT_INCRBLOB",
595 +#endif
596 +#if SQLITE_OMIT_INTEGRITY_CHECK
597 + "OMIT_INTEGRITY_CHECK",
598 +#endif
599 +#if SQLITE_OMIT_LIKE_OPTIMIZATION
600 + "OMIT_LIKE_OPTIMIZATION",
601 +#endif
602 +#if SQLITE_OMIT_LOAD_EXTENSION
603 + "OMIT_LOAD_EXTENSION",
604 +#endif
605 +#if SQLITE_OMIT_LOCALTIME
606 + "OMIT_LOCALTIME",
607 +#endif
608 +#if SQLITE_OMIT_LOOKASIDE
609 + "OMIT_LOOKASIDE",
610 +#endif
611 +#if SQLITE_OMIT_MEMORYDB
612 + "OMIT_MEMORYDB",
613 +#endif
614 +#if SQLITE_OMIT_OR_OPTIMIZATION
615 + "OMIT_OR_OPTIMIZATION",
616 +#endif
617 +#if SQLITE_OMIT_PAGER_PRAGMAS
618 + "OMIT_PAGER_PRAGMAS",
619 +#endif
620 +#if SQLITE_OMIT_PARSER_TRACE
621 + "OMIT_PARSER_TRACE",
622 +#endif
623 +#if SQLITE_OMIT_POPEN
624 + "OMIT_POPEN",
625 +#endif
626 +#if SQLITE_OMIT_PRAGMA
627 + "OMIT_PRAGMA",
628 +#endif
629 +#if SQLITE_OMIT_PROGRESS_CALLBACK
630 + "OMIT_PROGRESS_CALLBACK",
631 +#endif
632 +#if SQLITE_OMIT_QUICKBALANCE
633 + "OMIT_QUICKBALANCE",
634 +#endif
635 +#if SQLITE_OMIT_REINDEX
636 + "OMIT_REINDEX",
637 +#endif
638 +#if SQLITE_OMIT_SCHEMA_PRAGMAS
639 + "OMIT_SCHEMA_PRAGMAS",
640 +#endif
641 +#if SQLITE_OMIT_SCHEMA_VERSION_PRAGMAS
642 + "OMIT_SCHEMA_VERSION_PRAGMAS",
643 +#endif
644 +#if SQLITE_OMIT_SHARED_CACHE
645 + "OMIT_SHARED_CACHE",
646 +#endif
647 +#if SQLITE_OMIT_SHUTDOWN_DIRECTORIES
648 + "OMIT_SHUTDOWN_DIRECTORIES",
649 +#endif
650 +#if SQLITE_OMIT_SUBQUERY
651 + "OMIT_SUBQUERY",
652 +#endif
653 +#if SQLITE_OMIT_TCL_VARIABLE
654 + "OMIT_TCL_VARIABLE",
655 +#endif
656 +#if SQLITE_OMIT_TEMPDB
657 + "OMIT_TEMPDB",
658 +#endif
659 +#if SQLITE_OMIT_TEST_CONTROL
660 + "OMIT_TEST_CONTROL",
661 +#endif
662 +#if SQLITE_OMIT_TRACE
663 + "OMIT_TRACE",
664 +#endif
665 +#if SQLITE_OMIT_TRIGGER
666 + "OMIT_TRIGGER",
667 +#endif
668 +#if SQLITE_OMIT_TRUNCATE_OPTIMIZATION
669 + "OMIT_TRUNCATE_OPTIMIZATION",
670 +#endif
671 +#if SQLITE_OMIT_UTF16
672 + "OMIT_UTF16",
673 +#endif
674 +#if SQLITE_OMIT_VACUUM
675 + "OMIT_VACUUM",
676 +#endif
677 +#if SQLITE_OMIT_VIEW
678 + "OMIT_VIEW",
679 +#endif
680 +#if SQLITE_OMIT_VIRTUALTABLE
681 + "OMIT_VIRTUALTABLE",
682 +#endif
683 +#if SQLITE_OMIT_WAL
684 + "OMIT_WAL",
685 +#endif
686 +#if SQLITE_OMIT_WSD
687 + "OMIT_WSD",
688 +#endif
689 +#if SQLITE_OMIT_XFER_OPT
690 + "OMIT_XFER_OPT",
691 +#endif
692 +#if SQLITE_PCACHE_SEPARATE_HEADER
693 + "PCACHE_SEPARATE_HEADER",
694 +#endif
695 +#if SQLITE_PERFORMANCE_TRACE
696 + "PERFORMANCE_TRACE",
697 +#endif
698 +#if SQLITE_POWERSAFE_OVERWRITE
699 + "POWERSAFE_OVERWRITE",
700 +#endif
701 +#if SQLITE_PREFER_PROXY_LOCKING
702 + "PREFER_PROXY_LOCKING",
703 +#endif
704 +#if SQLITE_PROXY_DEBUG
705 + "PROXY_DEBUG",
706 +#endif
707 +#if SQLITE_REVERSE_UNORDERED_SELECTS
708 + "REVERSE_UNORDERED_SELECTS",
709 +#endif
710 +#if SQLITE_RTREE_INT_ONLY
711 + "RTREE_INT_ONLY",
712 +#endif
713 +#if SQLITE_SECURE_DELETE
714 + "SECURE_DELETE",
715 +#endif
716 +#if SQLITE_SMALL_STACK
717 + "SMALL_STACK",
718 +#endif
719 +#ifdef SQLITE_SORTER_PMASZ
720 + "SORTER_PMASZ=" CTIMEOPT_VAL(SQLITE_SORTER_PMASZ),
721 +#endif
722 +#if SQLITE_SOUNDEX
723 + "SOUNDEX",
724 +#endif
725 +#ifdef SQLITE_STAT4_SAMPLES
726 + "STAT4_SAMPLES=" CTIMEOPT_VAL(SQLITE_STAT4_SAMPLES),
727 +#endif
728 +#ifdef SQLITE_STMTJRNL_SPILL
729 + "STMTJRNL_SPILL=" CTIMEOPT_VAL(SQLITE_STMTJRNL_SPILL),
730 +#endif
731 +#if SQLITE_SUBSTR_COMPATIBILITY
732 + "SUBSTR_COMPATIBILITY",
733 +#endif
734 +#if SQLITE_SYSTEM_MALLOC
735 + "SYSTEM_MALLOC",
736 +#endif
737 +#if SQLITE_TCL
738 + "TCL",
739 +#endif
740 +#ifdef SQLITE_TEMP_STORE
741 + "TEMP_STORE=" CTIMEOPT_VAL(SQLITE_TEMP_STORE),
742 +#endif
743 +#if SQLITE_TEST
744 + "TEST",
745 +#endif
746 +#if defined(SQLITE_THREADSAFE)
747 + "THREADSAFE=" CTIMEOPT_VAL(SQLITE_THREADSAFE),
748 +#elif defined(THREADSAFE)
749 + "THREADSAFE=" CTIMEOPT_VAL(THREADSAFE),
750 +#else
751 + "THREADSAFE=1",
752 +#endif
753 +#if SQLITE_UNLINK_AFTER_CLOSE
754 + "UNLINK_AFTER_CLOSE",
755 +#endif
756 +#if SQLITE_UNTESTABLE
757 + "UNTESTABLE",
758 +#endif
759 +#if SQLITE_USER_AUTHENTICATION
760 + "USER_AUTHENTICATION",
761 +#endif
762 +#if SQLITE_USE_ALLOCA
763 + "USE_ALLOCA",
764 +#endif
765 +#if SQLITE_USE_FCNTL_TRACE
766 + "USE_FCNTL_TRACE",
767 +#endif
768 +#if SQLITE_USE_URI
769 + "USE_URI",
770 +#endif
771 +#if SQLITE_VDBE_COVERAGE
772 + "VDBE_COVERAGE",
773 +#endif
774 +#if SQLITE_WIN32_MALLOC
775 + "WIN32_MALLOC",
776 +#endif
777 +#if SQLITE_ZERO_MALLOC
778 + "ZERO_MALLOC",
779 +#endif
780 +/*
781 +** END CODE GENERATED BY tool/mkctime.tcl
782 +*/
783 +};
784 +
785 +SQLITE_PRIVATE const char **sqlite3CompileOptions(int *pnOpt){
786 + *pnOpt = sizeof(sqlite3azCompileOpt) / sizeof(sqlite3azCompileOpt[0]);
787 + return (const char**)sqlite3azCompileOpt;
788 +}
789 +
790 +#endif /* SQLITE_OMIT_COMPILEOPTION_DIAGS */
791 +
792 +/************** End of ctime.c ***********************************************/
793 +/************** Begin file sqliteInt.h ***************************************/
794 +/*
795 +** 2001 September 15
796 +**
797 +** The author disclaims copyright to this source code. In place of
798 +** a legal notice, here is a blessing:
799 +**
800 +** May you do good and not evil.
801 +** May you find forgiveness for yourself and forgive others.
802 +** May you share freely, never taking more than you give.
803 +**
804 +*************************************************************************
805 +** Internal interface definitions for SQLite.
806 +**
807 +*/
808 +#ifndef SQLITEINT_H
809 +#define SQLITEINT_H
810 +
811 +/* Special Comments:
812 +**
813 +** Some comments have special meaning to the tools that measure test
814 +** coverage:
815 +**
816 +** NO_TEST - The branches on this line are not
817 +** measured by branch coverage. This is
818 +** used on lines of code that actually
819 +** implement parts of coverage testing.
820 +**
821 +** OPTIMIZATION-IF-TRUE - This branch is allowed to alway be false
822 +** and the correct answer is still obtained,
823 +** though perhaps more slowly.
824 +**
825 +** OPTIMIZATION-IF-FALSE - This branch is allowed to alway be true
826 +** and the correct answer is still obtained,
827 +** though perhaps more slowly.
828 +**
829 +** PREVENTS-HARMLESS-OVERREAD - This branch prevents a buffer overread
830 +** that would be harmless and undetectable
831 +** if it did occur.
832 +**
833 +** In all cases, the special comment must be enclosed in the usual
834 +** slash-asterisk...asterisk-slash comment marks, with no spaces between the
835 +** asterisks and the comment text.
836 +*/
837 +
838 +/*
839 +** Make sure the Tcl calling convention macro is defined. This macro is
840 +** only used by test code and Tcl integration code.
841 +*/
842 +#ifndef SQLITE_TCLAPI
843 +# define SQLITE_TCLAPI
844 +#endif
845 +
846 +/*
847 +** Include the header file used to customize the compiler options for MSVC.
848 +** This should be done first so that it can successfully prevent spurious
849 +** compiler warnings due to subsequent content in this file and other files
850 +** that are included by this file.
851 +*/
852 +/************** Include msvc.h in the middle of sqliteInt.h ******************/
853 +/************** Begin file msvc.h ********************************************/
854 +/*
855 +** 2015 January 12
856 +**
857 +** The author disclaims copyright to this source code. In place of
858 +** a legal notice, here is a blessing:
859 +**
860 +** May you do good and not evil.
861 +** May you find forgiveness for yourself and forgive others.
862 +** May you share freely, never taking more than you give.
863 +**
864 +******************************************************************************
865 +**
866 +** This file contains code that is specific to MSVC.
867 +*/
868 +#ifndef SQLITE_MSVC_H
869 +#define SQLITE_MSVC_H
870 +
871 +#if defined(_MSC_VER)
872 +#pragma warning(disable : 4054)
873 +#pragma warning(disable : 4055)
874 +#pragma warning(disable : 4100)
875 +#pragma warning(disable : 4127)
876 +#pragma warning(disable : 4130)
877 +#pragma warning(disable : 4152)
878 +#pragma warning(disable : 4189)
879 +#pragma warning(disable : 4206)
880 +#pragma warning(disable : 4210)
881 +#pragma warning(disable : 4232)
882 +#pragma warning(disable : 4244)
883 +#pragma warning(disable : 4305)
884 +#pragma warning(disable : 4306)
885 +#pragma warning(disable : 4702)
886 +#pragma warning(disable : 4706)
887 +#endif /* defined(_MSC_VER) */
888 +
889 +#if defined(_MSC_VER) && !defined(_WIN64)
890 +#undef SQLITE_4_BYTE_ALIGNED_MALLOC
891 +#define SQLITE_4_BYTE_ALIGNED_MALLOC
892 +#endif /* defined(_MSC_VER) && !defined(_WIN64) */
893 +
894 +#endif /* SQLITE_MSVC_H */
895 +
896 +/************** End of msvc.h ************************************************/
897 +/************** Continuing where we left off in sqliteInt.h ******************/
898 +
899 +/*
900 +** Special setup for VxWorks
901 +*/
902 +/************** Include vxworks.h in the middle of sqliteInt.h ***************/
903 +/************** Begin file vxworks.h *****************************************/
904 +/*
905 +** 2015-03-02
906 +**
907 +** The author disclaims copyright to this source code. In place of
908 +** a legal notice, here is a blessing:
909 +**
910 +** May you do good and not evil.
911 +** May you find forgiveness for yourself and forgive others.
912 +** May you share freely, never taking more than you give.
913 +**
914 +******************************************************************************
915 +**
916 +** This file contains code that is specific to Wind River's VxWorks
917 +*/
918 +#if defined(__RTP__) || defined(_WRS_KERNEL)
919 +/* This is VxWorks. Set up things specially for that OS
920 +*/
921 +#include <vxWorks.h>
922 +#include <pthread.h> /* amalgamator: dontcache */
923 +#define OS_VXWORKS 1
924 +#define SQLITE_OS_OTHER 0
925 +#define SQLITE_HOMEGROWN_RECURSIVE_MUTEX 1
926 +#define SQLITE_OMIT_LOAD_EXTENSION 1
927 +#define SQLITE_ENABLE_LOCKING_STYLE 0
928 +#define HAVE_UTIME 1
929 +#else
930 +/* This is not VxWorks. */
931 +#define OS_VXWORKS 0
932 +#define HAVE_FCHOWN 1
933 +#define HAVE_READLINK 1
934 +#define HAVE_LSTAT 1
935 +#endif /* defined(_WRS_KERNEL) */
936 +
937 +/************** End of vxworks.h *********************************************/
938 +/************** Continuing where we left off in sqliteInt.h ******************/
939 +
940 +/*
941 +** These #defines should enable >2GB file support on POSIX if the
942 +** underlying operating system supports it. If the OS lacks
943 +** large file support, or if the OS is windows, these should be no-ops.
944 +**
945 +** Ticket #2739: The _LARGEFILE_SOURCE macro must appear before any
946 +** system #includes. Hence, this block of code must be the very first
947 +** code in all source files.
948 +**
949 +** Large file support can be disabled using the -DSQLITE_DISABLE_LFS switch
950 +** on the compiler command line. This is necessary if you are compiling
951 +** on a recent machine (ex: Red Hat 7.2) but you want your code to work
952 +** on an older machine (ex: Red Hat 6.0). If you compile on Red Hat 7.2
953 +** without this option, LFS is enable. But LFS does not exist in the kernel
954 +** in Red Hat 6.0, so the code won't work. Hence, for maximum binary
955 +** portability you should omit LFS.
956 +**
957 +** The previous paragraph was written in 2005. (This paragraph is written
958 +** on 2008-11-28.) These days, all Linux kernels support large files, so
959 +** you should probably leave LFS enabled. But some embedded platforms might
960 +** lack LFS in which case the SQLITE_DISABLE_LFS macro might still be useful.
961 +**
962 +** Similar is true for Mac OS X. LFS is only supported on Mac OS X 9 and later.
963 +*/
964 +#ifndef SQLITE_DISABLE_LFS
965 +# define _LARGE_FILE 1
966 +# ifndef _FILE_OFFSET_BITS
967 +# define _FILE_OFFSET_BITS 64
968 +# endif
969 +# define _LARGEFILE_SOURCE 1
970 +#endif
971 +
972 +/* The GCC_VERSION and MSVC_VERSION macros are used to
973 +** conditionally include optimizations for each of these compilers. A
974 +** value of 0 means that compiler is not being used. The
975 +** SQLITE_DISABLE_INTRINSIC macro means do not use any compiler-specific
976 +** optimizations, and hence set all compiler macros to 0
977 +**
978 +** There was once also a CLANG_VERSION macro. However, we learn that the
979 +** version numbers in clang are for "marketing" only and are inconsistent
980 +** and unreliable. Fortunately, all versions of clang also recognize the
981 +** gcc version numbers and have reasonable settings for gcc version numbers,
982 +** so the GCC_VERSION macro will be set to a correct non-zero value even
983 +** when compiling with clang.
984 +*/
985 +#if defined(__GNUC__) && !defined(SQLITE_DISABLE_INTRINSIC)
986 +# define GCC_VERSION (__GNUC__*1000000+__GNUC_MINOR__*1000+__GNUC_PATCHLEVEL__)
987 +#else
988 +# define GCC_VERSION 0
989 +#endif
990 +#if defined(_MSC_VER) && !defined(SQLITE_DISABLE_INTRINSIC)
991 +# define MSVC_VERSION _MSC_VER
992 +#else
993 +# define MSVC_VERSION 0
994 +#endif
995 +
996 +/* Needed for various definitions... */
997 +#if defined(__GNUC__) && !defined(_GNU_SOURCE)
998 +# define _GNU_SOURCE
999 +#endif
1000 +
1001 +#if defined(__OpenBSD__) && !defined(_BSD_SOURCE)
1002 +# define _BSD_SOURCE
1003 +#endif
1004 +
1005 +/*
1006 +** Macro to disable warnings about missing "break" at the end of a "case".
1007 +*/
1008 +#if GCC_VERSION>=7000000
1009 +# define deliberate_fall_through __attribute__((fallthrough));
1010 +#else
1011 +# define deliberate_fall_through
1012 +#endif
1013 +
1014 +/*
1015 +** For MinGW, check to see if we can include the header file containing its
1016 +** version information, among other things. Normally, this internal MinGW
1017 +** header file would [only] be included automatically by other MinGW header
1018 +** files; however, the contained version information is now required by this
1019 +** header file to work around binary compatibility issues (see below) and
1020 +** this is the only known way to reliably obtain it. This entire #if block
1021 +** would be completely unnecessary if there was any other way of detecting
1022 +** MinGW via their preprocessor (e.g. if they customized their GCC to define
1023 +** some MinGW-specific macros). When compiling for MinGW, either the
1024 +** _HAVE_MINGW_H or _HAVE__MINGW_H (note the extra underscore) macro must be
1025 +** defined; otherwise, detection of conditions specific to MinGW will be
1026 +** disabled.
1027 +*/
1028 +#if defined(_HAVE_MINGW_H)
1029 +# include "mingw.h"
1030 +#elif defined(_HAVE__MINGW_H)
1031 +# include "_mingw.h"
1032 +#endif
1033 +
1034 +/*
1035 +** For MinGW version 4.x (and higher), check to see if the _USE_32BIT_TIME_T
1036 +** define is required to maintain binary compatibility with the MSVC runtime
1037 +** library in use (e.g. for Windows XP).
1038 +*/
1039 +#if !defined(_USE_32BIT_TIME_T) && !defined(_USE_64BIT_TIME_T) && \
1040 + defined(_WIN32) && !defined(_WIN64) && \
1041 + defined(__MINGW_MAJOR_VERSION) && __MINGW_MAJOR_VERSION >= 4 && \
1042 + defined(__MSVCRT__)
1043 +# define _USE_32BIT_TIME_T
1044 +#endif
1045 +
1046 +/* The public SQLite interface. The _FILE_OFFSET_BITS macro must appear
1047 +** first in QNX. Also, the _USE_32BIT_TIME_T macro must appear first for
1048 +** MinGW.
1049 +*/
1050 +/************** Include sqlite3.h in the middle of sqliteInt.h ***************/
1051 +/************** Begin file sqlite3.h *****************************************/
1052 +/*
1053 +** 2001-09-15
1054 +**
1055 +** The author disclaims copyright to this source code. In place of
1056 +** a legal notice, here is a blessing:
1057 +**
1058 +** May you do good and not evil.
1059 +** May you find forgiveness for yourself and forgive others.
1060 +** May you share freely, never taking more than you give.
1061 +**
1062 +*************************************************************************
1063 +** This header file defines the interface that the SQLite library
1064 +** presents to client programs. If a C-function, structure, datatype,
1065 +** or constant definition does not appear in this file, then it is
1066 +** not a published API of SQLite, is subject to change without
1067 +** notice, and should not be referenced by programs that use SQLite.
1068 +**
1069 +** Some of the definitions that are in this file are marked as
1070 +** "experimental". Experimental interfaces are normally new
1071 +** features recently added to SQLite. We do not anticipate changes
1072 +** to experimental interfaces but reserve the right to make minor changes
1073 +** if experience from use "in the wild" suggest such changes are prudent.
1074 +**
1075 +** The official C-language API documentation for SQLite is derived
1076 +** from comments in this file. This file is the authoritative source
1077 +** on how SQLite interfaces are supposed to operate.
1078 +**
1079 +** The name of this file under configuration management is "sqlite.h.in".
1080 +** The makefile makes some minor changes to this file (such as inserting
1081 +** the version number) and changes its name to "sqlite3.h" as
1082 +** part of the build process.
1083 +*/
1084 +#ifndef SQLITE3_H
1085 +#define SQLITE3_H
1086 +#include <stdarg.h> /* Needed for the definition of va_list */
1087 +
1088 +/*
1089 +** Make sure we can call this stuff from C++.
1090 +*/
1091 +#if 0
1092 +extern "C" {
1093 +#endif
1094 +
1095 +
1096 +/*
1097 +** Provide the ability to override linkage features of the interface.
1098 +*/
1099 +#ifndef SQLITE_EXTERN
1100 +# define SQLITE_EXTERN extern
1101 +#endif
1102 +#ifndef SQLITE_API
1103 +# define SQLITE_API
1104 +#endif
1105 +#ifndef SQLITE_CDECL
1106 +# define SQLITE_CDECL
1107 +#endif
1108 +#ifndef SQLITE_APICALL
1109 +# define SQLITE_APICALL
1110 +#endif
1111 +#ifndef SQLITE_STDCALL
1112 +# define SQLITE_STDCALL SQLITE_APICALL
1113 +#endif
1114 +#ifndef SQLITE_CALLBACK
1115 +# define SQLITE_CALLBACK
1116 +#endif
1117 +#ifndef SQLITE_SYSAPI
1118 +# define SQLITE_SYSAPI
1119 +#endif
1120 +
1121 +/*
1122 +** These no-op macros are used in front of interfaces to mark those
1123 +** interfaces as either deprecated or experimental. New applications
1124 +** should not use deprecated interfaces - they are supported for backwards
1125 +** compatibility only. Application writers should be aware that
1126 +** experimental interfaces are subject to change in point releases.
1127 +**
1128 +** These macros used to resolve to various kinds of compiler magic that
1129 +** would generate warning messages when they were used. But that
1130 +** compiler magic ended up generating such a flurry of bug reports
1131 +** that we have taken it all out and gone back to using simple
1132 +** noop macros.
1133 +*/
1134 +#define SQLITE_DEPRECATED
1135 +#define SQLITE_EXPERIMENTAL
1136 +
1137 +/*
1138 +** Ensure these symbols were not defined by some previous header file.
1139 +*/
1140 +#ifdef SQLITE_VERSION
1141 +# undef SQLITE_VERSION
1142 +#endif
1143 +#ifdef SQLITE_VERSION_NUMBER
1144 +# undef SQLITE_VERSION_NUMBER
1145 +#endif
1146 +
1147 +/*
1148 +** CAPI3REF: Compile-Time Library Version Numbers
1149 +**
1150 +** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
1151 +** evaluates to a string literal that is the SQLite version in the
1152 +** format "X.Y.Z" where X is the major version number (always 3 for
1153 +** SQLite3) and Y is the minor version number and Z is the release number.)^
1154 +** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
1155 +** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
1156 +** numbers used in [SQLITE_VERSION].)^
1157 +** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
1158 +** be larger than the release from which it is derived. Either Y will
1159 +** be held constant and Z will be incremented or else Y will be incremented
1160 +** and Z will be reset to zero.
1161 +**
1162 +** Since [version 3.6.18] ([dateof:3.6.18]),
1163 +** SQLite source code has been stored in the
1164 +** <a href="http://www.fossil-scm.org/">Fossil configuration management
1165 +** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to
1166 +** a string which identifies a particular check-in of SQLite
1167 +** within its configuration management system. ^The SQLITE_SOURCE_ID
1168 +** string contains the date and time of the check-in (UTC) and a SHA1
1169 +** or SHA3-256 hash of the entire source tree. If the source code has
1170 +** been edited in any way since it was last checked in, then the last
1171 +** four hexadecimal digits of the hash may be modified.
1172 +**
1173 +** See also: [sqlite3_libversion()],
1174 +** [sqlite3_libversion_number()], [sqlite3_sourceid()],
1175 +** [sqlite_version()] and [sqlite_source_id()].
1176 +*/
1177 +#define SQLITE_VERSION "3.33.0"
1178 +#define SQLITE_VERSION_NUMBER 3033000
1179 +#define SQLITE_SOURCE_ID "2020-08-14 13:23:32 fca8dc8b578f215a969cd899336378966156154710873e68b3d9ac5881b0alt1"
1180 +
1181 +/*
1182 +** CAPI3REF: Run-Time Library Version Numbers
1183 +** KEYWORDS: sqlite3_version sqlite3_sourceid
1184 +**
1185 +** These interfaces provide the same information as the [SQLITE_VERSION],
1186 +** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
1187 +** but are associated with the library instead of the header file. ^(Cautious
1188 +** programmers might include assert() statements in their application to
1189 +** verify that values returned by these interfaces match the macros in
1190 +** the header, and thus ensure that the application is
1191 +** compiled with matching library and header files.
1192 +**
1193 +** <blockquote><pre>
1194 +** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
1195 +** assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 );
1196 +** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
1197 +** </pre></blockquote>)^
1198 +**
1199 +** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
1200 +** macro. ^The sqlite3_libversion() function returns a pointer to the
1201 +** to the sqlite3_version[] string constant. The sqlite3_libversion()
1202 +** function is provided for use in DLLs since DLL users usually do not have
1203 +** direct access to string constants within the DLL. ^The
1204 +** sqlite3_libversion_number() function returns an integer equal to
1205 +** [SQLITE_VERSION_NUMBER]. ^(The sqlite3_sourceid() function returns
1206 +** a pointer to a string constant whose value is the same as the
1207 +** [SQLITE_SOURCE_ID] C preprocessor macro. Except if SQLite is built
1208 +** using an edited copy of [the amalgamation], then the last four characters
1209 +** of the hash might be different from [SQLITE_SOURCE_ID].)^
1210 +**
1211 +** See also: [sqlite_version()] and [sqlite_source_id()].
1212 +*/
1213 +SQLITE_API const char sqlite3_version[] = SQLITE_VERSION;
1214 +SQLITE_API const char *sqlite3_libversion(void);
1215 +SQLITE_API const char *sqlite3_sourceid(void);
1216 +SQLITE_API int sqlite3_libversion_number(void);
1217 +
1218 +/*
1219 +** CAPI3REF: Run-Time Library Compilation Options Diagnostics
1220 +**
1221 +** ^The sqlite3_compileoption_used() function returns 0 or 1
1222 +** indicating whether the specified option was defined at
1223 +** compile time. ^The SQLITE_ prefix may be omitted from the
1224 +** option name passed to sqlite3_compileoption_used().
1225 +**
1226 +** ^The sqlite3_compileoption_get() function allows iterating
1227 +** over the list of options that were defined at compile time by
1228 +** returning the N-th compile time option string. ^If N is out of range,
1229 +** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_
1230 +** prefix is omitted from any strings returned by
1231 +** sqlite3_compileoption_get().
1232 +**
1233 +** ^Support for the diagnostic functions sqlite3_compileoption_used()
1234 +** and sqlite3_compileoption_get() may be omitted by specifying the
1235 +** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
1236 +**
1237 +** See also: SQL functions [sqlite_compileoption_used()] and
1238 +** [sqlite_compileoption_get()] and the [compile_options pragma].
1239 +*/
1240 +#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
1241 +SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
1242 +SQLITE_API const char *sqlite3_compileoption_get(int N);
1243 +#else
1244 +# define sqlite3_compileoption_used(X) 0
1245 +# define sqlite3_compileoption_get(X) ((void*)0)
1246 +#endif
1247 +
1248 +/*
1249 +** CAPI3REF: Test To See If The Library Is Threadsafe
1250 +**
1251 +** ^The sqlite3_threadsafe() function returns zero if and only if
1252 +** SQLite was compiled with mutexing code omitted due to the
1253 +** [SQLITE_THREADSAFE] compile-time option being set to 0.
1254 +**
1255 +** SQLite can be compiled with or without mutexes. When
1256 +** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
1257 +** are enabled and SQLite is threadsafe. When the
1258 +** [SQLITE_THREADSAFE] macro is 0,
1259 +** the mutexes are omitted. Without the mutexes, it is not safe
1260 +** to use SQLite concurrently from more than one thread.
1261 +**
1262 +** Enabling mutexes incurs a measurable performance penalty.
1263 +** So if speed is of utmost importance, it makes sense to disable
1264 +** the mutexes. But for maximum safety, mutexes should be enabled.
1265 +** ^The default behavior is for mutexes to be enabled.
1266 +**
1267 +** This interface can be used by an application to make sure that the
1268 +** version of SQLite that it is linking against was compiled with
1269 +** the desired setting of the [SQLITE_THREADSAFE] macro.
1270 +**
1271 +** This interface only reports on the compile-time mutex setting
1272 +** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with
1273 +** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
1274 +** can be fully or partially disabled using a call to [sqlite3_config()]
1275 +** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
1276 +** or [SQLITE_CONFIG_SERIALIZED]. ^(The return value of the
1277 +** sqlite3_threadsafe() function shows only the compile-time setting of
1278 +** thread safety, not any run-time changes to that setting made by
1279 +** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
1280 +** is unchanged by calls to sqlite3_config().)^
1281 +**
1282 +** See the [threading mode] documentation for additional information.
1283 +*/
1284 +SQLITE_API int sqlite3_threadsafe(void);
1285 +
1286 +/*
1287 +** CAPI3REF: Database Connection Handle
1288 +** KEYWORDS: {database connection} {database connections}
1289 +**
1290 +** Each open SQLite database is represented by a pointer to an instance of
1291 +** the opaque structure named "sqlite3". It is useful to think of an sqlite3
1292 +** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
1293 +** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
1294 +** and [sqlite3_close_v2()] are its destructors. There are many other
1295 +** interfaces (such as
1296 +** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
1297 +** [sqlite3_busy_timeout()] to name but three) that are methods on an
1298 +** sqlite3 object.
1299 +*/
1300 +typedef struct sqlite3 sqlite3;
1301 +
1302 +/*
1303 +** CAPI3REF: 64-Bit Integer Types
1304 +** KEYWORDS: sqlite_int64 sqlite_uint64
1305 +**
1306 +** Because there is no cross-platform way to specify 64-bit integer types
1307 +** SQLite includes typedefs for 64-bit signed and unsigned integers.
1308 +**
1309 +** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
1310 +** The sqlite_int64 and sqlite_uint64 types are supported for backwards
1311 +** compatibility only.
1312 +**
1313 +** ^The sqlite3_int64 and sqlite_int64 types can store integer values
1314 +** between -9223372036854775808 and +9223372036854775807 inclusive. ^The
1315 +** sqlite3_uint64 and sqlite_uint64 types can store integer values
1316 +** between 0 and +18446744073709551615 inclusive.
1317 +*/
1318 +#ifdef SQLITE_INT64_TYPE
1319 + typedef SQLITE_INT64_TYPE sqlite_int64;
1320 +# ifdef SQLITE_UINT64_TYPE
1321 + typedef SQLITE_UINT64_TYPE sqlite_uint64;
1322 +# else
1323 + typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
1324 +# endif
1325 +#elif defined(_MSC_VER) || defined(__BORLANDC__)
1326 + typedef __int64 sqlite_int64;
1327 + typedef unsigned __int64 sqlite_uint64;
1328 +#else
1329 + typedef long long int sqlite_int64;
1330 + typedef unsigned long long int sqlite_uint64;
1331 +#endif
1332 +typedef sqlite_int64 sqlite3_int64;
1333 +typedef sqlite_uint64 sqlite3_uint64;
1334 +
1335 +/*
1336 +** If compiling for a processor that lacks floating point support,
1337 +** substitute integer for floating-point.
1338 +*/
1339 +#ifdef SQLITE_OMIT_FLOATING_POINT
1340 +# define double sqlite3_int64
1341 +#endif
1342 +
1343 +/*
1344 +** CAPI3REF: Closing A Database Connection
1345 +** DESTRUCTOR: sqlite3
1346 +**
1347 +** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
1348 +** for the [sqlite3] object.
1349 +** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
1350 +** the [sqlite3] object is successfully destroyed and all associated
1351 +** resources are deallocated.
1352 +**
1353 +** Ideally, applications should [sqlite3_finalize | finalize] all
1354 +** [prepared statements], [sqlite3_blob_close | close] all [BLOB handles], and
1355 +** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated
1356 +** with the [sqlite3] object prior to attempting to close the object.
1357 +** ^If the database connection is associated with unfinalized prepared
1358 +** statements, BLOB handlers, and/or unfinished sqlite3_backup objects then
1359 +** sqlite3_close() will leave the database connection open and return
1360 +** [SQLITE_BUSY]. ^If sqlite3_close_v2() is called with unfinalized prepared
1361 +** statements, unclosed BLOB handlers, and/or unfinished sqlite3_backups,
1362 +** it returns [SQLITE_OK] regardless, but instead of deallocating the database
1363 +** connection immediately, it marks the database connection as an unusable
1364 +** "zombie" and makes arrangements to automatically deallocate the database
1365 +** connection after all prepared statements are finalized, all BLOB handles
1366 +** are closed, and all backups have finished. The sqlite3_close_v2() interface
1367 +** is intended for use with host languages that are garbage collected, and
1368 +** where the order in which destructors are called is arbitrary.
1369 +**
1370 +** ^If an [sqlite3] object is destroyed while a transaction is open,
1371 +** the transaction is automatically rolled back.
1372 +**
1373 +** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
1374 +** must be either a NULL
1375 +** pointer or an [sqlite3] object pointer obtained
1376 +** from [sqlite3_open()], [sqlite3_open16()], or
1377 +** [sqlite3_open_v2()], and not previously closed.
1378 +** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
1379 +** argument is a harmless no-op.
1380 +*/
1381 +SQLITE_API int sqlite3_close(sqlite3*);
1382 +SQLITE_API int sqlite3_close_v2(sqlite3*);
1383 +
1384 +/*
1385 +** The type for a callback function.
1386 +** This is legacy and deprecated. It is included for historical
1387 +** compatibility and is not documented.
1388 +*/
1389 +typedef int (*sqlite3_callback)(void*,int,char**, char**);
1390 +
1391 +/*
1392 +** CAPI3REF: One-Step Query Execution Interface
1393 +** METHOD: sqlite3
1394 +**
1395 +** The sqlite3_exec() interface is a convenience wrapper around
1396 +** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
1397 +** that allows an application to run multiple statements of SQL
1398 +** without having to use a lot of C code.
1399 +**
1400 +** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
1401 +** semicolon-separate SQL statements passed into its 2nd argument,
1402 +** in the context of the [database connection] passed in as its 1st
1403 +** argument. ^If the callback function of the 3rd argument to
1404 +** sqlite3_exec() is not NULL, then it is invoked for each result row
1405 +** coming out of the evaluated SQL statements. ^The 4th argument to
1406 +** sqlite3_exec() is relayed through to the 1st argument of each
1407 +** callback invocation. ^If the callback pointer to sqlite3_exec()
1408 +** is NULL, then no callback is ever invoked and result rows are
1409 +** ignored.
1410 +**
1411 +** ^If an error occurs while evaluating the SQL statements passed into
1412 +** sqlite3_exec(), then execution of the current statement stops and
1413 +** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec()
1414 +** is not NULL then any error message is written into memory obtained
1415 +** from [sqlite3_malloc()] and passed back through the 5th parameter.
1416 +** To avoid memory leaks, the application should invoke [sqlite3_free()]
1417 +** on error message strings returned through the 5th parameter of
1418 +** sqlite3_exec() after the error message string is no longer needed.
1419 +** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
1420 +** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
1421 +** NULL before returning.
1422 +**
1423 +** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
1424 +** routine returns SQLITE_ABORT without invoking the callback again and
1425 +** without running any subsequent SQL statements.
1426 +**
1427 +** ^The 2nd argument to the sqlite3_exec() callback function is the
1428 +** number of columns in the result. ^The 3rd argument to the sqlite3_exec()
1429 +** callback is an array of pointers to strings obtained as if from
1430 +** [sqlite3_column_text()], one for each column. ^If an element of a
1431 +** result row is NULL then the corresponding string pointer for the
1432 +** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
1433 +** sqlite3_exec() callback is an array of pointers to strings where each
1434 +** entry represents the name of corresponding result column as obtained
1435 +** from [sqlite3_column_name()].
1436 +**
1437 +** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
1438 +** to an empty string, or a pointer that contains only whitespace and/or
1439 +** SQL comments, then no SQL statements are evaluated and the database
1440 +** is not changed.
1441 +**
1442 +** Restrictions:
1443 +**
1444 +** <ul>
1445 +** <li> The application must ensure that the 1st parameter to sqlite3_exec()
1446 +** is a valid and open [database connection].
1447 +** <li> The application must not close the [database connection] specified by
1448 +** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
1449 +** <li> The application must not modify the SQL statement text passed into
1450 +** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
1451 +** </ul>
1452 +*/
1453 +SQLITE_API int sqlite3_exec(
1454 + sqlite3*, /* An open database */
1455 + const char *sql, /* SQL to be evaluated */
1456 + int (*callback)(void*,int,char**,char**), /* Callback function */
1457 + void *, /* 1st argument to callback */
1458 + char **errmsg /* Error msg written here */
1459 +);
1460 +
1461 +/*
1462 +** CAPI3REF: Result Codes
1463 +** KEYWORDS: {result code definitions}
1464 +**
1465 +** Many SQLite functions return an integer result code from the set shown
1466 +** here in order to indicate success or failure.
1467 +**
1468 +** New error codes may be added in future versions of SQLite.
1469 +**
1470 +** See also: [extended result code definitions]
1471 +*/
1472 +#define SQLITE_OK 0 /* Successful result */
1473 +/* beginning-of-error-codes */
1474 +#define SQLITE_ERROR 1 /* Generic error */
1475 +#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
1476 +#define SQLITE_PERM 3 /* Access permission denied */
1477 +#define SQLITE_ABORT 4 /* Callback routine requested an abort */
1478 +#define SQLITE_BUSY 5 /* The database file is locked */
1479 +#define SQLITE_LOCKED 6 /* A table in the database is locked */
1480 +#define SQLITE_NOMEM 7 /* A malloc() failed */
1481 +#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
1482 +#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
1483 +#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
1484 +#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
1485 +#define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */
1486 +#define SQLITE_FULL 13 /* Insertion failed because database is full */
1487 +#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
1488 +#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
1489 +#define SQLITE_EMPTY 16 /* Internal use only */
1490 +#define SQLITE_SCHEMA 17 /* The database schema changed */
1491 +#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
1492 +#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
1493 +#define SQLITE_MISMATCH 20 /* Data type mismatch */
1494 +#define SQLITE_MISUSE 21 /* Library used incorrectly */
1495 +#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
1496 +#define SQLITE_AUTH 23 /* Authorization denied */
1497 +#define SQLITE_FORMAT 24 /* Not used */
1498 +#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
1499 +#define SQLITE_NOTADB 26 /* File opened that is not a database file */
1500 +#define SQLITE_NOTICE 27 /* Notifications from sqlite3_log() */
1501 +#define SQLITE_WARNING 28 /* Warnings from sqlite3_log() */
1502 +#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
1503 +#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
1504 +/* end-of-error-codes */
1505 +
1506 +/*
1507 +** CAPI3REF: Extended Result Codes
1508 +** KEYWORDS: {extended result code definitions}
1509 +**
1510 +** In its default configuration, SQLite API routines return one of 30 integer
1511 +** [result codes]. However, experience has shown that many of
1512 +** these result codes are too coarse-grained. They do not provide as
1513 +** much information about problems as programmers might like. In an effort to
1514 +** address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8]
1515 +** and later) include
1516 +** support for additional result codes that provide more detailed information
1517 +** about errors. These [extended result codes] are enabled or disabled
1518 +** on a per database connection basis using the
1519 +** [sqlite3_extended_result_codes()] API. Or, the extended code for
1520 +** the most recent error can be obtained using
1521 +** [sqlite3_extended_errcode()].
1522 +*/
1523 +#define SQLITE_ERROR_MISSING_COLLSEQ (SQLITE_ERROR | (1<<8))
1524 +#define SQLITE_ERROR_RETRY (SQLITE_ERROR | (2<<8))
1525 +#define SQLITE_ERROR_SNAPSHOT (SQLITE_ERROR | (3<<8))
1526 +#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
1527 +#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
1528 +#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))
1529 +#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))
1530 +#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))
1531 +#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))
1532 +#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))
1533 +#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))
1534 +#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))
1535 +#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
1536 +#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
1537 +#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))
1538 +#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8))
1539 +#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
1540 +#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8))
1541 +#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8))
1542 +#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8))
1543 +#define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8))
1544 +#define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8))
1545 +#define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8))
1546 +#define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8))
1547 +#define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8))
1548 +#define SQLITE_IOERR_DELETE_NOENT (SQLITE_IOERR | (23<<8))
1549 +#define SQLITE_IOERR_MMAP (SQLITE_IOERR | (24<<8))
1550 +#define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR | (25<<8))
1551 +#define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26<<8))
1552 +#define SQLITE_IOERR_VNODE (SQLITE_IOERR | (27<<8))
1553 +#define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28<<8))
1554 +#define SQLITE_IOERR_BEGIN_ATOMIC (SQLITE_IOERR | (29<<8))
1555 +#define SQLITE_IOERR_COMMIT_ATOMIC (SQLITE_IOERR | (30<<8))
1556 +#define SQLITE_IOERR_ROLLBACK_ATOMIC (SQLITE_IOERR | (31<<8))
1557 +#define SQLITE_IOERR_DATA (SQLITE_IOERR | (32<<8))
1558 +#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))
1559 +#define SQLITE_LOCKED_VTAB (SQLITE_LOCKED | (2<<8))
1560 +#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))
1561 +#define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8))
1562 +#define SQLITE_BUSY_TIMEOUT (SQLITE_BUSY | (3<<8))
1563 +#define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8))
1564 +#define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8))
1565 +#define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8))
1566 +#define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8))
1567 +#define SQLITE_CANTOPEN_DIRTYWAL (SQLITE_CANTOPEN | (5<<8)) /* Not Used */
1568 +#define SQLITE_CANTOPEN_SYMLINK (SQLITE_CANTOPEN | (6<<8))
1569 +#define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8))
1570 +#define SQLITE_CORRUPT_SEQUENCE (SQLITE_CORRUPT | (2<<8))
1571 +#define SQLITE_CORRUPT_INDEX (SQLITE_CORRUPT | (3<<8))
1572 +#define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8))
1573 +#define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8))
1574 +#define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8))
1575 +#define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8))
1576 +#define SQLITE_READONLY_CANTINIT (SQLITE_READONLY | (5<<8))
1577 +#define SQLITE_READONLY_DIRECTORY (SQLITE_READONLY | (6<<8))
1578 +#define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8))
1579 +#define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1<<8))
1580 +#define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2<<8))
1581 +#define SQLITE_CONSTRAINT_FOREIGNKEY (SQLITE_CONSTRAINT | (3<<8))
1582 +#define SQLITE_CONSTRAINT_FUNCTION (SQLITE_CONSTRAINT | (4<<8))
1583 +#define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5<<8))
1584 +#define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6<<8))
1585 +#define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7<<8))
1586 +#define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8<<8))
1587 +#define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8))
1588 +#define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8))
1589 +#define SQLITE_CONSTRAINT_PINNED (SQLITE_CONSTRAINT |(11<<8))
1590 +#define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8))
1591 +#define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
1592 +#define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8))
1593 +#define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8))
1594 +#define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8))
1595 +#define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8))
1596 +
1597 +/*
1598 +** CAPI3REF: Flags For File Open Operations
1599 +**
1600 +** These bit values are intended for use in the
1601 +** 3rd parameter to the [sqlite3_open_v2()] interface and
1602 +** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
1603 +*/
1604 +#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
1605 +#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
1606 +#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */
1607 +#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */
1608 +#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */
1609 +#define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */
1610 +#define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */
1611 +#define SQLITE_OPEN_MEMORY 0x00000080 /* Ok for sqlite3_open_v2() */
1612 +#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */
1613 +#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */
1614 +#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */
1615 +#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */
1616 +#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */
1617 +#define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */
1618 +#define SQLITE_OPEN_SUPER_JOURNAL 0x00004000 /* VFS only */
1619 +#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */
1620 +#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */
1621 +#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */
1622 +#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
1623 +#define SQLITE_OPEN_WAL 0x00080000 /* VFS only */
1624 +#define SQLITE_OPEN_NOFOLLOW 0x01000000 /* Ok for sqlite3_open_v2() */
1625 +
1626 +/* Reserved: 0x00F00000 */
1627 +/* Legacy compatibility: */
1628 +#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */
1629 +
1630 +
1631 +/*
1632 +** CAPI3REF: Device Characteristics
1633 +**
1634 +** The xDeviceCharacteristics method of the [sqlite3_io_methods]
1635 +** object returns an integer which is a vector of these
1636 +** bit values expressing I/O characteristics of the mass storage
1637 +** device that holds the file that the [sqlite3_io_methods]
1638 +** refers to.
1639 +**
1640 +** The SQLITE_IOCAP_ATOMIC property means that all writes of
1641 +** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
1642 +** mean that writes of blocks that are nnn bytes in size and
1643 +** are aligned to an address which is an integer multiple of
1644 +** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
1645 +** that when data is appended to a file, the data is appended
1646 +** first then the size of the file is extended, never the other
1647 +** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
1648 +** information is written to disk in the same order as calls
1649 +** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
1650 +** after reboot following a crash or power loss, the only bytes in a
1651 +** file that were written at the application level might have changed
1652 +** and that adjacent bytes, even bytes within the same sector are
1653 +** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
1654 +** flag indicates that a file cannot be deleted when open. The
1655 +** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
1656 +** read-only media and cannot be changed even by processes with
1657 +** elevated privileges.
1658 +**
1659 +** The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying
1660 +** filesystem supports doing multiple write operations atomically when those
1661 +** write operations are bracketed by [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] and
1662 +** [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].
1663 +*/
1664 +#define SQLITE_IOCAP_ATOMIC 0x00000001
1665 +#define SQLITE_IOCAP_ATOMIC512 0x00000002
1666 +#define SQLITE_IOCAP_ATOMIC1K 0x00000004
1667 +#define SQLITE_IOCAP_ATOMIC2K 0x00000008
1668 +#define SQLITE_IOCAP_ATOMIC4K 0x00000010
1669 +#define SQLITE_IOCAP_ATOMIC8K 0x00000020
1670 +#define SQLITE_IOCAP_ATOMIC16K 0x00000040
1671 +#define SQLITE_IOCAP_ATOMIC32K 0x00000080
1672 +#define SQLITE_IOCAP_ATOMIC64K 0x00000100
1673 +#define SQLITE_IOCAP_SAFE_APPEND 0x00000200
1674 +#define SQLITE_IOCAP_SEQUENTIAL 0x00000400
1675 +#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800
1676 +#define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000
1677 +#define SQLITE_IOCAP_IMMUTABLE 0x00002000
1678 +#define SQLITE_IOCAP_BATCH_ATOMIC 0x00004000
1679 +
1680 +/*
1681 +** CAPI3REF: File Locking Levels
1682 +**
1683 +** SQLite uses one of these integer values as the second
1684 +** argument to calls it makes to the xLock() and xUnlock() methods
1685 +** of an [sqlite3_io_methods] object.
1686 +*/
1687 +#define SQLITE_LOCK_NONE 0
1688 +#define SQLITE_LOCK_SHARED 1
1689 +#define SQLITE_LOCK_RESERVED 2
1690 +#define SQLITE_LOCK_PENDING 3
1691 +#define SQLITE_LOCK_EXCLUSIVE 4
1692 +
1693 +/*
1694 +** CAPI3REF: Synchronization Type Flags
1695 +**
1696 +** When SQLite invokes the xSync() method of an
1697 +** [sqlite3_io_methods] object it uses a combination of
1698 +** these integer values as the second argument.
1699 +**
1700 +** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
1701 +** sync operation only needs to flush data to mass storage. Inode
1702 +** information need not be flushed. If the lower four bits of the flag
1703 +** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
1704 +** If the lower four bits equal SQLITE_SYNC_FULL, that means
1705 +** to use Mac OS X style fullsync instead of fsync().
1706 +**
1707 +** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
1708 +** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
1709 +** settings. The [synchronous pragma] determines when calls to the
1710 +** xSync VFS method occur and applies uniformly across all platforms.
1711 +** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
1712 +** energetic or rigorous or forceful the sync operations are and
1713 +** only make a difference on Mac OSX for the default SQLite code.
1714 +** (Third-party VFS implementations might also make the distinction
1715 +** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
1716 +** operating systems natively supported by SQLite, only Mac OSX
1717 +** cares about the difference.)
1718 +*/
1719 +#define SQLITE_SYNC_NORMAL 0x00002
1720 +#define SQLITE_SYNC_FULL 0x00003
1721 +#define SQLITE_SYNC_DATAONLY 0x00010
1722 +
1723 +/*
1724 +** CAPI3REF: OS Interface Open File Handle
1725 +**
1726 +** An [sqlite3_file] object represents an open file in the
1727 +** [sqlite3_vfs | OS interface layer]. Individual OS interface
1728 +** implementations will
1729 +** want to subclass this object by appending additional fields
1730 +** for their own use. The pMethods entry is a pointer to an
1731 +** [sqlite3_io_methods] object that defines methods for performing
1732 +** I/O operations on the open file.
1733 +*/
1734 +typedef struct sqlite3_file sqlite3_file;
1735 +struct sqlite3_file {
1736 + const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
1737 +};
1738 +
1739 +/*
1740 +** CAPI3REF: OS Interface File Virtual Methods Object
1741 +**
1742 +** Every file opened by the [sqlite3_vfs.xOpen] method populates an
1743 +** [sqlite3_file] object (or, more commonly, a subclass of the
1744 +** [sqlite3_file] object) with a pointer to an instance of this object.
1745 +** This object defines the methods used to perform various operations
1746 +** against the open file represented by the [sqlite3_file] object.
1747 +**
1748 +** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element
1749 +** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
1750 +** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed. The
1751 +** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
1752 +** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
1753 +** to NULL.
1754 +**
1755 +** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
1756 +** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
1757 +** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
1758 +** flag may be ORed in to indicate that only the data of the file
1759 +** and not its inode needs to be synced.
1760 +**
1761 +** The integer values to xLock() and xUnlock() are one of
1762 +** <ul>
1763 +** <li> [SQLITE_LOCK_NONE],
1764 +** <li> [SQLITE_LOCK_SHARED],
1765 +** <li> [SQLITE_LOCK_RESERVED],
1766 +** <li> [SQLITE_LOCK_PENDING], or
1767 +** <li> [SQLITE_LOCK_EXCLUSIVE].
1768 +** </ul>
1769 +** xLock() increases the lock. xUnlock() decreases the lock.
1770 +** The xCheckReservedLock() method checks whether any database connection,
1771 +** either in this process or in some other process, is holding a RESERVED,
1772 +** PENDING, or EXCLUSIVE lock on the file. It returns true
1773 +** if such a lock exists and false otherwise.
1774 +**
1775 +** The xFileControl() method is a generic interface that allows custom
1776 +** VFS implementations to directly control an open file using the
1777 +** [sqlite3_file_control()] interface. The second "op" argument is an
1778 +** integer opcode. The third argument is a generic pointer intended to
1779 +** point to a structure that may contain arguments or space in which to
1780 +** write return values. Potential uses for xFileControl() might be
1781 +** functions to enable blocking locks with timeouts, to change the
1782 +** locking strategy (for example to use dot-file locks), to inquire
1783 +** about the status of a lock, or to break stale locks. The SQLite
1784 +** core reserves all opcodes less than 100 for its own use.
1785 +** A [file control opcodes | list of opcodes] less than 100 is available.
1786 +** Applications that define a custom xFileControl method should use opcodes
1787 +** greater than 100 to avoid conflicts. VFS implementations should
1788 +** return [SQLITE_NOTFOUND] for file control opcodes that they do not
1789 +** recognize.
1790 +**
1791 +** The xSectorSize() method returns the sector size of the
1792 +** device that underlies the file. The sector size is the
1793 +** minimum write that can be performed without disturbing
1794 +** other bytes in the file. The xDeviceCharacteristics()
1795 +** method returns a bit vector describing behaviors of the
1796 +** underlying device:
1797 +**
1798 +** <ul>
1799 +** <li> [SQLITE_IOCAP_ATOMIC]
1800 +** <li> [SQLITE_IOCAP_ATOMIC512]
1801 +** <li> [SQLITE_IOCAP_ATOMIC1K]
1802 +** <li> [SQLITE_IOCAP_ATOMIC2K]
1803 +** <li> [SQLITE_IOCAP_ATOMIC4K]
1804 +** <li> [SQLITE_IOCAP_ATOMIC8K]
1805 +** <li> [SQLITE_IOCAP_ATOMIC16K]
1806 +** <li> [SQLITE_IOCAP_ATOMIC32K]
1807 +** <li> [SQLITE_IOCAP_ATOMIC64K]
1808 +** <li> [SQLITE_IOCAP_SAFE_APPEND]
1809 +** <li> [SQLITE_IOCAP_SEQUENTIAL]
1810 +** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN]
1811 +** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE]
1812 +** <li> [SQLITE_IOCAP_IMMUTABLE]
1813 +** <li> [SQLITE_IOCAP_BATCH_ATOMIC]
1814 +** </ul>
1815 +**
1816 +** The SQLITE_IOCAP_ATOMIC property means that all writes of
1817 +** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
1818 +** mean that writes of blocks that are nnn bytes in size and
1819 +** are aligned to an address which is an integer multiple of
1820 +** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
1821 +** that when data is appended to a file, the data is appended
1822 +** first then the size of the file is extended, never the other
1823 +** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
1824 +** information is written to disk in the same order as calls
1825 +** to xWrite().
1826 +**
1827 +** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
1828 +** in the unread portions of the buffer with zeros. A VFS that
1829 +** fails to zero-fill short reads might seem to work. However,
1830 +** failure to zero-fill short reads will eventually lead to
1831 +** database corruption.
1832 +*/
1833 +typedef struct sqlite3_io_methods sqlite3_io_methods;
1834 +struct sqlite3_io_methods {
1835 + int iVersion;
1836 + int (*xClose)(sqlite3_file*);
1837 + int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
1838 + int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
1839 + int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
1840 + int (*xSync)(sqlite3_file*, int flags);
1841 + int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
1842 + int (*xLock)(sqlite3_file*, int);
1843 + int (*xUnlock)(sqlite3_file*, int);
1844 + int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
1845 + int (*xFileControl)(sqlite3_file*, int op, void *pArg);
1846 + int (*xSectorSize)(sqlite3_file*);
1847 + int (*xDeviceCharacteristics)(sqlite3_file*);
1848 + /* Methods above are valid for version 1 */
1849 + int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
1850 + int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
1851 + void (*xShmBarrier)(sqlite3_file*);
1852 + int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
1853 + /* Methods above are valid for version 2 */
1854 + int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
1855 + int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
1856 + /* Methods above are valid for version 3 */
1857 + /* Additional methods may be added in future releases */
1858 +};
1859 +
1860 +/*
1861 +** CAPI3REF: Standard File Control Opcodes
1862 +** KEYWORDS: {file control opcodes} {file control opcode}
1863 +**
1864 +** These integer constants are opcodes for the xFileControl method
1865 +** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
1866 +** interface.
1867 +**
1868 +** <ul>
1869 +** <li>[[SQLITE_FCNTL_LOCKSTATE]]
1870 +** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
1871 +** opcode causes the xFileControl method to write the current state of
1872 +** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
1873 +** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
1874 +** into an integer that the pArg argument points to. This capability
1875 +** is used during testing and is only available when the SQLITE_TEST
1876 +** compile-time option is used.
1877 +**
1878 +** <li>[[SQLITE_FCNTL_SIZE_HINT]]
1879 +** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
1880 +** layer a hint of how large the database file will grow to be during the
1881 +** current transaction. This hint is not guaranteed to be accurate but it
1882 +** is often close. The underlying VFS might choose to preallocate database
1883 +** file space based on this hint in order to help writes to the database
1884 +** file run faster.
1885 +**
1886 +** <li>[[SQLITE_FCNTL_SIZE_LIMIT]]
1887 +** The [SQLITE_FCNTL_SIZE_LIMIT] opcode is used by in-memory VFS that
1888 +** implements [sqlite3_deserialize()] to set an upper bound on the size
1889 +** of the in-memory database. The argument is a pointer to a [sqlite3_int64].
1890 +** If the integer pointed to is negative, then it is filled in with the
1891 +** current limit. Otherwise the limit is set to the larger of the value
1892 +** of the integer pointed to and the current database size. The integer
1893 +** pointed to is set to the new limit.
1894 +**
1895 +** <li>[[SQLITE_FCNTL_CHUNK_SIZE]]
1896 +** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
1897 +** extends and truncates the database file in chunks of a size specified
1898 +** by the user. The fourth argument to [sqlite3_file_control()] should
1899 +** point to an integer (type int) containing the new chunk-size to use
1900 +** for the nominated database. Allocating database file space in large
1901 +** chunks (say 1MB at a time), may reduce file-system fragmentation and
1902 +** improve performance on some systems.
1903 +**
1904 +** <li>[[SQLITE_FCNTL_FILE_POINTER]]
1905 +** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
1906 +** to the [sqlite3_file] object associated with a particular database
1907 +** connection. See also [SQLITE_FCNTL_JOURNAL_POINTER].
1908 +**
1909 +** <li>[[SQLITE_FCNTL_JOURNAL_POINTER]]
1910 +** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
1911 +** to the [sqlite3_file] object associated with the journal file (either
1912 +** the [rollback journal] or the [write-ahead log]) for a particular database
1913 +** connection. See also [SQLITE_FCNTL_FILE_POINTER].
1914 +**
1915 +** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
1916 +** No longer in use.
1917 +**
1918 +** <li>[[SQLITE_FCNTL_SYNC]]
1919 +** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
1920 +** sent to the VFS immediately before the xSync method is invoked on a
1921 +** database file descriptor. Or, if the xSync method is not invoked
1922 +** because the user has configured SQLite with
1923 +** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place
1924 +** of the xSync method. In most cases, the pointer argument passed with
1925 +** this file-control is NULL. However, if the database file is being synced
1926 +** as part of a multi-database commit, the argument points to a nul-terminated
1927 +** string containing the transactions super-journal file name. VFSes that
1928 +** do not need this signal should silently ignore this opcode. Applications
1929 +** should not call [sqlite3_file_control()] with this opcode as doing so may
1930 +** disrupt the operation of the specialized VFSes that do require it.
1931 +**
1932 +** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]]
1933 +** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
1934 +** and sent to the VFS after a transaction has been committed immediately
1935 +** but before the database is unlocked. VFSes that do not need this signal
1936 +** should silently ignore this opcode. Applications should not call
1937 +** [sqlite3_file_control()] with this opcode as doing so may disrupt the
1938 +** operation of the specialized VFSes that do require it.
1939 +**
1940 +** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
1941 +** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
1942 +** retry counts and intervals for certain disk I/O operations for the
1943 +** windows [VFS] in order to provide robustness in the presence of
1944 +** anti-virus programs. By default, the windows VFS will retry file read,
1945 +** file write, and file delete operations up to 10 times, with a delay
1946 +** of 25 milliseconds before the first retry and with the delay increasing
1947 +** by an additional 25 milliseconds with each subsequent retry. This
1948 +** opcode allows these two values (10 retries and 25 milliseconds of delay)
1949 +** to be adjusted. The values are changed for all database connections
1950 +** within the same process. The argument is a pointer to an array of two
1951 +** integers where the first integer is the new retry count and the second
1952 +** integer is the delay. If either integer is negative, then the setting
1953 +** is not changed but instead the prior value of that setting is written
1954 +** into the array entry, allowing the current retry settings to be
1955 +** interrogated. The zDbName parameter is ignored.
1956 +**
1957 +** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
1958 +** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
1959 +** persistent [WAL | Write Ahead Log] setting. By default, the auxiliary
1960 +** write ahead log ([WAL file]) and shared memory
1961 +** files used for transaction control
1962 +** are automatically deleted when the latest connection to the database
1963 +** closes. Setting persistent WAL mode causes those files to persist after
1964 +** close. Persisting the files is useful when other processes that do not
1965 +** have write permission on the directory containing the database file want
1966 +** to read the database file, as the WAL and shared memory files must exist
1967 +** in order for the database to be readable. The fourth parameter to
1968 +** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
1969 +** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
1970 +** WAL mode. If the integer is -1, then it is overwritten with the current
1971 +** WAL persistence setting.
1972 +**
1973 +** <li>[[SQLITE_FCNTL_POWERSAFE_OVERWRITE]]
1974 +** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
1975 +** persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting
1976 +** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the
1977 +** xDeviceCharacteristics methods. The fourth parameter to
1978 +** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
1979 +** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
1980 +** mode. If the integer is -1, then it is overwritten with the current
1981 +** zero-damage mode setting.
1982 +**
1983 +** <li>[[SQLITE_FCNTL_OVERWRITE]]
1984 +** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
1985 +** a write transaction to indicate that, unless it is rolled back for some
1986 +** reason, the entire database file will be overwritten by the current
1987 +** transaction. This is used by VACUUM operations.
1988 +**
1989 +** <li>[[SQLITE_FCNTL_VFSNAME]]
1990 +** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
1991 +** all [VFSes] in the VFS stack. The names are of all VFS shims and the
1992 +** final bottom-level VFS are written into memory obtained from
1993 +** [sqlite3_malloc()] and the result is stored in the char* variable
1994 +** that the fourth parameter of [sqlite3_file_control()] points to.
1995 +** The caller is responsible for freeing the memory when done. As with
1996 +** all file-control actions, there is no guarantee that this will actually
1997 +** do anything. Callers should initialize the char* variable to a NULL
1998 +** pointer in case this file-control is not implemented. This file-control
1999 +** is intended for diagnostic use only.
2000 +**
2001 +** <li>[[SQLITE_FCNTL_VFS_POINTER]]
2002 +** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
2003 +** [VFSes] currently in use. ^(The argument X in
2004 +** sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
2005 +** of type "[sqlite3_vfs] **". This opcodes will set *X
2006 +** to a pointer to the top-level VFS.)^
2007 +** ^When there are multiple VFS shims in the stack, this opcode finds the
2008 +** upper-most shim only.
2009 +**
2010 +** <li>[[SQLITE_FCNTL_PRAGMA]]
2011 +** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
2012 +** file control is sent to the open [sqlite3_file] object corresponding
2013 +** to the database file to which the pragma statement refers. ^The argument
2014 +** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
2015 +** pointers to strings (char**) in which the second element of the array
2016 +** is the name of the pragma and the third element is the argument to the
2017 +** pragma or NULL if the pragma has no argument. ^The handler for an
2018 +** [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element
2019 +** of the char** argument point to a string obtained from [sqlite3_mprintf()]
2020 +** or the equivalent and that string will become the result of the pragma or
2021 +** the error message if the pragma fails. ^If the
2022 +** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal
2023 +** [PRAGMA] processing continues. ^If the [SQLITE_FCNTL_PRAGMA]
2024 +** file control returns [SQLITE_OK], then the parser assumes that the
2025 +** VFS has handled the PRAGMA itself and the parser generates a no-op
2026 +** prepared statement if result string is NULL, or that returns a copy
2027 +** of the result string if the string is non-NULL.
2028 +** ^If the [SQLITE_FCNTL_PRAGMA] file control returns
2029 +** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
2030 +** that the VFS encountered an error while handling the [PRAGMA] and the
2031 +** compilation of the PRAGMA fails with an error. ^The [SQLITE_FCNTL_PRAGMA]
2032 +** file control occurs at the beginning of pragma statement analysis and so
2033 +** it is able to override built-in [PRAGMA] statements.
2034 +**
2035 +** <li>[[SQLITE_FCNTL_BUSYHANDLER]]
2036 +** ^The [SQLITE_FCNTL_BUSYHANDLER]
2037 +** file-control may be invoked by SQLite on the database file handle
2038 +** shortly after it is opened in order to provide a custom VFS with access
2039 +** to the connection's busy-handler callback. The argument is of type (void**)
2040 +** - an array of two (void *) values. The first (void *) actually points
2041 +** to a function of type (int (*)(void *)). In order to invoke the connection's
2042 +** busy-handler, this function should be invoked with the second (void *) in
2043 +** the array as the only argument. If it returns non-zero, then the operation
2044 +** should be retried. If it returns zero, the custom VFS should abandon the
2045 +** current operation.
2046 +**
2047 +** <li>[[SQLITE_FCNTL_TEMPFILENAME]]
2048 +** ^Applications can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
2049 +** to have SQLite generate a
2050 +** temporary filename using the same algorithm that is followed to generate
2051 +** temporary filenames for TEMP tables and other internal uses. The
2052 +** argument should be a char** which will be filled with the filename
2053 +** written into memory obtained from [sqlite3_malloc()]. The caller should
2054 +** invoke [sqlite3_free()] on the result to avoid a memory leak.
2055 +**
2056 +** <li>[[SQLITE_FCNTL_MMAP_SIZE]]
2057 +** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
2058 +** maximum number of bytes that will be used for memory-mapped I/O.
2059 +** The argument is a pointer to a value of type sqlite3_int64 that
2060 +** is an advisory maximum number of bytes in the file to memory map. The
2061 +** pointer is overwritten with the old value. The limit is not changed if
2062 +** the value originally pointed to is negative, and so the current limit
2063 +** can be queried by passing in a pointer to a negative number. This
2064 +** file-control is used internally to implement [PRAGMA mmap_size].
2065 +**
2066 +** <li>[[SQLITE_FCNTL_TRACE]]
2067 +** The [SQLITE_FCNTL_TRACE] file control provides advisory information
2068 +** to the VFS about what the higher layers of the SQLite stack are doing.
2069 +** This file control is used by some VFS activity tracing [shims].
2070 +** The argument is a zero-terminated string. Higher layers in the
2071 +** SQLite stack may generate instances of this file control if
2072 +** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
2073 +**
2074 +** <li>[[SQLITE_FCNTL_HAS_MOVED]]
2075 +** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a
2076 +** pointer to an integer and it writes a boolean into that integer depending
2077 +** on whether or not the file has been renamed, moved, or deleted since it
2078 +** was first opened.
2079 +**
2080 +** <li>[[SQLITE_FCNTL_WIN32_GET_HANDLE]]
2081 +** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the
2082 +** underlying native file handle associated with a file handle. This file
2083 +** control interprets its argument as a pointer to a native file handle and
2084 +** writes the resulting value there.
2085 +**
2086 +** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]
2087 +** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This
2088 +** opcode causes the xFileControl method to swap the file handle with the one
2089 +** pointed to by the pArg argument. This capability is used during testing
2090 +** and only needs to be supported when SQLITE_TEST is defined.
2091 +**
2092 +** <li>[[SQLITE_FCNTL_WAL_BLOCK]]
2093 +** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
2094 +** be advantageous to block on the next WAL lock if the lock is not immediately
2095 +** available. The WAL subsystem issues this signal during rare
2096 +** circumstances in order to fix a problem with priority inversion.
2097 +** Applications should <em>not</em> use this file-control.
2098 +**
2099 +** <li>[[SQLITE_FCNTL_ZIPVFS]]
2100 +** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
2101 +** VFS should return SQLITE_NOTFOUND for this opcode.
2102 +**
2103 +** <li>[[SQLITE_FCNTL_RBU]]
2104 +** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
2105 +** the RBU extension only. All other VFS should return SQLITE_NOTFOUND for
2106 +** this opcode.
2107 +**
2108 +** <li>[[SQLITE_FCNTL_BEGIN_ATOMIC_WRITE]]
2109 +** If the [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] opcode returns SQLITE_OK, then
2110 +** the file descriptor is placed in "batch write mode", which
2111 +** means all subsequent write operations will be deferred and done
2112 +** atomically at the next [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]. Systems
2113 +** that do not support batch atomic writes will return SQLITE_NOTFOUND.
2114 +** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
2115 +** the closing [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] or
2116 +** [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE], SQLite will make
2117 +** no VFS interface calls on the same [sqlite3_file] file descriptor
2118 +** except for calls to the xWrite method and the xFileControl method
2119 +** with [SQLITE_FCNTL_SIZE_HINT].
2120 +**
2121 +** <li>[[SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]]
2122 +** The [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write
2123 +** operations since the previous successful call to
2124 +** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.
2125 +** This file control returns [SQLITE_OK] if and only if the writes were
2126 +** all performed successfully and have been committed to persistent storage.
2127 +** ^Regardless of whether or not it is successful, this file control takes
2128 +** the file descriptor out of batch write mode so that all subsequent
2129 +** write operations are independent.
2130 +** ^SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without
2131 +** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
2132 +**
2133 +** <li>[[SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE]]
2134 +** The [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write
2135 +** operations since the previous successful call to
2136 +** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.
2137 +** ^This file control takes the file descriptor out of batch write mode
2138 +** so that all subsequent write operations are independent.
2139 +** ^SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
2140 +** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
2141 +**
2142 +** <li>[[SQLITE_FCNTL_LOCK_TIMEOUT]]
2143 +** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode is used to configure a VFS
2144 +** to block for up to M milliseconds before failing when attempting to
2145 +** obtain a file lock using the xLock or xShmLock methods of the VFS.
2146 +** The parameter is a pointer to a 32-bit signed integer that contains
2147 +** the value that M is to be set to. Before returning, the 32-bit signed
2148 +** integer is overwritten with the previous value of M.
2149 +**
2150 +** <li>[[SQLITE_FCNTL_DATA_VERSION]]
2151 +** The [SQLITE_FCNTL_DATA_VERSION] opcode is used to detect changes to
2152 +** a database file. The argument is a pointer to a 32-bit unsigned integer.
2153 +** The "data version" for the pager is written into the pointer. The
2154 +** "data version" changes whenever any change occurs to the corresponding
2155 +** database file, either through SQL statements on the same database
2156 +** connection or through transactions committed by separate database
2157 +** connections possibly in other processes. The [sqlite3_total_changes()]
2158 +** interface can be used to find if any database on the connection has changed,
2159 +** but that interface responds to changes on TEMP as well as MAIN and does
2160 +** not provide a mechanism to detect changes to MAIN only. Also, the
2161 +** [sqlite3_total_changes()] interface responds to internal changes only and
2162 +** omits changes made by other database connections. The
2163 +** [PRAGMA data_version] command provides a mechanism to detect changes to
2164 +** a single attached database that occur due to other database connections,
2165 +** but omits changes implemented by the database connection on which it is
2166 +** called. This file control is the only mechanism to detect changes that
2167 +** happen either internally or externally and that are associated with
2168 +** a particular attached database.
2169 +**
2170 +** <li>[[SQLITE_FCNTL_CKPT_START]]
2171 +** The [SQLITE_FCNTL_CKPT_START] opcode is invoked from within a checkpoint
2172 +** in wal mode before the client starts to copy pages from the wal
2173 +** file to the database file.
2174 +**
2175 +** <li>[[SQLITE_FCNTL_CKPT_DONE]]
2176 +** The [SQLITE_FCNTL_CKPT_DONE] opcode is invoked from within a checkpoint
2177 +** in wal mode after the client has finished copying pages from the wal
2178 +** file to the database file, but before the *-shm file is updated to
2179 +** record the fact that the pages have been checkpointed.
2180 +** </ul>
2181 +*/
2182 +#define SQLITE_FCNTL_LOCKSTATE 1
2183 +#define SQLITE_FCNTL_GET_LOCKPROXYFILE 2
2184 +#define SQLITE_FCNTL_SET_LOCKPROXYFILE 3
2185 +#define SQLITE_FCNTL_LAST_ERRNO 4
2186 +#define SQLITE_FCNTL_SIZE_HINT 5
2187 +#define SQLITE_FCNTL_CHUNK_SIZE 6
2188 +#define SQLITE_FCNTL_FILE_POINTER 7
2189 +#define SQLITE_FCNTL_SYNC_OMITTED 8
2190 +#define SQLITE_FCNTL_WIN32_AV_RETRY 9
2191 +#define SQLITE_FCNTL_PERSIST_WAL 10
2192 +#define SQLITE_FCNTL_OVERWRITE 11
2193 +#define SQLITE_FCNTL_VFSNAME 12
2194 +#define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13
2195 +#define SQLITE_FCNTL_PRAGMA 14
2196 +#define SQLITE_FCNTL_BUSYHANDLER 15
2197 +#define SQLITE_FCNTL_TEMPFILENAME 16
2198 +#define SQLITE_FCNTL_MMAP_SIZE 18
2199 +#define SQLITE_FCNTL_TRACE 19
2200 +#define SQLITE_FCNTL_HAS_MOVED 20
2201 +#define SQLITE_FCNTL_SYNC 21
2202 +#define SQLITE_FCNTL_COMMIT_PHASETWO 22
2203 +#define SQLITE_FCNTL_WIN32_SET_HANDLE 23
2204 +#define SQLITE_FCNTL_WAL_BLOCK 24
2205 +#define SQLITE_FCNTL_ZIPVFS 25
2206 +#define SQLITE_FCNTL_RBU 26
2207 +#define SQLITE_FCNTL_VFS_POINTER 27
2208 +#define SQLITE_FCNTL_JOURNAL_POINTER 28
2209 +#define SQLITE_FCNTL_WIN32_GET_HANDLE 29
2210 +#define SQLITE_FCNTL_PDB 30
2211 +#define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31
2212 +#define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32
2213 +#define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33
2214 +#define SQLITE_FCNTL_LOCK_TIMEOUT 34
2215 +#define SQLITE_FCNTL_DATA_VERSION 35
2216 +#define SQLITE_FCNTL_SIZE_LIMIT 36
2217 +#define SQLITE_FCNTL_CKPT_DONE 37
2218 +#define SQLITE_FCNTL_RESERVE_BYTES 38
2219 +#define SQLITE_FCNTL_CKPT_START 39
2220 +
2221 +/* deprecated names */
2222 +#define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE
2223 +#define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE
2224 +#define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO
2225 +
2226 +
2227 +/*
2228 +** CAPI3REF: Mutex Handle
2229 +**
2230 +** The mutex module within SQLite defines [sqlite3_mutex] to be an
2231 +** abstract type for a mutex object. The SQLite core never looks
2232 +** at the internal representation of an [sqlite3_mutex]. It only
2233 +** deals with pointers to the [sqlite3_mutex] object.
2234 +**
2235 +** Mutexes are created using [sqlite3_mutex_alloc()].
2236 +*/
2237 +typedef struct sqlite3_mutex sqlite3_mutex;
2238 +
2239 +/*
2240 +** CAPI3REF: Loadable Extension Thunk
2241 +**
2242 +** A pointer to the opaque sqlite3_api_routines structure is passed as
2243 +** the third parameter to entry points of [loadable extensions]. This
2244 +** structure must be typedefed in order to work around compiler warnings
2245 +** on some platforms.
2246 +*/
2247 +typedef struct sqlite3_api_routines sqlite3_api_routines;
2248 +
2249 +/*
2250 +** CAPI3REF: OS Interface Object
2251 +**
2252 +** An instance of the sqlite3_vfs object defines the interface between
2253 +** the SQLite core and the underlying operating system. The "vfs"
2254 +** in the name of the object stands for "virtual file system". See
2255 +** the [VFS | VFS documentation] for further information.
2256 +**
2257 +** The VFS interface is sometimes extended by adding new methods onto
2258 +** the end. Each time such an extension occurs, the iVersion field
2259 +** is incremented. The iVersion value started out as 1 in
2260 +** SQLite [version 3.5.0] on [dateof:3.5.0], then increased to 2
2261 +** with SQLite [version 3.7.0] on [dateof:3.7.0], and then increased
2262 +** to 3 with SQLite [version 3.7.6] on [dateof:3.7.6]. Additional fields
2263 +** may be appended to the sqlite3_vfs object and the iVersion value
2264 +** may increase again in future versions of SQLite.
2265 +** Note that due to an oversight, the structure
2266 +** of the sqlite3_vfs object changed in the transition from
2267 +** SQLite [version 3.5.9] to [version 3.6.0] on [dateof:3.6.0]
2268 +** and yet the iVersion field was not increased.
2269 +**
2270 +** The szOsFile field is the size of the subclassed [sqlite3_file]
2271 +** structure used by this VFS. mxPathname is the maximum length of
2272 +** a pathname in this VFS.
2273 +**
2274 +** Registered sqlite3_vfs objects are kept on a linked list formed by
2275 +** the pNext pointer. The [sqlite3_vfs_register()]
2276 +** and [sqlite3_vfs_unregister()] interfaces manage this list
2277 +** in a thread-safe way. The [sqlite3_vfs_find()] interface
2278 +** searches the list. Neither the application code nor the VFS
2279 +** implementation should use the pNext pointer.
2280 +**
2281 +** The pNext field is the only field in the sqlite3_vfs
2282 +** structure that SQLite will ever modify. SQLite will only access
2283 +** or modify this field while holding a particular static mutex.
2284 +** The application should never modify anything within the sqlite3_vfs
2285 +** object once the object has been registered.
2286 +**
2287 +** The zName field holds the name of the VFS module. The name must
2288 +** be unique across all VFS modules.
2289 +**
2290 +** [[sqlite3_vfs.xOpen]]
2291 +** ^SQLite guarantees that the zFilename parameter to xOpen
2292 +** is either a NULL pointer or string obtained
2293 +** from xFullPathname() with an optional suffix added.
2294 +** ^If a suffix is added to the zFilename parameter, it will
2295 +** consist of a single "-" character followed by no more than
2296 +** 11 alphanumeric and/or "-" characters.
2297 +** ^SQLite further guarantees that
2298 +** the string will be valid and unchanged until xClose() is
2299 +** called. Because of the previous sentence,
2300 +** the [sqlite3_file] can safely store a pointer to the
2301 +** filename if it needs to remember the filename for some reason.
2302 +** If the zFilename parameter to xOpen is a NULL pointer then xOpen
2303 +** must invent its own temporary name for the file. ^Whenever the
2304 +** xFilename parameter is NULL it will also be the case that the
2305 +** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
2306 +**
2307 +** The flags argument to xOpen() includes all bits set in
2308 +** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
2309 +** or [sqlite3_open16()] is used, then flags includes at least
2310 +** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
2311 +** If xOpen() opens a file read-only then it sets *pOutFlags to
2312 +** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set.
2313 +**
2314 +** ^(SQLite will also add one of the following flags to the xOpen()
2315 +** call, depending on the object being opened:
2316 +**
2317 +** <ul>
2318 +** <li> [SQLITE_OPEN_MAIN_DB]
2319 +** <li> [SQLITE_OPEN_MAIN_JOURNAL]
2320 +** <li> [SQLITE_OPEN_TEMP_DB]
2321 +** <li> [SQLITE_OPEN_TEMP_JOURNAL]
2322 +** <li> [SQLITE_OPEN_TRANSIENT_DB]
2323 +** <li> [SQLITE_OPEN_SUBJOURNAL]
2324 +** <li> [SQLITE_OPEN_SUPER_JOURNAL]
2325 +** <li> [SQLITE_OPEN_WAL]
2326 +** </ul>)^
2327 +**
2328 +** The file I/O implementation can use the object type flags to
2329 +** change the way it deals with files. For example, an application
2330 +** that does not care about crash recovery or rollback might make
2331 +** the open of a journal file a no-op. Writes to this journal would
2332 +** also be no-ops, and any attempt to read the journal would return
2333 +** SQLITE_IOERR. Or the implementation might recognize that a database
2334 +** file will be doing page-aligned sector reads and writes in a random
2335 +** order and set up its I/O subsystem accordingly.
2336 +**
2337 +** SQLite might also add one of the following flags to the xOpen method:
2338 +**
2339 +** <ul>
2340 +** <li> [SQLITE_OPEN_DELETEONCLOSE]
2341 +** <li> [SQLITE_OPEN_EXCLUSIVE]
2342 +** </ul>
2343 +**
2344 +** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
2345 +** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE]
2346 +** will be set for TEMP databases and their journals, transient
2347 +** databases, and subjournals.
2348 +**
2349 +** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
2350 +** with the [SQLITE_OPEN_CREATE] flag, which are both directly
2351 +** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
2352 +** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
2353 +** SQLITE_OPEN_CREATE, is used to indicate that file should always
2354 +** be created, and that it is an error if it already exists.
2355 +** It is <i>not</i> used to indicate the file should be opened
2356 +** for exclusive access.
2357 +**
2358 +** ^At least szOsFile bytes of memory are allocated by SQLite
2359 +** to hold the [sqlite3_file] structure passed as the third
2360 +** argument to xOpen. The xOpen method does not have to
2361 +** allocate the structure; it should just fill it in. Note that
2362 +** the xOpen method must set the sqlite3_file.pMethods to either
2363 +** a valid [sqlite3_io_methods] object or to NULL. xOpen must do
2364 +** this even if the open fails. SQLite expects that the sqlite3_file.pMethods
2365 +** element will be valid after xOpen returns regardless of the success
2366 +** or failure of the xOpen call.
2367 +**
2368 +** [[sqlite3_vfs.xAccess]]
2369 +** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
2370 +** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
2371 +** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
2372 +** to test whether a file is at least readable. The SQLITE_ACCESS_READ
2373 +** flag is never actually used and is not implemented in the built-in
2374 +** VFSes of SQLite. The file is named by the second argument and can be a
2375 +** directory. The xAccess method returns [SQLITE_OK] on success or some
2376 +** non-zero error code if there is an I/O error or if the name of
2377 +** the file given in the second argument is illegal. If SQLITE_OK
2378 +** is returned, then non-zero or zero is written into *pResOut to indicate
2379 +** whether or not the file is accessible.
2380 +**
2381 +** ^SQLite will always allocate at least mxPathname+1 bytes for the
2382 +** output buffer xFullPathname. The exact size of the output buffer
2383 +** is also passed as a parameter to both methods. If the output buffer
2384 +** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
2385 +** handled as a fatal error by SQLite, vfs implementations should endeavor
2386 +** to prevent this by setting mxPathname to a sufficiently large value.
2387 +**
2388 +** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
2389 +** interfaces are not strictly a part of the filesystem, but they are
2390 +** included in the VFS structure for completeness.
2391 +** The xRandomness() function attempts to return nBytes bytes
2392 +** of good-quality randomness into zOut. The return value is
2393 +** the actual number of bytes of randomness obtained.
2394 +** The xSleep() method causes the calling thread to sleep for at
2395 +** least the number of microseconds given. ^The xCurrentTime()
2396 +** method returns a Julian Day Number for the current date and time as
2397 +** a floating point value.
2398 +** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
2399 +** Day Number multiplied by 86400000 (the number of milliseconds in
2400 +** a 24-hour day).
2401 +** ^SQLite will use the xCurrentTimeInt64() method to get the current
2402 +** date and time if that method is available (if iVersion is 2 or
2403 +** greater and the function pointer is not NULL) and will fall back
2404 +** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
2405 +**
2406 +** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
2407 +** are not used by the SQLite core. These optional interfaces are provided
2408 +** by some VFSes to facilitate testing of the VFS code. By overriding
2409 +** system calls with functions under its control, a test program can
2410 +** simulate faults and error conditions that would otherwise be difficult
2411 +** or impossible to induce. The set of system calls that can be overridden
2412 +** varies from one VFS to another, and from one version of the same VFS to the
2413 +** next. Applications that use these interfaces must be prepared for any
2414 +** or all of these interfaces to be NULL or for their behavior to change
2415 +** from one release to the next. Applications must not attempt to access
2416 +** any of these methods if the iVersion of the VFS is less than 3.
2417 +*/
2418 +typedef struct sqlite3_vfs sqlite3_vfs;
2419 +typedef void (*sqlite3_syscall_ptr)(void);
2420 +struct sqlite3_vfs {
2421 + int iVersion; /* Structure version number (currently 3) */
2422 + int szOsFile; /* Size of subclassed sqlite3_file */
2423 + int mxPathname; /* Maximum file pathname length */
2424 + sqlite3_vfs *pNext; /* Next registered VFS */
2425 + const char *zName; /* Name of this virtual file system */
2426 + void *pAppData; /* Pointer to application-specific data */
2427 + int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
2428 + int flags, int *pOutFlags);
2429 + int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
2430 + int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
2431 + int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
2432 + void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
2433 + void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
2434 + void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
2435 + void (*xDlClose)(sqlite3_vfs*, void*);
2436 + int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
2437 + int (*xSleep)(sqlite3_vfs*, int microseconds);
2438 + int (*xCurrentTime)(sqlite3_vfs*, double*);
2439 + int (*xGetLastError)(sqlite3_vfs*, int, char *);
2440 + /*
2441 + ** The methods above are in version 1 of the sqlite_vfs object
2442 + ** definition. Those that follow are added in version 2 or later
2443 + */
2444 + int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
2445 + /*
2446 + ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
2447 + ** Those below are for version 3 and greater.
2448 + */
2449 + int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
2450 + sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
2451 + const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
2452 + /*
2453 + ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
2454 + ** New fields may be appended in future versions. The iVersion
2455 + ** value will increment whenever this happens.
2456 + */
2457 +};
2458 +
2459 +/*
2460 +** CAPI3REF: Flags for the xAccess VFS method
2461 +**
2462 +** These integer constants can be used as the third parameter to
2463 +** the xAccess method of an [sqlite3_vfs] object. They determine
2464 +** what kind of permissions the xAccess method is looking for.
2465 +** With SQLITE_ACCESS_EXISTS, the xAccess method
2466 +** simply checks whether the file exists.
2467 +** With SQLITE_ACCESS_READWRITE, the xAccess method
2468 +** checks whether the named directory is both readable and writable
2469 +** (in other words, if files can be added, removed, and renamed within
2470 +** the directory).
2471 +** The SQLITE_ACCESS_READWRITE constant is currently used only by the
2472 +** [temp_store_directory pragma], though this could change in a future
2473 +** release of SQLite.
2474 +** With SQLITE_ACCESS_READ, the xAccess method
2475 +** checks whether the file is readable. The SQLITE_ACCESS_READ constant is
2476 +** currently unused, though it might be used in a future release of
2477 +** SQLite.
2478 +*/
2479 +#define SQLITE_ACCESS_EXISTS 0
2480 +#define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */
2481 +#define SQLITE_ACCESS_READ 2 /* Unused */
2482 +
2483 +/*
2484 +** CAPI3REF: Flags for the xShmLock VFS method
2485 +**
2486 +** These integer constants define the various locking operations
2487 +** allowed by the xShmLock method of [sqlite3_io_methods]. The
2488 +** following are the only legal combinations of flags to the
2489 +** xShmLock method:
2490 +**
2491 +** <ul>
2492 +** <li> SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
2493 +** <li> SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
2494 +** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
2495 +** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
2496 +** </ul>
2497 +**
2498 +** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
2499 +** was given on the corresponding lock.
2500 +**
2501 +** The xShmLock method can transition between unlocked and SHARED or
2502 +** between unlocked and EXCLUSIVE. It cannot transition between SHARED
2503 +** and EXCLUSIVE.
2504 +*/
2505 +#define SQLITE_SHM_UNLOCK 1
2506 +#define SQLITE_SHM_LOCK 2
2507 +#define SQLITE_SHM_SHARED 4
2508 +#define SQLITE_SHM_EXCLUSIVE 8
2509 +
2510 +/*
2511 +** CAPI3REF: Maximum xShmLock index
2512 +**
2513 +** The xShmLock method on [sqlite3_io_methods] may use values
2514 +** between 0 and this upper bound as its "offset" argument.
2515 +** The SQLite core will never attempt to acquire or release a
2516 +** lock outside of this range
2517 +*/
2518 +#define SQLITE_SHM_NLOCK 8
2519 +
2520 +
2521 +/*
2522 +** CAPI3REF: Initialize The SQLite Library
2523 +**
2524 +** ^The sqlite3_initialize() routine initializes the
2525 +** SQLite library. ^The sqlite3_shutdown() routine
2526 +** deallocates any resources that were allocated by sqlite3_initialize().
2527 +** These routines are designed to aid in process initialization and
2528 +** shutdown on embedded systems. Workstation applications using
2529 +** SQLite normally do not need to invoke either of these routines.
2530 +**
2531 +** A call to sqlite3_initialize() is an "effective" call if it is
2532 +** the first time sqlite3_initialize() is invoked during the lifetime of
2533 +** the process, or if it is the first time sqlite3_initialize() is invoked
2534 +** following a call to sqlite3_shutdown(). ^(Only an effective call
2535 +** of sqlite3_initialize() does any initialization. All other calls
2536 +** are harmless no-ops.)^
2537 +**
2538 +** A call to sqlite3_shutdown() is an "effective" call if it is the first
2539 +** call to sqlite3_shutdown() since the last sqlite3_initialize(). ^(Only
2540 +** an effective call to sqlite3_shutdown() does any deinitialization.
2541 +** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
2542 +**
2543 +** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
2544 +** is not. The sqlite3_shutdown() interface must only be called from a
2545 +** single thread. All open [database connections] must be closed and all
2546 +** other SQLite resources must be deallocated prior to invoking
2547 +** sqlite3_shutdown().
2548 +**
2549 +** Among other things, ^sqlite3_initialize() will invoke
2550 +** sqlite3_os_init(). Similarly, ^sqlite3_shutdown()
2551 +** will invoke sqlite3_os_end().
2552 +**
2553 +** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
2554 +** ^If for some reason, sqlite3_initialize() is unable to initialize
2555 +** the library (perhaps it is unable to allocate a needed resource such
2556 +** as a mutex) it returns an [error code] other than [SQLITE_OK].
2557 +**
2558 +** ^The sqlite3_initialize() routine is called internally by many other
2559 +** SQLite interfaces so that an application usually does not need to
2560 +** invoke sqlite3_initialize() directly. For example, [sqlite3_open()]
2561 +** calls sqlite3_initialize() so the SQLite library will be automatically
2562 +** initialized when [sqlite3_open()] is called if it has not be initialized
2563 +** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
2564 +** compile-time option, then the automatic calls to sqlite3_initialize()
2565 +** are omitted and the application must call sqlite3_initialize() directly
2566 +** prior to using any other SQLite interface. For maximum portability,
2567 +** it is recommended that applications always invoke sqlite3_initialize()
2568 +** directly prior to using any other SQLite interface. Future releases
2569 +** of SQLite may require this. In other words, the behavior exhibited
2570 +** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
2571 +** default behavior in some future release of SQLite.
2572 +**
2573 +** The sqlite3_os_init() routine does operating-system specific
2574 +** initialization of the SQLite library. The sqlite3_os_end()
2575 +** routine undoes the effect of sqlite3_os_init(). Typical tasks
2576 +** performed by these routines include allocation or deallocation
2577 +** of static resources, initialization of global variables,
2578 +** setting up a default [sqlite3_vfs] module, or setting up
2579 +** a default configuration using [sqlite3_config()].
2580 +**
2581 +** The application should never invoke either sqlite3_os_init()
2582 +** or sqlite3_os_end() directly. The application should only invoke
2583 +** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init()
2584 +** interface is called automatically by sqlite3_initialize() and
2585 +** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
2586 +** implementations for sqlite3_os_init() and sqlite3_os_end()
2587 +** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
2588 +** When [custom builds | built for other platforms]
2589 +** (using the [SQLITE_OS_OTHER=1] compile-time
2590 +** option) the application must supply a suitable implementation for
2591 +** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
2592 +** implementation of sqlite3_os_init() or sqlite3_os_end()
2593 +** must return [SQLITE_OK] on success and some other [error code] upon
2594 +** failure.
2595 +*/
2596 +SQLITE_API int sqlite3_initialize(void);
2597 +SQLITE_API int sqlite3_shutdown(void);
2598 +SQLITE_API int sqlite3_os_init(void);
2599 +SQLITE_API int sqlite3_os_end(void);
2600 +
2601 +/*
2602 +** CAPI3REF: Configuring The SQLite Library
2603 +**
2604 +** The sqlite3_config() interface is used to make global configuration
2605 +** changes to SQLite in order to tune SQLite to the specific needs of
2606 +** the application. The default configuration is recommended for most
2607 +** applications and so this routine is usually not necessary. It is
2608 +** provided to support rare applications with unusual needs.
2609 +**
2610 +** <b>The sqlite3_config() interface is not threadsafe. The application
2611 +** must ensure that no other SQLite interfaces are invoked by other
2612 +** threads while sqlite3_config() is running.</b>
2613 +**
2614 +** The sqlite3_config() interface
2615 +** may only be invoked prior to library initialization using
2616 +** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
2617 +** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
2618 +** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
2619 +** Note, however, that ^sqlite3_config() can be called as part of the
2620 +** implementation of an application-defined [sqlite3_os_init()].
2621 +**
2622 +** The first argument to sqlite3_config() is an integer
2623 +** [configuration option] that determines
2624 +** what property of SQLite is to be configured. Subsequent arguments
2625 +** vary depending on the [configuration option]
2626 +** in the first argument.
2627 +**
2628 +** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
2629 +** ^If the option is unknown or SQLite is unable to set the option
2630 +** then this routine returns a non-zero [error code].
2631 +*/
2632 +SQLITE_API int sqlite3_config(int, ...);
2633 +
2634 +/*
2635 +** CAPI3REF: Configure database connections
2636 +** METHOD: sqlite3
2637 +**
2638 +** The sqlite3_db_config() interface is used to make configuration
2639 +** changes to a [database connection]. The interface is similar to
2640 +** [sqlite3_config()] except that the changes apply to a single
2641 +** [database connection] (specified in the first argument).
2642 +**
2643 +** The second argument to sqlite3_db_config(D,V,...) is the
2644 +** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code
2645 +** that indicates what aspect of the [database connection] is being configured.
2646 +** Subsequent arguments vary depending on the configuration verb.
2647 +**
2648 +** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
2649 +** the call is considered successful.
2650 +*/
2651 +SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
2652 +
2653 +/*
2654 +** CAPI3REF: Memory Allocation Routines
2655 +**
2656 +** An instance of this object defines the interface between SQLite
2657 +** and low-level memory allocation routines.
2658 +**
2659 +** This object is used in only one place in the SQLite interface.
2660 +** A pointer to an instance of this object is the argument to
2661 +** [sqlite3_config()] when the configuration option is
2662 +** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].
2663 +** By creating an instance of this object
2664 +** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
2665 +** during configuration, an application can specify an alternative
2666 +** memory allocation subsystem for SQLite to use for all of its
2667 +** dynamic memory needs.
2668 +**
2669 +** Note that SQLite comes with several [built-in memory allocators]
2670 +** that are perfectly adequate for the overwhelming majority of applications
2671 +** and that this object is only useful to a tiny minority of applications
2672 +** with specialized memory allocation requirements. This object is
2673 +** also used during testing of SQLite in order to specify an alternative
2674 +** memory allocator that simulates memory out-of-memory conditions in
2675 +** order to verify that SQLite recovers gracefully from such
2676 +** conditions.
2677 +**
2678 +** The xMalloc, xRealloc, and xFree methods must work like the
2679 +** malloc(), realloc() and free() functions from the standard C library.
2680 +** ^SQLite guarantees that the second argument to
2681 +** xRealloc is always a value returned by a prior call to xRoundup.
2682 +**
2683 +** xSize should return the allocated size of a memory allocation
2684 +** previously obtained from xMalloc or xRealloc. The allocated size
2685 +** is always at least as big as the requested size but may be larger.
2686 +**
2687 +** The xRoundup method returns what would be the allocated size of
2688 +** a memory allocation given a particular requested size. Most memory
2689 +** allocators round up memory allocations at least to the next multiple
2690 +** of 8. Some allocators round up to a larger multiple or to a power of 2.
2691 +** Every memory allocation request coming in through [sqlite3_malloc()]
2692 +** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0,
2693 +** that causes the corresponding memory allocation to fail.
2694 +**
2695 +** The xInit method initializes the memory allocator. For example,
2696 +** it might allocate any required mutexes or initialize internal data
2697 +** structures. The xShutdown method is invoked (indirectly) by
2698 +** [sqlite3_shutdown()] and should deallocate any resources acquired
2699 +** by xInit. The pAppData pointer is used as the only parameter to
2700 +** xInit and xShutdown.
2701 +**
2702 +** SQLite holds the [SQLITE_MUTEX_STATIC_MAIN] mutex when it invokes
2703 +** the xInit method, so the xInit method need not be threadsafe. The
2704 +** xShutdown method is only called from [sqlite3_shutdown()] so it does
2705 +** not need to be threadsafe either. For all other methods, SQLite
2706 +** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
2707 +** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
2708 +** it is by default) and so the methods are automatically serialized.
2709 +** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
2710 +** methods must be threadsafe or else make their own arrangements for
2711 +** serialization.
2712 +**
2713 +** SQLite will never invoke xInit() more than once without an intervening
2714 +** call to xShutdown().
2715 +*/
2716 +typedef struct sqlite3_mem_methods sqlite3_mem_methods;
2717 +struct sqlite3_mem_methods {
2718 + void *(*xMalloc)(int); /* Memory allocation function */
2719 + void (*xFree)(void*); /* Free a prior allocation */
2720 + void *(*xRealloc)(void*,int); /* Resize an allocation */
2721 + int (*xSize)(void*); /* Return the size of an allocation */
2722 + int (*xRoundup)(int); /* Round up request size to allocation size */
2723 + int (*xInit)(void*); /* Initialize the memory allocator */
2724 + void (*xShutdown)(void*); /* Deinitialize the memory allocator */
2725 + void *pAppData; /* Argument to xInit() and xShutdown() */
2726 +};
2727 +
2728 +/*
2729 +** CAPI3REF: Configuration Options
2730 +** KEYWORDS: {configuration option}
2731 +**
2732 +** These constants are the available integer configuration options that
2733 +** can be passed as the first argument to the [sqlite3_config()] interface.
2734 +**
2735 +** New configuration options may be added in future releases of SQLite.
2736 +** Existing configuration options might be discontinued. Applications
2737 +** should check the return code from [sqlite3_config()] to make sure that
2738 +** the call worked. The [sqlite3_config()] interface will return a
2739 +** non-zero [error code] if a discontinued or unsupported configuration option
2740 +** is invoked.
2741 +**
2742 +** <dl>
2743 +** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
2744 +** <dd>There are no arguments to this option. ^This option sets the
2745 +** [threading mode] to Single-thread. In other words, it disables
2746 +** all mutexing and puts SQLite into a mode where it can only be used
2747 +** by a single thread. ^If SQLite is compiled with
2748 +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
2749 +** it is not possible to change the [threading mode] from its default
2750 +** value of Single-thread and so [sqlite3_config()] will return
2751 +** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
2752 +** configuration option.</dd>
2753 +**
2754 +** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
2755 +** <dd>There are no arguments to this option. ^This option sets the
2756 +** [threading mode] to Multi-thread. In other words, it disables
2757 +** mutexing on [database connection] and [prepared statement] objects.
2758 +** The application is responsible for serializing access to
2759 +** [database connections] and [prepared statements]. But other mutexes
2760 +** are enabled so that SQLite will be safe to use in a multi-threaded
2761 +** environment as long as no two threads attempt to use the same
2762 +** [database connection] at the same time. ^If SQLite is compiled with
2763 +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
2764 +** it is not possible to set the Multi-thread [threading mode] and
2765 +** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
2766 +** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
2767 +**
2768 +** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
2769 +** <dd>There are no arguments to this option. ^This option sets the
2770 +** [threading mode] to Serialized. In other words, this option enables
2771 +** all mutexes including the recursive
2772 +** mutexes on [database connection] and [prepared statement] objects.
2773 +** In this mode (which is the default when SQLite is compiled with
2774 +** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
2775 +** to [database connections] and [prepared statements] so that the
2776 +** application is free to use the same [database connection] or the
2777 +** same [prepared statement] in different threads at the same time.
2778 +** ^If SQLite is compiled with
2779 +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
2780 +** it is not possible to set the Serialized [threading mode] and
2781 +** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
2782 +** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
2783 +**
2784 +** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
2785 +** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is
2786 +** a pointer to an instance of the [sqlite3_mem_methods] structure.
2787 +** The argument specifies
2788 +** alternative low-level memory allocation routines to be used in place of
2789 +** the memory allocation routines built into SQLite.)^ ^SQLite makes
2790 +** its own private copy of the content of the [sqlite3_mem_methods] structure
2791 +** before the [sqlite3_config()] call returns.</dd>
2792 +**
2793 +** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
2794 +** <dd> ^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which
2795 +** is a pointer to an instance of the [sqlite3_mem_methods] structure.
2796 +** The [sqlite3_mem_methods]
2797 +** structure is filled with the currently defined memory allocation routines.)^
2798 +** This option can be used to overload the default memory allocation
2799 +** routines with a wrapper that simulations memory allocation failure or
2800 +** tracks memory usage, for example. </dd>
2801 +**
2802 +** [[SQLITE_CONFIG_SMALL_MALLOC]] <dt>SQLITE_CONFIG_SMALL_MALLOC</dt>
2803 +** <dd> ^The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of
2804 +** type int, interpreted as a boolean, which if true provides a hint to
2805 +** SQLite that it should avoid large memory allocations if possible.
2806 +** SQLite will run faster if it is free to make large memory allocations,
2807 +** but some application might prefer to run slower in exchange for
2808 +** guarantees about memory fragmentation that are possible if large
2809 +** allocations are avoided. This hint is normally off.
2810 +** </dd>
2811 +**
2812 +** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
2813 +** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
2814 +** interpreted as a boolean, which enables or disables the collection of
2815 +** memory allocation statistics. ^(When memory allocation statistics are
2816 +** disabled, the following SQLite interfaces become non-operational:
2817 +** <ul>
2818 +** <li> [sqlite3_hard_heap_limit64()]
2819 +** <li> [sqlite3_memory_used()]
2820 +** <li> [sqlite3_memory_highwater()]
2821 +** <li> [sqlite3_soft_heap_limit64()]
2822 +** <li> [sqlite3_status64()]
2823 +** </ul>)^
2824 +** ^Memory allocation statistics are enabled by default unless SQLite is
2825 +** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
2826 +** allocation statistics are disabled by default.
2827 +** </dd>
2828 +**
2829 +** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
2830 +** <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
2831 +** </dd>
2832 +**
2833 +** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
2834 +** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
2835 +** that SQLite can use for the database page cache with the default page
2836 +** cache implementation.
2837 +** This configuration option is a no-op if an application-defined page
2838 +** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
2839 +** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
2840 +** 8-byte aligned memory (pMem), the size of each page cache line (sz),
2841 +** and the number of cache lines (N).
2842 +** The sz argument should be the size of the largest database page
2843 +** (a power of two between 512 and 65536) plus some extra bytes for each
2844 +** page header. ^The number of extra bytes needed by the page header
2845 +** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].
2846 +** ^It is harmless, apart from the wasted memory,
2847 +** for the sz parameter to be larger than necessary. The pMem
2848 +** argument must be either a NULL pointer or a pointer to an 8-byte
2849 +** aligned block of memory of at least sz*N bytes, otherwise
2850 +** subsequent behavior is undefined.
2851 +** ^When pMem is not NULL, SQLite will strive to use the memory provided
2852 +** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
2853 +** a page cache line is larger than sz bytes or if all of the pMem buffer
2854 +** is exhausted.
2855 +** ^If pMem is NULL and N is non-zero, then each database connection
2856 +** does an initial bulk allocation for page cache memory
2857 +** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
2858 +** of -1024*N bytes if N is negative, . ^If additional
2859 +** page cache memory is needed beyond what is provided by the initial
2860 +** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
2861 +** additional cache line. </dd>
2862 +**
2863 +** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
2864 +** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer
2865 +** that SQLite will use for all of its dynamic memory allocation needs
2866 +** beyond those provided for by [SQLITE_CONFIG_PAGECACHE].
2867 +** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
2868 +** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
2869 +** [SQLITE_ERROR] if invoked otherwise.
2870 +** ^There are three arguments to SQLITE_CONFIG_HEAP:
2871 +** An 8-byte aligned pointer to the memory,
2872 +** the number of bytes in the memory buffer, and the minimum allocation size.
2873 +** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
2874 +** to using its default memory allocator (the system malloc() implementation),
2875 +** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the
2876 +** memory pointer is not NULL then the alternative memory
2877 +** allocator is engaged to handle all of SQLites memory allocation needs.
2878 +** The first pointer (the memory pointer) must be aligned to an 8-byte
2879 +** boundary or subsequent behavior of SQLite will be undefined.
2880 +** The minimum allocation size is capped at 2**12. Reasonable values
2881 +** for the minimum allocation size are 2**5 through 2**8.</dd>
2882 +**
2883 +** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
2884 +** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
2885 +** pointer to an instance of the [sqlite3_mutex_methods] structure.
2886 +** The argument specifies alternative low-level mutex routines to be used
2887 +** in place the mutex routines built into SQLite.)^ ^SQLite makes a copy of
2888 +** the content of the [sqlite3_mutex_methods] structure before the call to
2889 +** [sqlite3_config()] returns. ^If SQLite is compiled with
2890 +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
2891 +** the entire mutexing subsystem is omitted from the build and hence calls to
2892 +** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
2893 +** return [SQLITE_ERROR].</dd>
2894 +**
2895 +** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
2896 +** <dd> ^(The SQLITE_CONFIG_GETMUTEX option takes a single argument which
2897 +** is a pointer to an instance of the [sqlite3_mutex_methods] structure. The
2898 +** [sqlite3_mutex_methods]
2899 +** structure is filled with the currently defined mutex routines.)^
2900 +** This option can be used to overload the default mutex allocation
2901 +** routines with a wrapper used to track mutex usage for performance
2902 +** profiling or testing, for example. ^If SQLite is compiled with
2903 +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
2904 +** the entire mutexing subsystem is omitted from the build and hence calls to
2905 +** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
2906 +** return [SQLITE_ERROR].</dd>
2907 +**
2908 +** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
2909 +** <dd> ^(The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
2910 +** the default size of lookaside memory on each [database connection].
2911 +** The first argument is the
2912 +** size of each lookaside buffer slot and the second is the number of
2913 +** slots allocated to each database connection.)^ ^(SQLITE_CONFIG_LOOKASIDE
2914 +** sets the <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
2915 +** option to [sqlite3_db_config()] can be used to change the lookaside
2916 +** configuration on individual connections.)^ </dd>
2917 +**
2918 +** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
2919 +** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
2920 +** a pointer to an [sqlite3_pcache_methods2] object. This object specifies
2921 +** the interface to a custom page cache implementation.)^
2922 +** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
2923 +**
2924 +** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
2925 +** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
2926 +** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of
2927 +** the current page cache implementation into that object.)^ </dd>
2928 +**
2929 +** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
2930 +** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
2931 +** global [error log].
2932 +** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
2933 +** function with a call signature of void(*)(void*,int,const char*),
2934 +** and a pointer to void. ^If the function pointer is not NULL, it is
2935 +** invoked by [sqlite3_log()] to process each logging event. ^If the
2936 +** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
2937 +** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
2938 +** passed through as the first parameter to the application-defined logger
2939 +** function whenever that function is invoked. ^The second parameter to
2940 +** the logger function is a copy of the first parameter to the corresponding
2941 +** [sqlite3_log()] call and is intended to be a [result code] or an
2942 +** [extended result code]. ^The third parameter passed to the logger is
2943 +** log message after formatting via [sqlite3_snprintf()].
2944 +** The SQLite logging interface is not reentrant; the logger function
2945 +** supplied by the application must not invoke any SQLite interface.
2946 +** In a multi-threaded application, the application-defined logger
2947 +** function must be threadsafe. </dd>
2948 +**
2949 +** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
2950 +** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
2951 +** If non-zero, then URI handling is globally enabled. If the parameter is zero,
2952 +** then URI handling is globally disabled.)^ ^If URI handling is globally
2953 +** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],
2954 +** [sqlite3_open16()] or
2955 +** specified as part of [ATTACH] commands are interpreted as URIs, regardless
2956 +** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
2957 +** connection is opened. ^If it is globally disabled, filenames are
2958 +** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
2959 +** database connection is opened. ^(By default, URI handling is globally
2960 +** disabled. The default value may be changed by compiling with the
2961 +** [SQLITE_USE_URI] symbol defined.)^
2962 +**
2963 +** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
2964 +** <dd>^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
2965 +** argument which is interpreted as a boolean in order to enable or disable
2966 +** the use of covering indices for full table scans in the query optimizer.
2967 +** ^The default setting is determined
2968 +** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
2969 +** if that compile-time option is omitted.
2970 +** The ability to disable the use of covering indices for full table scans
2971 +** is because some incorrectly coded legacy applications might malfunction
2972 +** when the optimization is enabled. Providing the ability to
2973 +** disable the optimization allows the older, buggy application code to work
2974 +** without change even with newer versions of SQLite.
2975 +**
2976 +** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]
2977 +** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
2978 +** <dd> These options are obsolete and should not be used by new code.
2979 +** They are retained for backwards compatibility but are now no-ops.
2980 +** </dd>
2981 +**
2982 +** [[SQLITE_CONFIG_SQLLOG]]
2983 +** <dt>SQLITE_CONFIG_SQLLOG
2984 +** <dd>This option is only available if sqlite is compiled with the
2985 +** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
2986 +** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
2987 +** The second should be of type (void*). The callback is invoked by the library
2988 +** in three separate circumstances, identified by the value passed as the
2989 +** fourth parameter. If the fourth parameter is 0, then the database connection
2990 +** passed as the second argument has just been opened. The third argument
2991 +** points to a buffer containing the name of the main database file. If the
2992 +** fourth parameter is 1, then the SQL statement that the third parameter
2993 +** points to has just been executed. Or, if the fourth parameter is 2, then
2994 +** the connection being passed as the second parameter is being closed. The
2995 +** third parameter is passed NULL In this case. An example of using this
2996 +** configuration option can be seen in the "test_sqllog.c" source file in
2997 +** the canonical SQLite source tree.</dd>
2998 +**
2999 +** [[SQLITE_CONFIG_MMAP_SIZE]]
3000 +** <dt>SQLITE_CONFIG_MMAP_SIZE
3001 +** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
3002 +** that are the default mmap size limit (the default setting for
3003 +** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.
3004 +** ^The default setting can be overridden by each database connection using
3005 +** either the [PRAGMA mmap_size] command, or by using the
3006 +** [SQLITE_FCNTL_MMAP_SIZE] file control. ^(The maximum allowed mmap size
3007 +** will be silently truncated if necessary so that it does not exceed the
3008 +** compile-time maximum mmap size set by the
3009 +** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
3010 +** ^If either argument to this option is negative, then that argument is
3011 +** changed to its compile-time default.
3012 +**
3013 +** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
3014 +** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
3015 +** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
3016 +** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
3017 +** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
3018 +** that specifies the maximum size of the created heap.
3019 +**
3020 +** [[SQLITE_CONFIG_PCACHE_HDRSZ]]
3021 +** <dt>SQLITE_CONFIG_PCACHE_HDRSZ
3022 +** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
3023 +** is a pointer to an integer and writes into that integer the number of extra
3024 +** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE].
3025 +** The amount of extra space required can change depending on the compiler,
3026 +** target platform, and SQLite version.
3027 +**
3028 +** [[SQLITE_CONFIG_PMASZ]]
3029 +** <dt>SQLITE_CONFIG_PMASZ
3030 +** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which
3031 +** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
3032 +** sorter to that integer. The default minimum PMA Size is set by the
3033 +** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched
3034 +** to help with sort operations when multithreaded sorting
3035 +** is enabled (using the [PRAGMA threads] command) and the amount of content
3036 +** to be sorted exceeds the page size times the minimum of the
3037 +** [PRAGMA cache_size] setting and this value.
3038 +**
3039 +** [[SQLITE_CONFIG_STMTJRNL_SPILL]]
3040 +** <dt>SQLITE_CONFIG_STMTJRNL_SPILL
3041 +** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
3042 +** becomes the [statement journal] spill-to-disk threshold.
3043 +** [Statement journals] are held in memory until their size (in bytes)
3044 +** exceeds this threshold, at which point they are written to disk.
3045 +** Or if the threshold is -1, statement journals are always held
3046 +** exclusively in memory.
3047 +** Since many statement journals never become large, setting the spill
3048 +** threshold to a value such as 64KiB can greatly reduce the amount of
3049 +** I/O required to support statement rollback.
3050 +** The default value for this setting is controlled by the
3051 +** [SQLITE_STMTJRNL_SPILL] compile-time option.
3052 +**
3053 +** [[SQLITE_CONFIG_SORTERREF_SIZE]]
3054 +** <dt>SQLITE_CONFIG_SORTERREF_SIZE
3055 +** <dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter
3056 +** of type (int) - the new value of the sorter-reference size threshold.
3057 +** Usually, when SQLite uses an external sort to order records according
3058 +** to an ORDER BY clause, all fields required by the caller are present in the
3059 +** sorted records. However, if SQLite determines based on the declared type
3060 +** of a table column that its values are likely to be very large - larger
3061 +** than the configured sorter-reference size threshold - then a reference
3062 +** is stored in each sorted record and the required column values loaded
3063 +** from the database as records are returned in sorted order. The default
3064 +** value for this option is to never use this optimization. Specifying a
3065 +** negative value for this option restores the default behaviour.
3066 +** This option is only available if SQLite is compiled with the
3067 +** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option.
3068 +**
3069 +** [[SQLITE_CONFIG_MEMDB_MAXSIZE]]
3070 +** <dt>SQLITE_CONFIG_MEMDB_MAXSIZE
3071 +** <dd>The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter
3072 +** [sqlite3_int64] parameter which is the default maximum size for an in-memory
3073 +** database created using [sqlite3_deserialize()]. This default maximum
3074 +** size can be adjusted up or down for individual databases using the
3075 +** [SQLITE_FCNTL_SIZE_LIMIT] [sqlite3_file_control|file-control]. If this
3076 +** configuration setting is never used, then the default maximum is determined
3077 +** by the [SQLITE_MEMDB_DEFAULT_MAXSIZE] compile-time option. If that
3078 +** compile-time option is not set, then the default maximum is 1073741824.
3079 +** </dl>
3080 +*/
3081 +#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
3082 +#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
3083 +#define SQLITE_CONFIG_SERIALIZED 3 /* nil */
3084 +#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
3085 +#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
3086 +#define SQLITE_CONFIG_SCRATCH 6 /* No longer used */
3087 +#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
3088 +#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
3089 +#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
3090 +#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
3091 +#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
3092 +/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
3093 +#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
3094 +#define SQLITE_CONFIG_PCACHE 14 /* no-op */
3095 +#define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
3096 +#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
3097 +#define SQLITE_CONFIG_URI 17 /* int */
3098 +#define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */
3099 +#define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
3100 +#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */
3101 +#define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
3102 +#define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
3103 +#define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
3104 +#define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */
3105 +#define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
3106 +#define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */
3107 +#define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */
3108 +#define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */
3109 +#define SQLITE_CONFIG_MEMDB_MAXSIZE 29 /* sqlite3_int64 */
3110 +
3111 +/*
3112 +** CAPI3REF: Database Connection Configuration Options
3113 +**
3114 +** These constants are the available integer configuration options that
3115 +** can be passed as the second argument to the [sqlite3_db_config()] interface.
3116 +**
3117 +** New configuration options may be added in future releases of SQLite.
3118 +** Existing configuration options might be discontinued. Applications
3119 +** should check the return code from [sqlite3_db_config()] to make sure that
3120 +** the call worked. ^The [sqlite3_db_config()] interface will return a
3121 +** non-zero [error code] if a discontinued or unsupported configuration option
3122 +** is invoked.
3123 +**
3124 +** <dl>
3125 +** [[SQLITE_DBCONFIG_LOOKASIDE]]
3126 +** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
3127 +** <dd> ^This option takes three additional arguments that determine the
3128 +** [lookaside memory allocator] configuration for the [database connection].
3129 +** ^The first argument (the third parameter to [sqlite3_db_config()] is a
3130 +** pointer to a memory buffer to use for lookaside memory.
3131 +** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
3132 +** may be NULL in which case SQLite will allocate the
3133 +** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
3134 +** size of each lookaside buffer slot. ^The third argument is the number of
3135 +** slots. The size of the buffer in the first argument must be greater than
3136 +** or equal to the product of the second and third arguments. The buffer
3137 +** must be aligned to an 8-byte boundary. ^If the second argument to
3138 +** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
3139 +** rounded down to the next smaller multiple of 8. ^(The lookaside memory
3140 +** configuration for a database connection can only be changed when that
3141 +** connection is not currently using lookaside memory, or in other words
3142 +** when the "current value" returned by
3143 +** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
3144 +** Any attempt to change the lookaside memory configuration when lookaside
3145 +** memory is in use leaves the configuration unchanged and returns
3146 +** [SQLITE_BUSY].)^</dd>
3147 +**
3148 +** [[SQLITE_DBCONFIG_ENABLE_FKEY]]
3149 +** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
3150 +** <dd> ^This option is used to enable or disable the enforcement of
3151 +** [foreign key constraints]. There should be two additional arguments.
3152 +** The first argument is an integer which is 0 to disable FK enforcement,
3153 +** positive to enable FK enforcement or negative to leave FK enforcement
3154 +** unchanged. The second parameter is a pointer to an integer into which
3155 +** is written 0 or 1 to indicate whether FK enforcement is off or on
3156 +** following this call. The second parameter may be a NULL pointer, in
3157 +** which case the FK enforcement setting is not reported back. </dd>
3158 +**
3159 +** [[SQLITE_DBCONFIG_ENABLE_TRIGGER]]
3160 +** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
3161 +** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
3162 +** There should be two additional arguments.
3163 +** The first argument is an integer which is 0 to disable triggers,
3164 +** positive to enable triggers or negative to leave the setting unchanged.
3165 +** The second parameter is a pointer to an integer into which
3166 +** is written 0 or 1 to indicate whether triggers are disabled or enabled
3167 +** following this call. The second parameter may be a NULL pointer, in
3168 +** which case the trigger setting is not reported back. </dd>
3169 +**
3170 +** [[SQLITE_DBCONFIG_ENABLE_VIEW]]
3171 +** <dt>SQLITE_DBCONFIG_ENABLE_VIEW</dt>
3172 +** <dd> ^This option is used to enable or disable [CREATE VIEW | views].
3173 +** There should be two additional arguments.
3174 +** The first argument is an integer which is 0 to disable views,
3175 +** positive to enable views or negative to leave the setting unchanged.
3176 +** The second parameter is a pointer to an integer into which
3177 +** is written 0 or 1 to indicate whether views are disabled or enabled
3178 +** following this call. The second parameter may be a NULL pointer, in
3179 +** which case the view setting is not reported back. </dd>
3180 +**
3181 +** [[SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER]]
3182 +** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>
3183 +** <dd> ^This option is used to enable or disable the
3184 +** [fts3_tokenizer()] function which is part of the
3185 +** [FTS3] full-text search engine extension.
3186 +** There should be two additional arguments.
3187 +** The first argument is an integer which is 0 to disable fts3_tokenizer() or
3188 +** positive to enable fts3_tokenizer() or negative to leave the setting
3189 +** unchanged.
3190 +** The second parameter is a pointer to an integer into which
3191 +** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled
3192 +** following this call. The second parameter may be a NULL pointer, in
3193 +** which case the new setting is not reported back. </dd>
3194 +**
3195 +** [[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION]]
3196 +** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt>
3197 +** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]
3198 +** interface independently of the [load_extension()] SQL function.
3199 +** The [sqlite3_enable_load_extension()] API enables or disables both the
3200 +** C-API [sqlite3_load_extension()] and the SQL function [load_extension()].
3201 +** There should be two additional arguments.
3202 +** When the first argument to this interface is 1, then only the C-API is
3203 +** enabled and the SQL function remains disabled. If the first argument to
3204 +** this interface is 0, then both the C-API and the SQL function are disabled.
3205 +** If the first argument is -1, then no changes are made to state of either the
3206 +** C-API or the SQL function.
3207 +** The second parameter is a pointer to an integer into which
3208 +** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface
3209 +** is disabled or enabled following this call. The second parameter may
3210 +** be a NULL pointer, in which case the new setting is not reported back.
3211 +** </dd>
3212 +**
3213 +** [[SQLITE_DBCONFIG_MAINDBNAME]] <dt>SQLITE_DBCONFIG_MAINDBNAME</dt>
3214 +** <dd> ^This option is used to change the name of the "main" database
3215 +** schema. ^The sole argument is a pointer to a constant UTF8 string
3216 +** which will become the new schema name in place of "main". ^SQLite
3217 +** does not make a copy of the new main schema name string, so the application
3218 +** must ensure that the argument passed into this DBCONFIG option is unchanged
3219 +** until after the database connection closes.
3220 +** </dd>
3221 +**
3222 +** [[SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE]]
3223 +** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt>
3224 +** <dd> Usually, when a database in wal mode is closed or detached from a
3225 +** database handle, SQLite checks if this will mean that there are now no
3226 +** connections at all to the database. If so, it performs a checkpoint
3227 +** operation before closing the connection. This option may be used to
3228 +** override this behaviour. The first parameter passed to this operation
3229 +** is an integer - positive to disable checkpoints-on-close, or zero (the
3230 +** default) to enable them, and negative to leave the setting unchanged.
3231 +** The second parameter is a pointer to an integer
3232 +** into which is written 0 or 1 to indicate whether checkpoints-on-close
3233 +** have been disabled - 0 if they are not disabled, 1 if they are.
3234 +** </dd>
3235 +**
3236 +** [[SQLITE_DBCONFIG_ENABLE_QPSG]] <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>
3237 +** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates
3238 +** the [query planner stability guarantee] (QPSG). When the QPSG is active,
3239 +** a single SQL query statement will always use the same algorithm regardless
3240 +** of values of [bound parameters].)^ The QPSG disables some query optimizations
3241 +** that look at the values of bound parameters, which can make some queries
3242 +** slower. But the QPSG has the advantage of more predictable behavior. With
3243 +** the QPSG active, SQLite will always use the same query plan in the field as
3244 +** was used during testing in the lab.
3245 +** The first argument to this setting is an integer which is 0 to disable
3246 +** the QPSG, positive to enable QPSG, or negative to leave the setting
3247 +** unchanged. The second parameter is a pointer to an integer into which
3248 +** is written 0 or 1 to indicate whether the QPSG is disabled or enabled
3249 +** following this call.
3250 +** </dd>
3251 +**
3252 +** [[SQLITE_DBCONFIG_TRIGGER_EQP]] <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt>
3253 +** <dd> By default, the output of EXPLAIN QUERY PLAN commands does not
3254 +** include output for any operations performed by trigger programs. This
3255 +** option is used to set or clear (the default) a flag that governs this
3256 +** behavior. The first parameter passed to this operation is an integer -
3257 +** positive to enable output for trigger programs, or zero to disable it,
3258 +** or negative to leave the setting unchanged.
3259 +** The second parameter is a pointer to an integer into which is written
3260 +** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if
3261 +** it is not disabled, 1 if it is.
3262 +** </dd>
3263 +**
3264 +** [[SQLITE_DBCONFIG_RESET_DATABASE]] <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt>
3265 +** <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run
3266 +** [VACUUM] in order to reset a database back to an empty database
3267 +** with no schema and no content. The following process works even for
3268 +** a badly corrupted database file:
3269 +** <ol>
3270 +** <li> If the database connection is newly opened, make sure it has read the
3271 +** database schema by preparing then discarding some query against the
3272 +** database, or calling sqlite3_table_column_metadata(), ignoring any
3273 +** errors. This step is only necessary if the application desires to keep
3274 +** the database in WAL mode after the reset if it was in WAL mode before
3275 +** the reset.
3276 +** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0);
3277 +** <li> [sqlite3_exec](db, "[VACUUM]", 0, 0, 0);
3278 +** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);
3279 +** </ol>
3280 +** Because resetting a database is destructive and irreversible, the
3281 +** process requires the use of this obscure API and multiple steps to help
3282 +** ensure that it does not happen by accident.
3283 +**
3284 +** [[SQLITE_DBCONFIG_DEFENSIVE]] <dt>SQLITE_DBCONFIG_DEFENSIVE</dt>
3285 +** <dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the
3286 +** "defensive" flag for a database connection. When the defensive
3287 +** flag is enabled, language features that allow ordinary SQL to
3288 +** deliberately corrupt the database file are disabled. The disabled
3289 +** features include but are not limited to the following:
3290 +** <ul>
3291 +** <li> The [PRAGMA writable_schema=ON] statement.
3292 +** <li> The [PRAGMA journal_mode=OFF] statement.
3293 +** <li> Writes to the [sqlite_dbpage] virtual table.
3294 +** <li> Direct writes to [shadow tables].
3295 +** </ul>
3296 +** </dd>
3297 +**
3298 +** [[SQLITE_DBCONFIG_WRITABLE_SCHEMA]] <dt>SQLITE_DBCONFIG_WRITABLE_SCHEMA</dt>
3299 +** <dd>The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the
3300 +** "writable_schema" flag. This has the same effect and is logically equivalent
3301 +** to setting [PRAGMA writable_schema=ON] or [PRAGMA writable_schema=OFF].
3302 +** The first argument to this setting is an integer which is 0 to disable
3303 +** the writable_schema, positive to enable writable_schema, or negative to
3304 +** leave the setting unchanged. The second parameter is a pointer to an
3305 +** integer into which is written 0 or 1 to indicate whether the writable_schema
3306 +** is enabled or disabled following this call.
3307 +** </dd>
3308 +**
3309 +** [[SQLITE_DBCONFIG_LEGACY_ALTER_TABLE]]
3310 +** <dt>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</dt>
3311 +** <dd>The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates
3312 +** the legacy behavior of the [ALTER TABLE RENAME] command such it
3313 +** behaves as it did prior to [version 3.24.0] (2018-06-04). See the
3314 +** "Compatibility Notice" on the [ALTER TABLE RENAME documentation] for
3315 +** additional information. This feature can also be turned on and off
3316 +** using the [PRAGMA legacy_alter_table] statement.
3317 +** </dd>
3318 +**
3319 +** [[SQLITE_DBCONFIG_DQS_DML]]
3320 +** <dt>SQLITE_DBCONFIG_DQS_DML</td>
3321 +** <dd>The SQLITE_DBCONFIG_DQS_DML option activates or deactivates
3322 +** the legacy [double-quoted string literal] misfeature for DML statements
3323 +** only, that is DELETE, INSERT, SELECT, and UPDATE statements. The
3324 +** default value of this setting is determined by the [-DSQLITE_DQS]
3325 +** compile-time option.
3326 +** </dd>
3327 +**
3328 +** [[SQLITE_DBCONFIG_DQS_DDL]]
3329 +** <dt>SQLITE_DBCONFIG_DQS_DDL</td>
3330 +** <dd>The SQLITE_DBCONFIG_DQS option activates or deactivates
3331 +** the legacy [double-quoted string literal] misfeature for DDL statements,
3332 +** such as CREATE TABLE and CREATE INDEX. The
3333 +** default value of this setting is determined by the [-DSQLITE_DQS]
3334 +** compile-time option.
3335 +** </dd>
3336 +**
3337 +** [[SQLITE_DBCONFIG_TRUSTED_SCHEMA]]
3338 +** <dt>SQLITE_DBCONFIG_TRUSTED_SCHEMA</td>
3339 +** <dd>The SQLITE_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to
3340 +** assume that database schemas are untainted by malicious content.
3341 +** When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite
3342 +** takes additional defensive steps to protect the application from harm
3343 +** including:
3344 +** <ul>
3345 +** <li> Prohibit the use of SQL functions inside triggers, views,
3346 +** CHECK constraints, DEFAULT clauses, expression indexes,
3347 +** partial indexes, or generated columns
3348 +** unless those functions are tagged with [SQLITE_INNOCUOUS].
3349 +** <li> Prohibit the use of virtual tables inside of triggers or views
3350 +** unless those virtual tables are tagged with [SQLITE_VTAB_INNOCUOUS].
3351 +** </ul>
3352 +** This setting defaults to "on" for legacy compatibility, however
3353 +** all applications are advised to turn it off if possible. This setting
3354 +** can also be controlled using the [PRAGMA trusted_schema] statement.
3355 +** </dd>
3356 +**
3357 +** [[SQLITE_DBCONFIG_LEGACY_FILE_FORMAT]]
3358 +** <dt>SQLITE_DBCONFIG_LEGACY_FILE_FORMAT</td>
3359 +** <dd>The SQLITE_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates
3360 +** the legacy file format flag. When activated, this flag causes all newly
3361 +** created database file to have a schema format version number (the 4-byte
3362 +** integer found at offset 44 into the database header) of 1. This in turn
3363 +** means that the resulting database file will be readable and writable by
3364 +** any SQLite version back to 3.0.0 ([dateof:3.0.0]). Without this setting,
3365 +** newly created databases are generally not understandable by SQLite versions
3366 +** prior to 3.3.0 ([dateof:3.3.0]). As these words are written, there
3367 +** is now scarcely any need to generated database files that are compatible
3368 +** all the way back to version 3.0.0, and so this setting is of little
3369 +** practical use, but is provided so that SQLite can continue to claim the
3370 +** ability to generate new database files that are compatible with version
3371 +** 3.0.0.
3372 +** <p>Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on,
3373 +** the [VACUUM] command will fail with an obscure error when attempting to
3374 +** process a table with generated columns and a descending index. This is
3375 +** not considered a bug since SQLite versions 3.3.0 and earlier do not support
3376 +** either generated columns or decending indexes.
3377 +** </dd>
3378 +** </dl>
3379 +*/
3380 +#define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */
3381 +#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
3382 +#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */
3383 +#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */
3384 +#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */
3385 +#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
3386 +#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */
3387 +#define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */
3388 +#define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */
3389 +#define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */
3390 +#define SQLITE_DBCONFIG_DEFENSIVE 1010 /* int int* */
3391 +#define SQLITE_DBCONFIG_WRITABLE_SCHEMA 1011 /* int int* */
3392 +#define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 1012 /* int int* */
3393 +#define SQLITE_DBCONFIG_DQS_DML 1013 /* int int* */
3394 +#define SQLITE_DBCONFIG_DQS_DDL 1014 /* int int* */
3395 +#define SQLITE_DBCONFIG_ENABLE_VIEW 1015 /* int int* */
3396 +#define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 1016 /* int int* */
3397 +#define SQLITE_DBCONFIG_TRUSTED_SCHEMA 1017 /* int int* */
3398 +#define SQLITE_DBCONFIG_MAX 1017 /* Largest DBCONFIG */
3399 +
3400 +/*
3401 +** CAPI3REF: Enable Or Disable Extended Result Codes
3402 +** METHOD: sqlite3
3403 +**
3404 +** ^The sqlite3_extended_result_codes() routine enables or disables the
3405 +** [extended result codes] feature of SQLite. ^The extended result
3406 +** codes are disabled by default for historical compatibility.
3407 +*/
3408 +SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
3409 +
3410 +/*
3411 +** CAPI3REF: Last Insert Rowid
3412 +** METHOD: sqlite3
3413 +**
3414 +** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
3415 +** has a unique 64-bit signed
3416 +** integer key called the [ROWID | "rowid"]. ^The rowid is always available
3417 +** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
3418 +** names are not also used by explicitly declared columns. ^If
3419 +** the table has a column of type [INTEGER PRIMARY KEY] then that column
3420 +** is another alias for the rowid.
3421 +**
3422 +** ^The sqlite3_last_insert_rowid(D) interface usually returns the [rowid] of
3423 +** the most recent successful [INSERT] into a rowid table or [virtual table]
3424 +** on database connection D. ^Inserts into [WITHOUT ROWID] tables are not
3425 +** recorded. ^If no successful [INSERT]s into rowid tables have ever occurred
3426 +** on the database connection D, then sqlite3_last_insert_rowid(D) returns
3427 +** zero.
3428 +**
3429 +** As well as being set automatically as rows are inserted into database
3430 +** tables, the value returned by this function may be set explicitly by
3431 +** [sqlite3_set_last_insert_rowid()]
3432 +**
3433 +** Some virtual table implementations may INSERT rows into rowid tables as
3434 +** part of committing a transaction (e.g. to flush data accumulated in memory
3435 +** to disk). In this case subsequent calls to this function return the rowid
3436 +** associated with these internal INSERT operations, which leads to
3437 +** unintuitive results. Virtual table implementations that do write to rowid
3438 +** tables in this way can avoid this problem by restoring the original
3439 +** rowid value using [sqlite3_set_last_insert_rowid()] before returning
3440 +** control to the user.
3441 +**
3442 +** ^(If an [INSERT] occurs within a trigger then this routine will
3443 +** return the [rowid] of the inserted row as long as the trigger is
3444 +** running. Once the trigger program ends, the value returned
3445 +** by this routine reverts to what it was before the trigger was fired.)^
3446 +**
3447 +** ^An [INSERT] that fails due to a constraint violation is not a
3448 +** successful [INSERT] and does not change the value returned by this
3449 +** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
3450 +** and INSERT OR ABORT make no changes to the return value of this
3451 +** routine when their insertion fails. ^(When INSERT OR REPLACE
3452 +** encounters a constraint violation, it does not fail. The
3453 +** INSERT continues to completion after deleting rows that caused
3454 +** the constraint problem so INSERT OR REPLACE will always change
3455 +** the return value of this interface.)^
3456 +**
3457 +** ^For the purposes of this routine, an [INSERT] is considered to
3458 +** be successful even if it is subsequently rolled back.
3459 +**
3460 +** This function is accessible to SQL statements via the
3461 +** [last_insert_rowid() SQL function].
3462 +**
3463 +** If a separate thread performs a new [INSERT] on the same
3464 +** database connection while the [sqlite3_last_insert_rowid()]
3465 +** function is running and thus changes the last insert [rowid],
3466 +** then the value returned by [sqlite3_last_insert_rowid()] is
3467 +** unpredictable and might not equal either the old or the new
3468 +** last insert [rowid].
3469 +*/
3470 +SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
3471 +
3472 +/*
3473 +** CAPI3REF: Set the Last Insert Rowid value.
3474 +** METHOD: sqlite3
3475 +**
3476 +** The sqlite3_set_last_insert_rowid(D, R) method allows the application to
3477 +** set the value returned by calling sqlite3_last_insert_rowid(D) to R
3478 +** without inserting a row into the database.
3479 +*/
3480 +SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
3481 +
3482 +/*
3483 +** CAPI3REF: Count The Number Of Rows Modified
3484 +** METHOD: sqlite3
3485 +**
3486 +** ^This function returns the number of rows modified, inserted or
3487 +** deleted by the most recently completed INSERT, UPDATE or DELETE
3488 +** statement on the database connection specified by the only parameter.
3489 +** ^Executing any other type of SQL statement does not modify the value
3490 +** returned by this function.
3491 +**
3492 +** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are
3493 +** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],
3494 +** [foreign key actions] or [REPLACE] constraint resolution are not counted.
3495 +**
3496 +** Changes to a view that are intercepted by
3497 +** [INSTEAD OF trigger | INSTEAD OF triggers] are not counted. ^The value
3498 +** returned by sqlite3_changes() immediately after an INSERT, UPDATE or
3499 +** DELETE statement run on a view is always zero. Only changes made to real
3500 +** tables are counted.
3501 +**
3502 +** Things are more complicated if the sqlite3_changes() function is
3503 +** executed while a trigger program is running. This may happen if the
3504 +** program uses the [changes() SQL function], or if some other callback
3505 +** function invokes sqlite3_changes() directly. Essentially:
3506 +**
3507 +** <ul>
3508 +** <li> ^(Before entering a trigger program the value returned by
3509 +** sqlite3_changes() function is saved. After the trigger program
3510 +** has finished, the original value is restored.)^
3511 +**
3512 +** <li> ^(Within a trigger program each INSERT, UPDATE and DELETE
3513 +** statement sets the value returned by sqlite3_changes()
3514 +** upon completion as normal. Of course, this value will not include
3515 +** any changes performed by sub-triggers, as the sqlite3_changes()
3516 +** value will be saved and restored after each sub-trigger has run.)^
3517 +** </ul>
3518 +**
3519 +** ^This means that if the changes() SQL function (or similar) is used
3520 +** by the first INSERT, UPDATE or DELETE statement within a trigger, it
3521 +** returns the value as set when the calling statement began executing.
3522 +** ^If it is used by the second or subsequent such statement within a trigger
3523 +** program, the value returned reflects the number of rows modified by the
3524 +** previous INSERT, UPDATE or DELETE statement within the same trigger.
3525 +**
3526 +** If a separate thread makes changes on the same database connection
3527 +** while [sqlite3_changes()] is running then the value returned
3528 +** is unpredictable and not meaningful.
3529 +**
3530 +** See also:
3531 +** <ul>
3532 +** <li> the [sqlite3_total_changes()] interface
3533 +** <li> the [count_changes pragma]
3534 +** <li> the [changes() SQL function]
3535 +** <li> the [data_version pragma]
3536 +** </ul>
3537 +*/
3538 +SQLITE_API int sqlite3_changes(sqlite3*);
3539 +
3540 +/*
3541 +** CAPI3REF: Total Number Of Rows Modified
3542 +** METHOD: sqlite3
3543 +**
3544 +** ^This function returns the total number of rows inserted, modified or
3545 +** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed
3546 +** since the database connection was opened, including those executed as
3547 +** part of trigger programs. ^Executing any other type of SQL statement
3548 +** does not affect the value returned by sqlite3_total_changes().
3549 +**
3550 +** ^Changes made as part of [foreign key actions] are included in the
3551 +** count, but those made as part of REPLACE constraint resolution are
3552 +** not. ^Changes to a view that are intercepted by INSTEAD OF triggers
3553 +** are not counted.
3554 +**
3555 +** The [sqlite3_total_changes(D)] interface only reports the number
3556 +** of rows that changed due to SQL statement run against database
3557 +** connection D. Any changes by other database connections are ignored.
3558 +** To detect changes against a database file from other database
3559 +** connections use the [PRAGMA data_version] command or the
3560 +** [SQLITE_FCNTL_DATA_VERSION] [file control].
3561 +**
3562 +** If a separate thread makes changes on the same database connection
3563 +** while [sqlite3_total_changes()] is running then the value
3564 +** returned is unpredictable and not meaningful.
3565 +**
3566 +** See also:
3567 +** <ul>
3568 +** <li> the [sqlite3_changes()] interface
3569 +** <li> the [count_changes pragma]
3570 +** <li> the [changes() SQL function]
3571 +** <li> the [data_version pragma]
3572 +** <li> the [SQLITE_FCNTL_DATA_VERSION] [file control]
3573 +** </ul>
3574 +*/
3575 +SQLITE_API int sqlite3_total_changes(sqlite3*);
3576 +
3577 +/*
3578 +** CAPI3REF: Interrupt A Long-Running Query
3579 +** METHOD: sqlite3
3580 +**
3581 +** ^This function causes any pending database operation to abort and
3582 +** return at its earliest opportunity. This routine is typically
3583 +** called in response to a user action such as pressing "Cancel"
3584 +** or Ctrl-C where the user wants a long query operation to halt
3585 +** immediately.
3586 +**
3587 +** ^It is safe to call this routine from a thread different from the
3588 +** thread that is currently running the database operation. But it
3589 +** is not safe to call this routine with a [database connection] that
3590 +** is closed or might close before sqlite3_interrupt() returns.
3591 +**
3592 +** ^If an SQL operation is very nearly finished at the time when
3593 +** sqlite3_interrupt() is called, then it might not have an opportunity
3594 +** to be interrupted and might continue to completion.
3595 +**
3596 +** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
3597 +** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
3598 +** that is inside an explicit transaction, then the entire transaction
3599 +** will be rolled back automatically.
3600 +**
3601 +** ^The sqlite3_interrupt(D) call is in effect until all currently running
3602 +** SQL statements on [database connection] D complete. ^Any new SQL statements
3603 +** that are started after the sqlite3_interrupt() call and before the
3604 +** running statement count reaches zero are interrupted as if they had been
3605 +** running prior to the sqlite3_interrupt() call. ^New SQL statements
3606 +** that are started after the running statement count reaches zero are
3607 +** not effected by the sqlite3_interrupt().
3608 +** ^A call to sqlite3_interrupt(D) that occurs when there are no running
3609 +** SQL statements is a no-op and has no effect on SQL statements
3610 +** that are started after the sqlite3_interrupt() call returns.
3611 +*/
3612 +SQLITE_API void sqlite3_interrupt(sqlite3*);
3613 +
3614 +/*
3615 +** CAPI3REF: Determine If An SQL Statement Is Complete
3616 +**
3617 +** These routines are useful during command-line input to determine if the
3618 +** currently entered text seems to form a complete SQL statement or
3619 +** if additional input is needed before sending the text into
3620 +** SQLite for parsing. ^These routines return 1 if the input string
3621 +** appears to be a complete SQL statement. ^A statement is judged to be
3622 +** complete if it ends with a semicolon token and is not a prefix of a
3623 +** well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within
3624 +** string literals or quoted identifier names or comments are not
3625 +** independent tokens (they are part of the token in which they are
3626 +** embedded) and thus do not count as a statement terminator. ^Whitespace
3627 +** and comments that follow the final semicolon are ignored.
3628 +**
3629 +** ^These routines return 0 if the statement is incomplete. ^If a
3630 +** memory allocation fails, then SQLITE_NOMEM is returned.
3631 +**
3632 +** ^These routines do not parse the SQL statements thus
3633 +** will not detect syntactically incorrect SQL.
3634 +**
3635 +** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior
3636 +** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
3637 +** automatically by sqlite3_complete16(). If that initialization fails,
3638 +** then the return value from sqlite3_complete16() will be non-zero
3639 +** regardless of whether or not the input SQL is complete.)^
3640 +**
3641 +** The input to [sqlite3_complete()] must be a zero-terminated
3642 +** UTF-8 string.
3643 +**
3644 +** The input to [sqlite3_complete16()] must be a zero-terminated
3645 +** UTF-16 string in native byte order.
3646 +*/
3647 +SQLITE_API int sqlite3_complete(const char *sql);
3648 +SQLITE_API int sqlite3_complete16(const void *sql);
3649 +
3650 +/*
3651 +** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
3652 +** KEYWORDS: {busy-handler callback} {busy handler}
3653 +** METHOD: sqlite3
3654 +**
3655 +** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
3656 +** that might be invoked with argument P whenever
3657 +** an attempt is made to access a database table associated with
3658 +** [database connection] D when another thread
3659 +** or process has the table locked.
3660 +** The sqlite3_busy_handler() interface is used to implement
3661 +** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
3662 +**
3663 +** ^If the busy callback is NULL, then [SQLITE_BUSY]
3664 +** is returned immediately upon encountering the lock. ^If the busy callback
3665 +** is not NULL, then the callback might be invoked with two arguments.
3666 +**
3667 +** ^The first argument to the busy handler is a copy of the void* pointer which
3668 +** is the third argument to sqlite3_busy_handler(). ^The second argument to
3669 +** the busy handler callback is the number of times that the busy handler has
3670 +** been invoked previously for the same locking event. ^If the
3671 +** busy callback returns 0, then no additional attempts are made to
3672 +** access the database and [SQLITE_BUSY] is returned
3673 +** to the application.
3674 +** ^If the callback returns non-zero, then another attempt
3675 +** is made to access the database and the cycle repeats.
3676 +**
3677 +** The presence of a busy handler does not guarantee that it will be invoked
3678 +** when there is lock contention. ^If SQLite determines that invoking the busy
3679 +** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
3680 +** to the application instead of invoking the
3681 +** busy handler.
3682 +** Consider a scenario where one process is holding a read lock that
3683 +** it is trying to promote to a reserved lock and
3684 +** a second process is holding a reserved lock that it is trying
3685 +** to promote to an exclusive lock. The first process cannot proceed
3686 +** because it is blocked by the second and the second process cannot
3687 +** proceed because it is blocked by the first. If both processes
3688 +** invoke the busy handlers, neither will make any progress. Therefore,
3689 +** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
3690 +** will induce the first process to release its read lock and allow
3691 +** the second process to proceed.
3692 +**
3693 +** ^The default busy callback is NULL.
3694 +**
3695 +** ^(There can only be a single busy handler defined for each
3696 +** [database connection]. Setting a new busy handler clears any
3697 +** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()]
3698 +** or evaluating [PRAGMA busy_timeout=N] will change the
3699 +** busy handler and thus clear any previously set busy handler.
3700 +**
3701 +** The busy callback should not take any actions which modify the
3702 +** database connection that invoked the busy handler. In other words,
3703 +** the busy handler is not reentrant. Any such actions
3704 +** result in undefined behavior.
3705 +**
3706 +** A busy handler must not close the database connection
3707 +** or [prepared statement] that invoked the busy handler.
3708 +*/
3709 +SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);
3710 +
3711 +/*
3712 +** CAPI3REF: Set A Busy Timeout
3713 +** METHOD: sqlite3
3714 +**
3715 +** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
3716 +** for a specified amount of time when a table is locked. ^The handler
3717 +** will sleep multiple times until at least "ms" milliseconds of sleeping
3718 +** have accumulated. ^After at least "ms" milliseconds of sleeping,
3719 +** the handler returns 0 which causes [sqlite3_step()] to return
3720 +** [SQLITE_BUSY].
3721 +**
3722 +** ^Calling this routine with an argument less than or equal to zero
3723 +** turns off all busy handlers.
3724 +**
3725 +** ^(There can only be a single busy handler for a particular
3726 +** [database connection] at any given moment. If another busy handler
3727 +** was defined (using [sqlite3_busy_handler()]) prior to calling
3728 +** this routine, that other busy handler is cleared.)^
3729 +**
3730 +** See also: [PRAGMA busy_timeout]
3731 +*/
3732 +SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
3733 +
3734 +/*
3735 +** CAPI3REF: Convenience Routines For Running Queries
3736 +** METHOD: sqlite3
3737 +**
3738 +** This is a legacy interface that is preserved for backwards compatibility.
3739 +** Use of this interface is not recommended.
3740 +**
3741 +** Definition: A <b>result table</b> is memory data structure created by the
3742 +** [sqlite3_get_table()] interface. A result table records the
3743 +** complete query results from one or more queries.
3744 +**
3745 +** The table conceptually has a number of rows and columns. But
3746 +** these numbers are not part of the result table itself. These
3747 +** numbers are obtained separately. Let N be the number of rows
3748 +** and M be the number of columns.
3749 +**
3750 +** A result table is an array of pointers to zero-terminated UTF-8 strings.
3751 +** There are (N+1)*M elements in the array. The first M pointers point
3752 +** to zero-terminated strings that contain the names of the columns.
3753 +** The remaining entries all point to query results. NULL values result
3754 +** in NULL pointers. All other values are in their UTF-8 zero-terminated
3755 +** string representation as returned by [sqlite3_column_text()].
3756 +**
3757 +** A result table might consist of one or more memory allocations.
3758 +** It is not safe to pass a result table directly to [sqlite3_free()].
3759 +** A result table should be deallocated using [sqlite3_free_table()].
3760 +**
3761 +** ^(As an example of the result table format, suppose a query result
3762 +** is as follows:
3763 +**
3764 +** <blockquote><pre>
3765 +** Name | Age
3766 +** -----------------------
3767 +** Alice | 43
3768 +** Bob | 28
3769 +** Cindy | 21
3770 +** </pre></blockquote>
3771 +**
3772 +** There are two columns (M==2) and three rows (N==3). Thus the
3773 +** result table has 8 entries. Suppose the result table is stored
3774 +** in an array named azResult. Then azResult holds this content:
3775 +**
3776 +** <blockquote><pre>
3777 +** azResult&#91;0] = "Name";
3778 +** azResult&#91;1] = "Age";
3779 +** azResult&#91;2] = "Alice";
3780 +** azResult&#91;3] = "43";
3781 +** azResult&#91;4] = "Bob";
3782 +** azResult&#91;5] = "28";
3783 +** azResult&#91;6] = "Cindy";
3784 +** azResult&#91;7] = "21";
3785 +** </pre></blockquote>)^
3786 +**
3787 +** ^The sqlite3_get_table() function evaluates one or more
3788 +** semicolon-separated SQL statements in the zero-terminated UTF-8
3789 +** string of its 2nd parameter and returns a result table to the
3790 +** pointer given in its 3rd parameter.
3791 +**
3792 +** After the application has finished with the result from sqlite3_get_table(),
3793 +** it must pass the result table pointer to sqlite3_free_table() in order to
3794 +** release the memory that was malloced. Because of the way the
3795 +** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
3796 +** function must not try to call [sqlite3_free()] directly. Only
3797 +** [sqlite3_free_table()] is able to release the memory properly and safely.
3798 +**
3799 +** The sqlite3_get_table() interface is implemented as a wrapper around
3800 +** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access
3801 +** to any internal data structures of SQLite. It uses only the public
3802 +** interface defined here. As a consequence, errors that occur in the
3803 +** wrapper layer outside of the internal [sqlite3_exec()] call are not
3804 +** reflected in subsequent calls to [sqlite3_errcode()] or
3805 +** [sqlite3_errmsg()].
3806 +*/
3807 +SQLITE_API int sqlite3_get_table(
3808 + sqlite3 *db, /* An open database */
3809 + const char *zSql, /* SQL to be evaluated */
3810 + char ***pazResult, /* Results of the query */
3811 + int *pnRow, /* Number of result rows written here */
3812 + int *pnColumn, /* Number of result columns written here */
3813 + char **pzErrmsg /* Error msg written here */
3814 +);
3815 +SQLITE_API void sqlite3_free_table(char **result);
3816 +
3817 +/*
3818 +** CAPI3REF: Formatted String Printing Functions
3819 +**
3820 +** These routines are work-alikes of the "printf()" family of functions
3821 +** from the standard C library.
3822 +** These routines understand most of the common formatting options from
3823 +** the standard library printf()
3824 +** plus some additional non-standard formats ([%q], [%Q], [%w], and [%z]).
3825 +** See the [built-in printf()] documentation for details.
3826 +**
3827 +** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
3828 +** results into memory obtained from [sqlite3_malloc64()].
3829 +** The strings returned by these two routines should be
3830 +** released by [sqlite3_free()]. ^Both routines return a
3831 +** NULL pointer if [sqlite3_malloc64()] is unable to allocate enough
3832 +** memory to hold the resulting string.
3833 +**
3834 +** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
3835 +** the standard C library. The result is written into the
3836 +** buffer supplied as the second parameter whose size is given by
3837 +** the first parameter. Note that the order of the
3838 +** first two parameters is reversed from snprintf().)^ This is an
3839 +** historical accident that cannot be fixed without breaking
3840 +** backwards compatibility. ^(Note also that sqlite3_snprintf()
3841 +** returns a pointer to its buffer instead of the number of
3842 +** characters actually written into the buffer.)^ We admit that
3843 +** the number of characters written would be a more useful return
3844 +** value but we cannot change the implementation of sqlite3_snprintf()
3845 +** now without breaking compatibility.
3846 +**
3847 +** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
3848 +** guarantees that the buffer is always zero-terminated. ^The first
3849 +** parameter "n" is the total size of the buffer, including space for
3850 +** the zero terminator. So the longest string that can be completely
3851 +** written will be n-1 characters.
3852 +**
3853 +** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
3854 +**
3855 +** See also: [built-in printf()], [printf() SQL function]
3856 +*/
3857 +SQLITE_API char *sqlite3_mprintf(const char*,...);
3858 +SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
3859 +SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
3860 +SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
3861 +
3862 +/*
3863 +** CAPI3REF: Memory Allocation Subsystem
3864 +**
3865 +** The SQLite core uses these three routines for all of its own
3866 +** internal memory allocation needs. "Core" in the previous sentence
3867 +** does not include operating-system specific [VFS] implementation. The
3868 +** Windows VFS uses native malloc() and free() for some operations.
3869 +**
3870 +** ^The sqlite3_malloc() routine returns a pointer to a block
3871 +** of memory at least N bytes in length, where N is the parameter.
3872 +** ^If sqlite3_malloc() is unable to obtain sufficient free
3873 +** memory, it returns a NULL pointer. ^If the parameter N to
3874 +** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
3875 +** a NULL pointer.
3876 +**
3877 +** ^The sqlite3_malloc64(N) routine works just like
3878 +** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
3879 +** of a signed 32-bit integer.
3880 +**
3881 +** ^Calling sqlite3_free() with a pointer previously returned
3882 +** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
3883 +** that it might be reused. ^The sqlite3_free() routine is
3884 +** a no-op if is called with a NULL pointer. Passing a NULL pointer
3885 +** to sqlite3_free() is harmless. After being freed, memory
3886 +** should neither be read nor written. Even reading previously freed
3887 +** memory might result in a segmentation fault or other severe error.
3888 +** Memory corruption, a segmentation fault, or other severe error
3889 +** might result if sqlite3_free() is called with a non-NULL pointer that
3890 +** was not obtained from sqlite3_malloc() or sqlite3_realloc().
3891 +**
3892 +** ^The sqlite3_realloc(X,N) interface attempts to resize a
3893 +** prior memory allocation X to be at least N bytes.
3894 +** ^If the X parameter to sqlite3_realloc(X,N)
3895 +** is a NULL pointer then its behavior is identical to calling
3896 +** sqlite3_malloc(N).
3897 +** ^If the N parameter to sqlite3_realloc(X,N) is zero or
3898 +** negative then the behavior is exactly the same as calling
3899 +** sqlite3_free(X).
3900 +** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation
3901 +** of at least N bytes in size or NULL if insufficient memory is available.
3902 +** ^If M is the size of the prior allocation, then min(N,M) bytes
3903 +** of the prior allocation are copied into the beginning of buffer returned
3904 +** by sqlite3_realloc(X,N) and the prior allocation is freed.
3905 +** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
3906 +** prior allocation is not freed.
3907 +**
3908 +** ^The sqlite3_realloc64(X,N) interfaces works the same as
3909 +** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
3910 +** of a 32-bit signed integer.
3911 +**
3912 +** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
3913 +** sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
3914 +** sqlite3_msize(X) returns the size of that memory allocation in bytes.
3915 +** ^The value returned by sqlite3_msize(X) might be larger than the number
3916 +** of bytes requested when X was allocated. ^If X is a NULL pointer then
3917 +** sqlite3_msize(X) returns zero. If X points to something that is not
3918 +** the beginning of memory allocation, or if it points to a formerly
3919 +** valid memory allocation that has now been freed, then the behavior
3920 +** of sqlite3_msize(X) is undefined and possibly harmful.
3921 +**
3922 +** ^The memory returned by sqlite3_malloc(), sqlite3_realloc(),
3923 +** sqlite3_malloc64(), and sqlite3_realloc64()
3924 +** is always aligned to at least an 8 byte boundary, or to a
3925 +** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
3926 +** option is used.
3927 +**
3928 +** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
3929 +** must be either NULL or else pointers obtained from a prior
3930 +** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
3931 +** not yet been released.
3932 +**
3933 +** The application must not read or write any part of
3934 +** a block of memory after it has been released using
3935 +** [sqlite3_free()] or [sqlite3_realloc()].
3936 +*/
3937 +SQLITE_API void *sqlite3_malloc(int);
3938 +SQLITE_API void *sqlite3_malloc64(sqlite3_uint64);
3939 +SQLITE_API void *sqlite3_realloc(void*, int);
3940 +SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64);
3941 +SQLITE_API void sqlite3_free(void*);
3942 +SQLITE_API sqlite3_uint64 sqlite3_msize(void*);
3943 +
3944 +/*
3945 +** CAPI3REF: Memory Allocator Statistics
3946 +**
3947 +** SQLite provides these two interfaces for reporting on the status
3948 +** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
3949 +** routines, which form the built-in memory allocation subsystem.
3950 +**
3951 +** ^The [sqlite3_memory_used()] routine returns the number of bytes
3952 +** of memory currently outstanding (malloced but not freed).
3953 +** ^The [sqlite3_memory_highwater()] routine returns the maximum
3954 +** value of [sqlite3_memory_used()] since the high-water mark
3955 +** was last reset. ^The values returned by [sqlite3_memory_used()] and
3956 +** [sqlite3_memory_highwater()] include any overhead
3957 +** added by SQLite in its implementation of [sqlite3_malloc()],
3958 +** but not overhead added by the any underlying system library
3959 +** routines that [sqlite3_malloc()] may call.
3960 +**
3961 +** ^The memory high-water mark is reset to the current value of
3962 +** [sqlite3_memory_used()] if and only if the parameter to
3963 +** [sqlite3_memory_highwater()] is true. ^The value returned
3964 +** by [sqlite3_memory_highwater(1)] is the high-water mark
3965 +** prior to the reset.
3966 +*/
3967 +SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
3968 +SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
3969 +
3970 +/*
3971 +** CAPI3REF: Pseudo-Random Number Generator
3972 +**
3973 +** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
3974 +** select random [ROWID | ROWIDs] when inserting new records into a table that
3975 +** already uses the largest possible [ROWID]. The PRNG is also used for
3976 +** the built-in random() and randomblob() SQL functions. This interface allows
3977 +** applications to access the same PRNG for other purposes.
3978 +**
3979 +** ^A call to this routine stores N bytes of randomness into buffer P.
3980 +** ^The P parameter can be a NULL pointer.
3981 +**
3982 +** ^If this routine has not been previously called or if the previous
3983 +** call had N less than one or a NULL pointer for P, then the PRNG is
3984 +** seeded using randomness obtained from the xRandomness method of
3985 +** the default [sqlite3_vfs] object.
3986 +** ^If the previous call to this routine had an N of 1 or more and a
3987 +** non-NULL P then the pseudo-randomness is generated
3988 +** internally and without recourse to the [sqlite3_vfs] xRandomness
3989 +** method.
3990 +*/
3991 +SQLITE_API void sqlite3_randomness(int N, void *P);
3992 +
3993 +/*
3994 +** CAPI3REF: Compile-Time Authorization Callbacks
3995 +** METHOD: sqlite3
3996 +** KEYWORDS: {authorizer callback}
3997 +**
3998 +** ^This routine registers an authorizer callback with a particular
3999 +** [database connection], supplied in the first argument.
4000 +** ^The authorizer callback is invoked as SQL statements are being compiled
4001 +** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
4002 +** [sqlite3_prepare_v3()], [sqlite3_prepare16()], [sqlite3_prepare16_v2()],
4003 +** and [sqlite3_prepare16_v3()]. ^At various
4004 +** points during the compilation process, as logic is being created
4005 +** to perform various actions, the authorizer callback is invoked to
4006 +** see if those actions are allowed. ^The authorizer callback should
4007 +** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
4008 +** specific action but allow the SQL statement to continue to be
4009 +** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
4010 +** rejected with an error. ^If the authorizer callback returns
4011 +** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
4012 +** then the [sqlite3_prepare_v2()] or equivalent call that triggered
4013 +** the authorizer will fail with an error message.
4014 +**
4015 +** When the callback returns [SQLITE_OK], that means the operation
4016 +** requested is ok. ^When the callback returns [SQLITE_DENY], the
4017 +** [sqlite3_prepare_v2()] or equivalent call that triggered the
4018 +** authorizer will fail with an error message explaining that
4019 +** access is denied.
4020 +**
4021 +** ^The first parameter to the authorizer callback is a copy of the third
4022 +** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
4023 +** to the callback is an integer [SQLITE_COPY | action code] that specifies
4024 +** the particular action to be authorized. ^The third through sixth parameters
4025 +** to the callback are either NULL pointers or zero-terminated strings
4026 +** that contain additional details about the action to be authorized.
4027 +** Applications must always be prepared to encounter a NULL pointer in any
4028 +** of the third through the sixth parameters of the authorization callback.
4029 +**
4030 +** ^If the action code is [SQLITE_READ]
4031 +** and the callback returns [SQLITE_IGNORE] then the
4032 +** [prepared statement] statement is constructed to substitute
4033 +** a NULL value in place of the table column that would have
4034 +** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
4035 +** return can be used to deny an untrusted user access to individual
4036 +** columns of a table.
4037 +** ^When a table is referenced by a [SELECT] but no column values are
4038 +** extracted from that table (for example in a query like
4039 +** "SELECT count(*) FROM tab") then the [SQLITE_READ] authorizer callback
4040 +** is invoked once for that table with a column name that is an empty string.
4041 +** ^If the action code is [SQLITE_DELETE] and the callback returns
4042 +** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
4043 +** [truncate optimization] is disabled and all rows are deleted individually.
4044 +**
4045 +** An authorizer is used when [sqlite3_prepare | preparing]
4046 +** SQL statements from an untrusted source, to ensure that the SQL statements
4047 +** do not try to access data they are not allowed to see, or that they do not
4048 +** try to execute malicious statements that damage the database. For
4049 +** example, an application may allow a user to enter arbitrary
4050 +** SQL queries for evaluation by a database. But the application does
4051 +** not want the user to be able to make arbitrary changes to the
4052 +** database. An authorizer could then be put in place while the
4053 +** user-entered SQL is being [sqlite3_prepare | prepared] that
4054 +** disallows everything except [SELECT] statements.
4055 +**
4056 +** Applications that need to process SQL from untrusted sources
4057 +** might also consider lowering resource limits using [sqlite3_limit()]
4058 +** and limiting database size using the [max_page_count] [PRAGMA]
4059 +** in addition to using an authorizer.
4060 +**
4061 +** ^(Only a single authorizer can be in place on a database connection
4062 +** at a time. Each call to sqlite3_set_authorizer overrides the
4063 +** previous call.)^ ^Disable the authorizer by installing a NULL callback.
4064 +** The authorizer is disabled by default.
4065 +**
4066 +** The authorizer callback must not do anything that will modify
4067 +** the database connection that invoked the authorizer callback.
4068 +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
4069 +** database connections for the meaning of "modify" in this paragraph.
4070 +**
4071 +** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
4072 +** statement might be re-prepared during [sqlite3_step()] due to a
4073 +** schema change. Hence, the application should ensure that the
4074 +** correct authorizer callback remains in place during the [sqlite3_step()].
4075 +**
4076 +** ^Note that the authorizer callback is invoked only during
4077 +** [sqlite3_prepare()] or its variants. Authorization is not
4078 +** performed during statement evaluation in [sqlite3_step()], unless
4079 +** as stated in the previous paragraph, sqlite3_step() invokes
4080 +** sqlite3_prepare_v2() to reprepare a statement after a schema change.
4081 +*/
4082 +SQLITE_API int sqlite3_set_authorizer(
4083 + sqlite3*,
4084 + int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
4085 + void *pUserData
4086 +);
4087 +
4088 +/*
4089 +** CAPI3REF: Authorizer Return Codes
4090 +**
4091 +** The [sqlite3_set_authorizer | authorizer callback function] must
4092 +** return either [SQLITE_OK] or one of these two constants in order
4093 +** to signal SQLite whether or not the action is permitted. See the
4094 +** [sqlite3_set_authorizer | authorizer documentation] for additional
4095 +** information.
4096 +**
4097 +** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
4098 +** returned from the [sqlite3_vtab_on_conflict()] interface.
4099 +*/
4100 +#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
4101 +#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
4102 +
4103 +/*
4104 +** CAPI3REF: Authorizer Action Codes
4105 +**
4106 +** The [sqlite3_set_authorizer()] interface registers a callback function
4107 +** that is invoked to authorize certain SQL statement actions. The
4108 +** second parameter to the callback is an integer code that specifies
4109 +** what action is being authorized. These are the integer action codes that
4110 +** the authorizer callback may be passed.
4111 +**
4112 +** These action code values signify what kind of operation is to be
4113 +** authorized. The 3rd and 4th parameters to the authorization
4114 +** callback function will be parameters or NULL depending on which of these
4115 +** codes is used as the second parameter. ^(The 5th parameter to the
4116 +** authorizer callback is the name of the database ("main", "temp",
4117 +** etc.) if applicable.)^ ^The 6th parameter to the authorizer callback
4118 +** is the name of the inner-most trigger or view that is responsible for
4119 +** the access attempt or NULL if this access attempt is directly from
4120 +** top-level SQL code.
4121 +*/
4122 +/******************************************* 3rd ************ 4th ***********/
4123 +#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
4124 +#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
4125 +#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
4126 +#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
4127 +#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
4128 +#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
4129 +#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
4130 +#define SQLITE_CREATE_VIEW 8 /* View Name NULL */
4131 +#define SQLITE_DELETE 9 /* Table Name NULL */
4132 +#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
4133 +#define SQLITE_DROP_TABLE 11 /* Table Name NULL */
4134 +#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
4135 +#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
4136 +#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
4137 +#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
4138 +#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
4139 +#define SQLITE_DROP_VIEW 17 /* View Name NULL */
4140 +#define SQLITE_INSERT 18 /* Table Name NULL */
4141 +#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
4142 +#define SQLITE_READ 20 /* Table Name Column Name */
4143 +#define SQLITE_SELECT 21 /* NULL NULL */
4144 +#define SQLITE_TRANSACTION 22 /* Operation NULL */
4145 +#define SQLITE_UPDATE 23 /* Table Name Column Name */
4146 +#define SQLITE_ATTACH 24 /* Filename NULL */
4147 +#define SQLITE_DETACH 25 /* Database Name NULL */
4148 +#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
4149 +#define SQLITE_REINDEX 27 /* Index Name NULL */
4150 +#define SQLITE_ANALYZE 28 /* Table Name NULL */
4151 +#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
4152 +#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
4153 +#define SQLITE_FUNCTION 31 /* NULL Function Name */
4154 +#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */
4155 +#define SQLITE_COPY 0 /* No longer used */
4156 +#define SQLITE_RECURSIVE 33 /* NULL NULL */
4157 +
4158 +/*
4159 +** CAPI3REF: Tracing And Profiling Functions
4160 +** METHOD: sqlite3
4161 +**
4162 +** These routines are deprecated. Use the [sqlite3_trace_v2()] interface
4163 +** instead of the routines described here.
4164 +**
4165 +** These routines register callback functions that can be used for
4166 +** tracing and profiling the execution of SQL statements.
4167 +**
4168 +** ^The callback function registered by sqlite3_trace() is invoked at
4169 +** various times when an SQL statement is being run by [sqlite3_step()].
4170 +** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
4171 +** SQL statement text as the statement first begins executing.
4172 +** ^(Additional sqlite3_trace() callbacks might occur
4173 +** as each triggered subprogram is entered. The callbacks for triggers
4174 +** contain a UTF-8 SQL comment that identifies the trigger.)^
4175 +**
4176 +** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
4177 +** the length of [bound parameter] expansion in the output of sqlite3_trace().
4178 +**
4179 +** ^The callback function registered by sqlite3_profile() is invoked
4180 +** as each SQL statement finishes. ^The profile callback contains
4181 +** the original statement text and an estimate of wall-clock time
4182 +** of how long that statement took to run. ^The profile callback
4183 +** time is in units of nanoseconds, however the current implementation
4184 +** is only capable of millisecond resolution so the six least significant
4185 +** digits in the time are meaningless. Future versions of SQLite
4186 +** might provide greater resolution on the profiler callback. Invoking
4187 +** either [sqlite3_trace()] or [sqlite3_trace_v2()] will cancel the
4188 +** profile callback.
4189 +*/
4190 +SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*,
4191 + void(*xTrace)(void*,const char*), void*);
4192 +SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
4193 + void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
4194 +
4195 +/*
4196 +** CAPI3REF: SQL Trace Event Codes
4197 +** KEYWORDS: SQLITE_TRACE
4198 +**
4199 +** These constants identify classes of events that can be monitored
4200 +** using the [sqlite3_trace_v2()] tracing logic. The M argument
4201 +** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of
4202 +** the following constants. ^The first argument to the trace callback
4203 +** is one of the following constants.
4204 +**
4205 +** New tracing constants may be added in future releases.
4206 +**
4207 +** ^A trace callback has four arguments: xCallback(T,C,P,X).
4208 +** ^The T argument is one of the integer type codes above.
4209 +** ^The C argument is a copy of the context pointer passed in as the
4210 +** fourth argument to [sqlite3_trace_v2()].
4211 +** The P and X arguments are pointers whose meanings depend on T.
4212 +**
4213 +** <dl>
4214 +** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt>
4215 +** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
4216 +** first begins running and possibly at other times during the
4217 +** execution of the prepared statement, such as at the start of each
4218 +** trigger subprogram. ^The P argument is a pointer to the
4219 +** [prepared statement]. ^The X argument is a pointer to a string which
4220 +** is the unexpanded SQL text of the prepared statement or an SQL comment
4221 +** that indicates the invocation of a trigger. ^The callback can compute
4222 +** the same text that would have been returned by the legacy [sqlite3_trace()]
4223 +** interface by using the X argument when X begins with "--" and invoking
4224 +** [sqlite3_expanded_sql(P)] otherwise.
4225 +**
4226 +** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>
4227 +** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same
4228 +** information as is provided by the [sqlite3_profile()] callback.
4229 +** ^The P argument is a pointer to the [prepared statement] and the
4230 +** X argument points to a 64-bit integer which is the estimated of
4231 +** the number of nanosecond that the prepared statement took to run.
4232 +** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
4233 +**
4234 +** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
4235 +** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
4236 +** statement generates a single row of result.
4237 +** ^The P argument is a pointer to the [prepared statement] and the
4238 +** X argument is unused.
4239 +**
4240 +** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt>
4241 +** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
4242 +** connection closes.
4243 +** ^The P argument is a pointer to the [database connection] object
4244 +** and the X argument is unused.
4245 +** </dl>
4246 +*/
4247 +#define SQLITE_TRACE_STMT 0x01
4248 +#define SQLITE_TRACE_PROFILE 0x02
4249 +#define SQLITE_TRACE_ROW 0x04
4250 +#define SQLITE_TRACE_CLOSE 0x08
4251 +
4252 +/*
4253 +** CAPI3REF: SQL Trace Hook
4254 +** METHOD: sqlite3
4255 +**
4256 +** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
4257 +** function X against [database connection] D, using property mask M
4258 +** and context pointer P. ^If the X callback is
4259 +** NULL or if the M mask is zero, then tracing is disabled. The
4260 +** M argument should be the bitwise OR-ed combination of
4261 +** zero or more [SQLITE_TRACE] constants.
4262 +**
4263 +** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides
4264 +** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
4265 +**
4266 +** ^The X callback is invoked whenever any of the events identified by
4267 +** mask M occur. ^The integer return value from the callback is currently
4268 +** ignored, though this may change in future releases. Callback
4269 +** implementations should return zero to ensure future compatibility.
4270 +**
4271 +** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
4272 +** ^The T argument is one of the [SQLITE_TRACE]
4273 +** constants to indicate why the callback was invoked.
4274 +** ^The C argument is a copy of the context pointer.
4275 +** The P and X arguments are pointers whose meanings depend on T.
4276 +**
4277 +** The sqlite3_trace_v2() interface is intended to replace the legacy
4278 +** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which
4279 +** are deprecated.
4280 +*/
4281 +SQLITE_API int sqlite3_trace_v2(
4282 + sqlite3*,
4283 + unsigned uMask,
4284 + int(*xCallback)(unsigned,void*,void*,void*),
4285 + void *pCtx
4286 +);
4287 +
4288 +/*
4289 +** CAPI3REF: Query Progress Callbacks
4290 +** METHOD: sqlite3
4291 +**
4292 +** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
4293 +** function X to be invoked periodically during long running calls to
4294 +** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
4295 +** database connection D. An example use for this
4296 +** interface is to keep a GUI updated during a large query.
4297 +**
4298 +** ^The parameter P is passed through as the only parameter to the
4299 +** callback function X. ^The parameter N is the approximate number of
4300 +** [virtual machine instructions] that are evaluated between successive
4301 +** invocations of the callback X. ^If N is less than one then the progress
4302 +** handler is disabled.
4303 +**
4304 +** ^Only a single progress handler may be defined at one time per
4305 +** [database connection]; setting a new progress handler cancels the
4306 +** old one. ^Setting parameter X to NULL disables the progress handler.
4307 +** ^The progress handler is also disabled by setting N to a value less
4308 +** than 1.
4309 +**
4310 +** ^If the progress callback returns non-zero, the operation is
4311 +** interrupted. This feature can be used to implement a
4312 +** "Cancel" button on a GUI progress dialog box.
4313 +**
4314 +** The progress handler callback must not do anything that will modify
4315 +** the database connection that invoked the progress handler.
4316 +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
4317 +** database connections for the meaning of "modify" in this paragraph.
4318 +**
4319 +*/
4320 +SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
4321 +
4322 +/*
4323 +** CAPI3REF: Opening A New Database Connection
4324 +** CONSTRUCTOR: sqlite3
4325 +**
4326 +** ^These routines open an SQLite database file as specified by the
4327 +** filename argument. ^The filename argument is interpreted as UTF-8 for
4328 +** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
4329 +** order for sqlite3_open16(). ^(A [database connection] handle is usually
4330 +** returned in *ppDb, even if an error occurs. The only exception is that
4331 +** if SQLite is unable to allocate memory to hold the [sqlite3] object,
4332 +** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
4333 +** object.)^ ^(If the database is opened (and/or created) successfully, then
4334 +** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The
4335 +** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
4336 +** an English language description of the error following a failure of any
4337 +** of the sqlite3_open() routines.
4338 +**
4339 +** ^The default encoding will be UTF-8 for databases created using
4340 +** sqlite3_open() or sqlite3_open_v2(). ^The default encoding for databases
4341 +** created using sqlite3_open16() will be UTF-16 in the native byte order.
4342 +**
4343 +** Whether or not an error occurs when it is opened, resources
4344 +** associated with the [database connection] handle should be released by
4345 +** passing it to [sqlite3_close()] when it is no longer required.
4346 +**
4347 +** The sqlite3_open_v2() interface works like sqlite3_open()
4348 +** except that it accepts two additional parameters for additional control
4349 +** over the new database connection. ^(The flags parameter to
4350 +** sqlite3_open_v2() must include, at a minimum, one of the following
4351 +** three flag combinations:)^
4352 +**
4353 +** <dl>
4354 +** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
4355 +** <dd>The database is opened in read-only mode. If the database does not
4356 +** already exist, an error is returned.</dd>)^
4357 +**
4358 +** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
4359 +** <dd>The database is opened for reading and writing if possible, or reading
4360 +** only if the file is write protected by the operating system. In either
4361 +** case the database must already exist, otherwise an error is returned.</dd>)^
4362 +**
4363 +** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
4364 +** <dd>The database is opened for reading and writing, and is created if
4365 +** it does not already exist. This is the behavior that is always used for
4366 +** sqlite3_open() and sqlite3_open16().</dd>)^
4367 +** </dl>
4368 +**
4369 +** In addition to the required flags, the following optional flags are
4370 +** also supported:
4371 +**
4372 +** <dl>
4373 +** ^(<dt>[SQLITE_OPEN_URI]</dt>
4374 +** <dd>The filename can be interpreted as a URI if this flag is set.</dd>)^
4375 +**
4376 +** ^(<dt>[SQLITE_OPEN_MEMORY]</dt>
4377 +** <dd>The database will be opened as an in-memory database. The database
4378 +** is named by the "filename" argument for the purposes of cache-sharing,
4379 +** if shared cache mode is enabled, but the "filename" is otherwise ignored.
4380 +** </dd>)^
4381 +**
4382 +** ^(<dt>[SQLITE_OPEN_NOMUTEX]</dt>
4383 +** <dd>The new database connection will use the "multi-thread"
4384 +** [threading mode].)^ This means that separate threads are allowed
4385 +** to use SQLite at the same time, as long as each thread is using
4386 +** a different [database connection].
4387 +**
4388 +** ^(<dt>[SQLITE_OPEN_FULLMUTEX]</dt>
4389 +** <dd>The new database connection will use the "serialized"
4390 +** [threading mode].)^ This means the multiple threads can safely
4391 +** attempt to use the same database connection at the same time.
4392 +** (Mutexes will block any actual concurrency, but in this mode
4393 +** there is no harm in trying.)
4394 +**
4395 +** ^(<dt>[SQLITE_OPEN_SHAREDCACHE]</dt>
4396 +** <dd>The database is opened [shared cache] enabled, overriding
4397 +** the default shared cache setting provided by
4398 +** [sqlite3_enable_shared_cache()].)^
4399 +**
4400 +** ^(<dt>[SQLITE_OPEN_PRIVATECACHE]</dt>
4401 +** <dd>The database is opened [shared cache] disabled, overriding
4402 +** the default shared cache setting provided by
4403 +** [sqlite3_enable_shared_cache()].)^
4404 +**
4405 +** [[OPEN_NOFOLLOW]] ^(<dt>[SQLITE_OPEN_NOFOLLOW]</dt>
4406 +** <dd>The database filename is not allowed to be a symbolic link</dd>
4407 +** </dl>)^
4408 +**
4409 +** If the 3rd parameter to sqlite3_open_v2() is not one of the
4410 +** required combinations shown above optionally combined with other
4411 +** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
4412 +** then the behavior is undefined.
4413 +**
4414 +** ^The fourth parameter to sqlite3_open_v2() is the name of the
4415 +** [sqlite3_vfs] object that defines the operating system interface that
4416 +** the new database connection should use. ^If the fourth parameter is
4417 +** a NULL pointer then the default [sqlite3_vfs] object is used.
4418 +**
4419 +** ^If the filename is ":memory:", then a private, temporary in-memory database
4420 +** is created for the connection. ^This in-memory database will vanish when
4421 +** the database connection is closed. Future versions of SQLite might
4422 +** make use of additional special filenames that begin with the ":" character.
4423 +** It is recommended that when a database filename actually does begin with
4424 +** a ":" character you should prefix the filename with a pathname such as
4425 +** "./" to avoid ambiguity.
4426 +**
4427 +** ^If the filename is an empty string, then a private, temporary
4428 +** on-disk database will be created. ^This private database will be
4429 +** automatically deleted as soon as the database connection is closed.
4430 +**
4431 +** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
4432 +**
4433 +** ^If [URI filename] interpretation is enabled, and the filename argument
4434 +** begins with "file:", then the filename is interpreted as a URI. ^URI
4435 +** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
4436 +** set in the third argument to sqlite3_open_v2(), or if it has
4437 +** been enabled globally using the [SQLITE_CONFIG_URI] option with the
4438 +** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
4439 +** URI filename interpretation is turned off
4440 +** by default, but future releases of SQLite might enable URI filename
4441 +** interpretation by default. See "[URI filenames]" for additional
4442 +** information.
4443 +**
4444 +** URI filenames are parsed according to RFC 3986. ^If the URI contains an
4445 +** authority, then it must be either an empty string or the string
4446 +** "localhost". ^If the authority is not an empty string or "localhost", an
4447 +** error is returned to the caller. ^The fragment component of a URI, if
4448 +** present, is ignored.
4449 +**
4450 +** ^SQLite uses the path component of the URI as the name of the disk file
4451 +** which contains the database. ^If the path begins with a '/' character,
4452 +** then it is interpreted as an absolute path. ^If the path does not begin
4453 +** with a '/' (meaning that the authority section is omitted from the URI)
4454 +** then the path is interpreted as a relative path.
4455 +** ^(On windows, the first component of an absolute path
4456 +** is a drive specification (e.g. "C:").)^
4457 +**
4458 +** [[core URI query parameters]]
4459 +** The query component of a URI may contain parameters that are interpreted
4460 +** either by SQLite itself, or by a [VFS | custom VFS implementation].
4461 +** SQLite and its built-in [VFSes] interpret the
4462 +** following query parameters:
4463 +**
4464 +** <ul>
4465 +** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
4466 +** a VFS object that provides the operating system interface that should
4467 +** be used to access the database file on disk. ^If this option is set to
4468 +** an empty string the default VFS object is used. ^Specifying an unknown
4469 +** VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
4470 +** present, then the VFS specified by the option takes precedence over
4471 +** the value passed as the fourth parameter to sqlite3_open_v2().
4472 +**
4473 +** <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",
4474 +** "rwc", or "memory". Attempting to set it to any other value is
4475 +** an error)^.
4476 +** ^If "ro" is specified, then the database is opened for read-only
4477 +** access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the
4478 +** third argument to sqlite3_open_v2(). ^If the mode option is set to
4479 +** "rw", then the database is opened for read-write (but not create)
4480 +** access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had
4481 +** been set. ^Value "rwc" is equivalent to setting both
4482 +** SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If the mode option is
4483 +** set to "memory" then a pure [in-memory database] that never reads
4484 +** or writes from disk is used. ^It is an error to specify a value for
4485 +** the mode parameter that is less restrictive than that specified by
4486 +** the flags passed in the third parameter to sqlite3_open_v2().
4487 +**
4488 +** <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
4489 +** "private". ^Setting it to "shared" is equivalent to setting the
4490 +** SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
4491 +** sqlite3_open_v2(). ^Setting the cache parameter to "private" is
4492 +** equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
4493 +** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
4494 +** a URI filename, its value overrides any behavior requested by setting
4495 +** SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
4496 +**
4497 +** <li> <b>psow</b>: ^The psow parameter indicates whether or not the
4498 +** [powersafe overwrite] property does or does not apply to the
4499 +** storage media on which the database file resides.
4500 +**
4501 +** <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
4502 +** which if set disables file locking in rollback journal modes. This
4503 +** is useful for accessing a database on a filesystem that does not
4504 +** support locking. Caution: Database corruption might result if two
4505 +** or more processes write to the same database and any one of those
4506 +** processes uses nolock=1.
4507 +**
4508 +** <li> <b>immutable</b>: ^The immutable parameter is a boolean query
4509 +** parameter that indicates that the database file is stored on
4510 +** read-only media. ^When immutable is set, SQLite assumes that the
4511 +** database file cannot be changed, even by a process with higher
4512 +** privilege, and so the database is opened read-only and all locking
4513 +** and change detection is disabled. Caution: Setting the immutable
4514 +** property on a database file that does in fact change can result
4515 +** in incorrect query results and/or [SQLITE_CORRUPT] errors.
4516 +** See also: [SQLITE_IOCAP_IMMUTABLE].
4517 +**
4518 +** </ul>
4519 +**
4520 +** ^Specifying an unknown parameter in the query component of a URI is not an
4521 +** error. Future versions of SQLite might understand additional query
4522 +** parameters. See "[query parameters with special meaning to SQLite]" for
4523 +** additional information.
4524 +**
4525 +** [[URI filename examples]] <h3>URI filename examples</h3>
4526 +**
4527 +** <table border="1" align=center cellpadding=5>
4528 +** <tr><th> URI filenames <th> Results
4529 +** <tr><td> file:data.db <td>
4530 +** Open the file "data.db" in the current directory.
4531 +** <tr><td> file:/home/fred/data.db<br>
4532 +** file:///home/fred/data.db <br>
4533 +** file://localhost/home/fred/data.db <br> <td>
4534 +** Open the database file "/home/fred/data.db".
4535 +** <tr><td> file://darkstar/home/fred/data.db <td>
4536 +** An error. "darkstar" is not a recognized authority.
4537 +** <tr><td style="white-space:nowrap">
4538 +** file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
4539 +** <td> Windows only: Open the file "data.db" on fred's desktop on drive
4540 +** C:. Note that the %20 escaping in this example is not strictly
4541 +** necessary - space characters can be used literally
4542 +** in URI filenames.
4543 +** <tr><td> file:data.db?mode=ro&cache=private <td>
4544 +** Open file "data.db" in the current directory for read-only access.
4545 +** Regardless of whether or not shared-cache mode is enabled by
4546 +** default, use a private cache.
4547 +** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
4548 +** Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
4549 +** that uses dot-files in place of posix advisory locking.
4550 +** <tr><td> file:data.db?mode=readonly <td>
4551 +** An error. "readonly" is not a valid option for the "mode" parameter.
4552 +** </table>
4553 +**
4554 +** ^URI hexadecimal escape sequences (%HH) are supported within the path and
4555 +** query components of a URI. A hexadecimal escape sequence consists of a
4556 +** percent sign - "%" - followed by exactly two hexadecimal digits
4557 +** specifying an octet value. ^Before the path or query components of a
4558 +** URI filename are interpreted, they are encoded using UTF-8 and all
4559 +** hexadecimal escape sequences replaced by a single byte containing the
4560 +** corresponding octet. If this process generates an invalid UTF-8 encoding,
4561 +** the results are undefined.
4562 +**
4563 +** <b>Note to Windows users:</b> The encoding used for the filename argument
4564 +** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
4565 +** codepage is currently defined. Filenames containing international
4566 +** characters must be converted to UTF-8 prior to passing them into
4567 +** sqlite3_open() or sqlite3_open_v2().
4568 +**
4569 +** <b>Note to Windows Runtime users:</b> The temporary directory must be set
4570 +** prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various
4571 +** features that require the use of temporary files may fail.
4572 +**
4573 +** See also: [sqlite3_temp_directory]
4574 +*/
4575 +SQLITE_API int sqlite3_open(
4576 + const char *filename, /* Database filename (UTF-8) */
4577 + sqlite3 **ppDb /* OUT: SQLite db handle */
4578 +);
4579 +SQLITE_API int sqlite3_open16(
4580 + const void *filename, /* Database filename (UTF-16) */
4581 + sqlite3 **ppDb /* OUT: SQLite db handle */
4582 +);
4583 +SQLITE_API int sqlite3_open_v2(
4584 + const char *filename, /* Database filename (UTF-8) */
4585 + sqlite3 **ppDb, /* OUT: SQLite db handle */
4586 + int flags, /* Flags */
4587 + const char *zVfs /* Name of VFS module to use */
4588 +);
4589 +
4590 +/*
4591 +** CAPI3REF: Obtain Values For URI Parameters
4592 +**
4593 +** These are utility routines, useful to [VFS|custom VFS implementations],
4594 +** that check if a database file was a URI that contained a specific query
4595 +** parameter, and if so obtains the value of that query parameter.
4596 +**
4597 +** The first parameter to these interfaces (hereafter referred to
4598 +** as F) must be one of:
4599 +** <ul>
4600 +** <li> A database filename pointer created by the SQLite core and
4601 +** passed into the xOpen() method of a VFS implemention, or
4602 +** <li> A filename obtained from [sqlite3_db_filename()], or
4603 +** <li> A new filename constructed using [sqlite3_create_filename()].
4604 +** </ul>
4605 +** If the F parameter is not one of the above, then the behavior is
4606 +** undefined and probably undesirable. Older versions of SQLite were
4607 +** more tolerant of invalid F parameters than newer versions.
4608 +**
4609 +** If F is a suitable filename (as described in the previous paragraph)
4610 +** and if P is the name of the query parameter, then
4611 +** sqlite3_uri_parameter(F,P) returns the value of the P
4612 +** parameter if it exists or a NULL pointer if P does not appear as a
4613 +** query parameter on F. If P is a query parameter of F and it
4614 +** has no explicit value, then sqlite3_uri_parameter(F,P) returns
4615 +** a pointer to an empty string.
4616 +**
4617 +** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
4618 +** parameter and returns true (1) or false (0) according to the value
4619 +** of P. The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
4620 +** value of query parameter P is one of "yes", "true", or "on" in any
4621 +** case or if the value begins with a non-zero number. The
4622 +** sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
4623 +** query parameter P is one of "no", "false", or "off" in any case or
4624 +** if the value begins with a numeric zero. If P is not a query
4625 +** parameter on F or if the value of P does not match any of the
4626 +** above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).
4627 +**
4628 +** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
4629 +** 64-bit signed integer and returns that integer, or D if P does not
4630 +** exist. If the value of P is something other than an integer, then
4631 +** zero is returned.
4632 +**
4633 +** The sqlite3_uri_key(F,N) returns a pointer to the name (not
4634 +** the value) of the N-th query parameter for filename F, or a NULL
4635 +** pointer if N is less than zero or greater than the number of query
4636 +** parameters minus 1. The N value is zero-based so N should be 0 to obtain
4637 +** the name of the first query parameter, 1 for the second parameter, and
4638 +** so forth.
4639 +**
4640 +** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
4641 +** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and
4642 +** is not a database file pathname pointer that the SQLite core passed
4643 +** into the xOpen VFS method, then the behavior of this routine is undefined
4644 +** and probably undesirable.
4645 +**
4646 +** Beginning with SQLite [version 3.31.0] ([dateof:3.31.0]) the input F
4647 +** parameter can also be the name of a rollback journal file or WAL file
4648 +** in addition to the main database file. Prior to version 3.31.0, these
4649 +** routines would only work if F was the name of the main database file.
4650 +** When the F parameter is the name of the rollback journal or WAL file,
4651 +** it has access to all the same query parameters as were found on the
4652 +** main database file.
4653 +**
4654 +** See the [URI filename] documentation for additional information.
4655 +*/
4656 +SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
4657 +SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
4658 +SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
4659 +SQLITE_API const char *sqlite3_uri_key(const char *zFilename, int N);
4660 +
4661 +/*
4662 +** CAPI3REF: Translate filenames
4663 +**
4664 +** These routines are available to [VFS|custom VFS implementations] for
4665 +** translating filenames between the main database file, the journal file,
4666 +** and the WAL file.
4667 +**
4668 +** If F is the name of an sqlite database file, journal file, or WAL file
4669 +** passed by the SQLite core into the VFS, then sqlite3_filename_database(F)
4670 +** returns the name of the corresponding database file.
4671 +**
4672 +** If F is the name of an sqlite database file, journal file, or WAL file
4673 +** passed by the SQLite core into the VFS, or if F is a database filename
4674 +** obtained from [sqlite3_db_filename()], then sqlite3_filename_journal(F)
4675 +** returns the name of the corresponding rollback journal file.
4676 +**
4677 +** If F is the name of an sqlite database file, journal file, or WAL file
4678 +** that was passed by the SQLite core into the VFS, or if F is a database
4679 +** filename obtained from [sqlite3_db_filename()], then
4680 +** sqlite3_filename_wal(F) returns the name of the corresponding
4681 +** WAL file.
4682 +**
4683 +** In all of the above, if F is not the name of a database, journal or WAL
4684 +** filename passed into the VFS from the SQLite core and F is not the
4685 +** return value from [sqlite3_db_filename()], then the result is
4686 +** undefined and is likely a memory access violation.
4687 +*/
4688 +SQLITE_API const char *sqlite3_filename_database(const char*);
4689 +SQLITE_API const char *sqlite3_filename_journal(const char*);
4690 +SQLITE_API const char *sqlite3_filename_wal(const char*);
4691 +
4692 +/*
4693 +** CAPI3REF: Database File Corresponding To A Journal
4694 +**
4695 +** ^If X is the name of a rollback or WAL-mode journal file that is
4696 +** passed into the xOpen method of [sqlite3_vfs], then
4697 +** sqlite3_database_file_object(X) returns a pointer to the [sqlite3_file]
4698 +** object that represents the main database file.
4699 +**
4700 +** This routine is intended for use in custom [VFS] implementations
4701 +** only. It is not a general-purpose interface.
4702 +** The argument sqlite3_file_object(X) must be a filename pointer that
4703 +** has been passed into [sqlite3_vfs].xOpen method where the
4704 +** flags parameter to xOpen contains one of the bits
4705 +** [SQLITE_OPEN_MAIN_JOURNAL] or [SQLITE_OPEN_WAL]. Any other use
4706 +** of this routine results in undefined and probably undesirable
4707 +** behavior.
4708 +*/
4709 +SQLITE_API sqlite3_file *sqlite3_database_file_object(const char*);
4710 +
4711 +/*
4712 +** CAPI3REF: Create and Destroy VFS Filenames
4713 +**
4714 +** These interfces are provided for use by [VFS shim] implementations and
4715 +** are not useful outside of that context.
4716 +**
4717 +** The sqlite3_create_filename(D,J,W,N,P) allocates memory to hold a version of
4718 +** database filename D with corresponding journal file J and WAL file W and
4719 +** with N URI parameters key/values pairs in the array P. The result from
4720 +** sqlite3_create_filename(D,J,W,N,P) is a pointer to a database filename that
4721 +** is safe to pass to routines like:
4722 +** <ul>
4723 +** <li> [sqlite3_uri_parameter()],
4724 +** <li> [sqlite3_uri_boolean()],
4725 +** <li> [sqlite3_uri_int64()],
4726 +** <li> [sqlite3_uri_key()],
4727 +** <li> [sqlite3_filename_database()],
4728 +** <li> [sqlite3_filename_journal()], or
4729 +** <li> [sqlite3_filename_wal()].
4730 +** </ul>
4731 +** If a memory allocation error occurs, sqlite3_create_filename() might
4732 +** return a NULL pointer. The memory obtained from sqlite3_create_filename(X)
4733 +** must be released by a corresponding call to sqlite3_free_filename(Y).
4734 +**
4735 +** The P parameter in sqlite3_create_filename(D,J,W,N,P) should be an array
4736 +** of 2*N pointers to strings. Each pair of pointers in this array corresponds
4737 +** to a key and value for a query parameter. The P parameter may be a NULL
4738 +** pointer if N is zero. None of the 2*N pointers in the P array may be
4739 +** NULL pointers and key pointers should not be empty strings.
4740 +** None of the D, J, or W parameters to sqlite3_create_filename(D,J,W,N,P) may
4741 +** be NULL pointers, though they can be empty strings.
4742 +**
4743 +** The sqlite3_free_filename(Y) routine releases a memory allocation
4744 +** previously obtained from sqlite3_create_filename(). Invoking
4745 +** sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless no-op.
4746 +**
4747 +** If the Y parameter to sqlite3_free_filename(Y) is anything other
4748 +** than a NULL pointer or a pointer previously acquired from
4749 +** sqlite3_create_filename(), then bad things such as heap
4750 +** corruption or segfaults may occur. The value Y should be
4751 +** used again after sqlite3_free_filename(Y) has been called. This means
4752 +** that if the [sqlite3_vfs.xOpen()] method of a VFS has been called using Y,
4753 +** then the corresponding [sqlite3_module.xClose() method should also be
4754 +** invoked prior to calling sqlite3_free_filename(Y).
4755 +*/
4756 +SQLITE_API char *sqlite3_create_filename(
4757 + const char *zDatabase,
4758 + const char *zJournal,
4759 + const char *zWal,
4760 + int nParam,
4761 + const char **azParam
4762 +);
4763 +SQLITE_API void sqlite3_free_filename(char*);
4764 +
4765 +/*
4766 +** CAPI3REF: Error Codes And Messages
4767 +** METHOD: sqlite3
4768 +**
4769 +** ^If the most recent sqlite3_* API call associated with
4770 +** [database connection] D failed, then the sqlite3_errcode(D) interface
4771 +** returns the numeric [result code] or [extended result code] for that
4772 +** API call.
4773 +** ^The sqlite3_extended_errcode()
4774 +** interface is the same except that it always returns the
4775 +** [extended result code] even when extended result codes are
4776 +** disabled.
4777 +**
4778 +** The values returned by sqlite3_errcode() and/or
4779 +** sqlite3_extended_errcode() might change with each API call.
4780 +** Except, there are some interfaces that are guaranteed to never
4781 +** change the value of the error code. The error-code preserving
4782 +** interfaces are:
4783 +**
4784 +** <ul>
4785 +** <li> sqlite3_errcode()
4786 +** <li> sqlite3_extended_errcode()
4787 +** <li> sqlite3_errmsg()
4788 +** <li> sqlite3_errmsg16()
4789 +** </ul>
4790 +**
4791 +** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
4792 +** text that describes the error, as either UTF-8 or UTF-16 respectively.
4793 +** ^(Memory to hold the error message string is managed internally.
4794 +** The application does not need to worry about freeing the result.
4795 +** However, the error string might be overwritten or deallocated by
4796 +** subsequent calls to other SQLite interface functions.)^
4797 +**
4798 +** ^The sqlite3_errstr() interface returns the English-language text
4799 +** that describes the [result code], as UTF-8.
4800 +** ^(Memory to hold the error message string is managed internally
4801 +** and must not be freed by the application)^.
4802 +**
4803 +** When the serialized [threading mode] is in use, it might be the
4804 +** case that a second error occurs on a separate thread in between
4805 +** the time of the first error and the call to these interfaces.
4806 +** When that happens, the second error will be reported since these
4807 +** interfaces always report the most recent result. To avoid
4808 +** this, each thread can obtain exclusive use of the [database connection] D
4809 +** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
4810 +** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
4811 +** all calls to the interfaces listed here are completed.
4812 +**
4813 +** If an interface fails with SQLITE_MISUSE, that means the interface
4814 +** was invoked incorrectly by the application. In that case, the
4815 +** error code and message may or may not be set.
4816 +*/
4817 +SQLITE_API int sqlite3_errcode(sqlite3 *db);
4818 +SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
4819 +SQLITE_API const char *sqlite3_errmsg(sqlite3*);
4820 +SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
4821 +SQLITE_API const char *sqlite3_errstr(int);
4822 +
4823 +/*
4824 +** CAPI3REF: Prepared Statement Object
4825 +** KEYWORDS: {prepared statement} {prepared statements}
4826 +**
4827 +** An instance of this object represents a single SQL statement that
4828 +** has been compiled into binary form and is ready to be evaluated.
4829 +**
4830 +** Think of each SQL statement as a separate computer program. The
4831 +** original SQL text is source code. A prepared statement object
4832 +** is the compiled object code. All SQL must be converted into a
4833 +** prepared statement before it can be run.
4834 +**
4835 +** The life-cycle of a prepared statement object usually goes like this:
4836 +**
4837 +** <ol>
4838 +** <li> Create the prepared statement object using [sqlite3_prepare_v2()].
4839 +** <li> Bind values to [parameters] using the sqlite3_bind_*()
4840 +** interfaces.
4841 +** <li> Run the SQL by calling [sqlite3_step()] one or more times.
4842 +** <li> Reset the prepared statement using [sqlite3_reset()] then go back
4843 +** to step 2. Do this zero or more times.
4844 +** <li> Destroy the object using [sqlite3_finalize()].
4845 +** </ol>
4846 +*/
4847 +typedef struct sqlite3_stmt sqlite3_stmt;
4848 +
4849 +/*
4850 +** CAPI3REF: Run-time Limits
4851 +** METHOD: sqlite3
4852 +**
4853 +** ^(This interface allows the size of various constructs to be limited
4854 +** on a connection by connection basis. The first parameter is the
4855 +** [database connection] whose limit is to be set or queried. The
4856 +** second parameter is one of the [limit categories] that define a
4857 +** class of constructs to be size limited. The third parameter is the
4858 +** new limit for that construct.)^
4859 +**
4860 +** ^If the new limit is a negative number, the limit is unchanged.
4861 +** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
4862 +** [limits | hard upper bound]
4863 +** set at compile-time by a C preprocessor macro called
4864 +** [limits | SQLITE_MAX_<i>NAME</i>].
4865 +** (The "_LIMIT_" in the name is changed to "_MAX_".))^
4866 +** ^Attempts to increase a limit above its hard upper bound are
4867 +** silently truncated to the hard upper bound.
4868 +**
4869 +** ^Regardless of whether or not the limit was changed, the
4870 +** [sqlite3_limit()] interface returns the prior value of the limit.
4871 +** ^Hence, to find the current value of a limit without changing it,
4872 +** simply invoke this interface with the third parameter set to -1.
4873 +**
4874 +** Run-time limits are intended for use in applications that manage
4875 +** both their own internal database and also databases that are controlled
4876 +** by untrusted external sources. An example application might be a
4877 +** web browser that has its own databases for storing history and
4878 +** separate databases controlled by JavaScript applications downloaded
4879 +** off the Internet. The internal databases can be given the
4880 +** large, default limits. Databases managed by external sources can
4881 +** be given much smaller limits designed to prevent a denial of service
4882 +** attack. Developers might also want to use the [sqlite3_set_authorizer()]
4883 +** interface to further control untrusted SQL. The size of the database
4884 +** created by an untrusted script can be contained using the
4885 +** [max_page_count] [PRAGMA].
4886 +**
4887 +** New run-time limit categories may be added in future releases.
4888 +*/
4889 +SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
4890 +
4891 +/*
4892 +** CAPI3REF: Run-Time Limit Categories
4893 +** KEYWORDS: {limit category} {*limit categories}
4894 +**
4895 +** These constants define various performance limits
4896 +** that can be lowered at run-time using [sqlite3_limit()].
4897 +** The synopsis of the meanings of the various limits is shown below.
4898 +** Additional information is available at [limits | Limits in SQLite].
4899 +**
4900 +** <dl>
4901 +** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
4902 +** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
4903 +**
4904 +** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
4905 +** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
4906 +**
4907 +** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
4908 +** <dd>The maximum number of columns in a table definition or in the
4909 +** result set of a [SELECT] or the maximum number of columns in an index
4910 +** or in an ORDER BY or GROUP BY clause.</dd>)^
4911 +**
4912 +** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
4913 +** <dd>The maximum depth of the parse tree on any expression.</dd>)^
4914 +**
4915 +** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
4916 +** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
4917 +**
4918 +** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
4919 +** <dd>The maximum number of instructions in a virtual machine program
4920 +** used to implement an SQL statement. If [sqlite3_prepare_v2()] or
4921 +** the equivalent tries to allocate space for more than this many opcodes
4922 +** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^
4923 +**
4924 +** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
4925 +** <dd>The maximum number of arguments on a function.</dd>)^
4926 +**
4927 +** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
4928 +** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
4929 +**
4930 +** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
4931 +** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
4932 +** <dd>The maximum length of the pattern argument to the [LIKE] or
4933 +** [GLOB] operators.</dd>)^
4934 +**
4935 +** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
4936 +** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
4937 +** <dd>The maximum index number of any [parameter] in an SQL statement.)^
4938 +**
4939 +** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
4940 +** <dd>The maximum depth of recursion for triggers.</dd>)^
4941 +**
4942 +** [[SQLITE_LIMIT_WORKER_THREADS]] ^(<dt>SQLITE_LIMIT_WORKER_THREADS</dt>
4943 +** <dd>The maximum number of auxiliary worker threads that a single
4944 +** [prepared statement] may start.</dd>)^
4945 +** </dl>
4946 +*/
4947 +#define SQLITE_LIMIT_LENGTH 0
4948 +#define SQLITE_LIMIT_SQL_LENGTH 1
4949 +#define SQLITE_LIMIT_COLUMN 2
4950 +#define SQLITE_LIMIT_EXPR_DEPTH 3
4951 +#define SQLITE_LIMIT_COMPOUND_SELECT 4
4952 +#define SQLITE_LIMIT_VDBE_OP 5
4953 +#define SQLITE_LIMIT_FUNCTION_ARG 6
4954 +#define SQLITE_LIMIT_ATTACHED 7
4955 +#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8
4956 +#define SQLITE_LIMIT_VARIABLE_NUMBER 9
4957 +#define SQLITE_LIMIT_TRIGGER_DEPTH 10
4958 +#define SQLITE_LIMIT_WORKER_THREADS 11
4959 +
4960 +/*
4961 +** CAPI3REF: Prepare Flags
4962 +**
4963 +** These constants define various flags that can be passed into
4964 +** "prepFlags" parameter of the [sqlite3_prepare_v3()] and
4965 +** [sqlite3_prepare16_v3()] interfaces.
4966 +**
4967 +** New flags may be added in future releases of SQLite.
4968 +**
4969 +** <dl>
4970 +** [[SQLITE_PREPARE_PERSISTENT]] ^(<dt>SQLITE_PREPARE_PERSISTENT</dt>
4971 +** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
4972 +** that the prepared statement will be retained for a long time and
4973 +** probably reused many times.)^ ^Without this flag, [sqlite3_prepare_v3()]
4974 +** and [sqlite3_prepare16_v3()] assume that the prepared statement will
4975 +** be used just once or at most a few times and then destroyed using
4976 +** [sqlite3_finalize()] relatively soon. The current implementation acts
4977 +** on this hint by avoiding the use of [lookaside memory] so as not to
4978 +** deplete the limited store of lookaside memory. Future versions of
4979 +** SQLite may act on this hint differently.
4980 +**
4981 +** [[SQLITE_PREPARE_NORMALIZE]] <dt>SQLITE_PREPARE_NORMALIZE</dt>
4982 +** <dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used
4983 +** to be required for any prepared statement that wanted to use the
4984 +** [sqlite3_normalized_sql()] interface. However, the
4985 +** [sqlite3_normalized_sql()] interface is now available to all
4986 +** prepared statements, regardless of whether or not they use this
4987 +** flag.
4988 +**
4989 +** [[SQLITE_PREPARE_NO_VTAB]] <dt>SQLITE_PREPARE_NO_VTAB</dt>
4990 +** <dd>The SQLITE_PREPARE_NO_VTAB flag causes the SQL compiler
4991 +** to return an error (error code SQLITE_ERROR) if the statement uses
4992 +** any virtual tables.
4993 +** </dl>
4994 +*/
4995 +#define SQLITE_PREPARE_PERSISTENT 0x01
4996 +#define SQLITE_PREPARE_NORMALIZE 0x02
4997 +#define SQLITE_PREPARE_NO_VTAB 0x04
4998 +
4999 +/*

This file is too large to show in full.

database/sqlite/sqlite3.h new
+12174
@@ -0,0 +1,12174 @@
1 +/*
2 +** 2001-09-15
3 +**
4 +** The author disclaims copyright to this source code. In place of
5 +** a legal notice, here is a blessing:
6 +**
7 +** May you do good and not evil.
8 +** May you find forgiveness for yourself and forgive others.
9 +** May you share freely, never taking more than you give.
10 +**
11 +*************************************************************************
12 +** This header file defines the interface that the SQLite library
13 +** presents to client programs. If a C-function, structure, datatype,
14 +** or constant definition does not appear in this file, then it is
15 +** not a published API of SQLite, is subject to change without
16 +** notice, and should not be referenced by programs that use SQLite.
17 +**
18 +** Some of the definitions that are in this file are marked as
19 +** "experimental". Experimental interfaces are normally new
20 +** features recently added to SQLite. We do not anticipate changes
21 +** to experimental interfaces but reserve the right to make minor changes
22 +** if experience from use "in the wild" suggest such changes are prudent.
23 +**
24 +** The official C-language API documentation for SQLite is derived
25 +** from comments in this file. This file is the authoritative source
26 +** on how SQLite interfaces are supposed to operate.
27 +**
28 +** The name of this file under configuration management is "sqlite.h.in".
29 +** The makefile makes some minor changes to this file (such as inserting
30 +** the version number) and changes its name to "sqlite3.h" as
31 +** part of the build process.
32 +*/
33 +#ifndef SQLITE3_H
34 +#define SQLITE3_H
35 +#include <stdarg.h> /* Needed for the definition of va_list */
36 +
37 +/*
38 +** Make sure we can call this stuff from C++.
39 +*/
40 +#ifdef __cplusplus
41 +extern "C" {
42 +#endif
43 +
44 +
45 +/*
46 +** Provide the ability to override linkage features of the interface.
47 +*/
48 +#ifndef SQLITE_EXTERN
49 +# define SQLITE_EXTERN extern
50 +#endif
51 +#ifndef SQLITE_API
52 +# define SQLITE_API
53 +#endif
54 +#ifndef SQLITE_CDECL
55 +# define SQLITE_CDECL
56 +#endif
57 +#ifndef SQLITE_APICALL
58 +# define SQLITE_APICALL
59 +#endif
60 +#ifndef SQLITE_STDCALL
61 +# define SQLITE_STDCALL SQLITE_APICALL
62 +#endif
63 +#ifndef SQLITE_CALLBACK
64 +# define SQLITE_CALLBACK
65 +#endif
66 +#ifndef SQLITE_SYSAPI
67 +# define SQLITE_SYSAPI
68 +#endif
69 +
70 +/*
71 +** These no-op macros are used in front of interfaces to mark those
72 +** interfaces as either deprecated or experimental. New applications
73 +** should not use deprecated interfaces - they are supported for backwards
74 +** compatibility only. Application writers should be aware that
75 +** experimental interfaces are subject to change in point releases.
76 +**
77 +** These macros used to resolve to various kinds of compiler magic that
78 +** would generate warning messages when they were used. But that
79 +** compiler magic ended up generating such a flurry of bug reports
80 +** that we have taken it all out and gone back to using simple
81 +** noop macros.
82 +*/
83 +#define SQLITE_DEPRECATED
84 +#define SQLITE_EXPERIMENTAL
85 +
86 +/*
87 +** Ensure these symbols were not defined by some previous header file.
88 +*/
89 +#ifdef SQLITE_VERSION
90 +# undef SQLITE_VERSION
91 +#endif
92 +#ifdef SQLITE_VERSION_NUMBER
93 +# undef SQLITE_VERSION_NUMBER
94 +#endif
95 +
96 +/*
97 +** CAPI3REF: Compile-Time Library Version Numbers
98 +**
99 +** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
100 +** evaluates to a string literal that is the SQLite version in the
101 +** format "X.Y.Z" where X is the major version number (always 3 for
102 +** SQLite3) and Y is the minor version number and Z is the release number.)^
103 +** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
104 +** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
105 +** numbers used in [SQLITE_VERSION].)^
106 +** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
107 +** be larger than the release from which it is derived. Either Y will
108 +** be held constant and Z will be incremented or else Y will be incremented
109 +** and Z will be reset to zero.
110 +**
111 +** Since [version 3.6.18] ([dateof:3.6.18]),
112 +** SQLite source code has been stored in the
113 +** <a href="http://www.fossil-scm.org/">Fossil configuration management
114 +** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to
115 +** a string which identifies a particular check-in of SQLite
116 +** within its configuration management system. ^The SQLITE_SOURCE_ID
117 +** string contains the date and time of the check-in (UTC) and a SHA1
118 +** or SHA3-256 hash of the entire source tree. If the source code has
119 +** been edited in any way since it was last checked in, then the last
120 +** four hexadecimal digits of the hash may be modified.
121 +**
122 +** See also: [sqlite3_libversion()],
123 +** [sqlite3_libversion_number()], [sqlite3_sourceid()],
124 +** [sqlite_version()] and [sqlite_source_id()].
125 +*/
126 +#define SQLITE_VERSION "3.33.0"
127 +#define SQLITE_VERSION_NUMBER 3033000
128 +#define SQLITE_SOURCE_ID "2020-08-14 13:23:32 fca8dc8b578f215a969cd899336378966156154710873e68b3d9ac5881b0alt1"
129 +
130 +/*
131 +** CAPI3REF: Run-Time Library Version Numbers
132 +** KEYWORDS: sqlite3_version sqlite3_sourceid
133 +**
134 +** These interfaces provide the same information as the [SQLITE_VERSION],
135 +** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
136 +** but are associated with the library instead of the header file. ^(Cautious
137 +** programmers might include assert() statements in their application to
138 +** verify that values returned by these interfaces match the macros in
139 +** the header, and thus ensure that the application is
140 +** compiled with matching library and header files.
141 +**
142 +** <blockquote><pre>
143 +** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
144 +** assert( strncmp(sqlite3_sourceid(),SQLITE_SOURCE_ID,80)==0 );
145 +** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
146 +** </pre></blockquote>)^
147 +**
148 +** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
149 +** macro. ^The sqlite3_libversion() function returns a pointer to the
150 +** to the sqlite3_version[] string constant. The sqlite3_libversion()
151 +** function is provided for use in DLLs since DLL users usually do not have
152 +** direct access to string constants within the DLL. ^The
153 +** sqlite3_libversion_number() function returns an integer equal to
154 +** [SQLITE_VERSION_NUMBER]. ^(The sqlite3_sourceid() function returns
155 +** a pointer to a string constant whose value is the same as the
156 +** [SQLITE_SOURCE_ID] C preprocessor macro. Except if SQLite is built
157 +** using an edited copy of [the amalgamation], then the last four characters
158 +** of the hash might be different from [SQLITE_SOURCE_ID].)^
159 +**
160 +** See also: [sqlite_version()] and [sqlite_source_id()].
161 +*/
162 +SQLITE_API SQLITE_EXTERN const char sqlite3_version[];
163 +SQLITE_API const char *sqlite3_libversion(void);
164 +SQLITE_API const char *sqlite3_sourceid(void);
165 +SQLITE_API int sqlite3_libversion_number(void);
166 +
167 +/*
168 +** CAPI3REF: Run-Time Library Compilation Options Diagnostics
169 +**
170 +** ^The sqlite3_compileoption_used() function returns 0 or 1
171 +** indicating whether the specified option was defined at
172 +** compile time. ^The SQLITE_ prefix may be omitted from the
173 +** option name passed to sqlite3_compileoption_used().
174 +**
175 +** ^The sqlite3_compileoption_get() function allows iterating
176 +** over the list of options that were defined at compile time by
177 +** returning the N-th compile time option string. ^If N is out of range,
178 +** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_
179 +** prefix is omitted from any strings returned by
180 +** sqlite3_compileoption_get().
181 +**
182 +** ^Support for the diagnostic functions sqlite3_compileoption_used()
183 +** and sqlite3_compileoption_get() may be omitted by specifying the
184 +** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
185 +**
186 +** See also: SQL functions [sqlite_compileoption_used()] and
187 +** [sqlite_compileoption_get()] and the [compile_options pragma].
188 +*/
189 +#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
190 +SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
191 +SQLITE_API const char *sqlite3_compileoption_get(int N);
192 +#else
193 +# define sqlite3_compileoption_used(X) 0
194 +# define sqlite3_compileoption_get(X) ((void*)0)
195 +#endif
196 +
197 +/*
198 +** CAPI3REF: Test To See If The Library Is Threadsafe
199 +**
200 +** ^The sqlite3_threadsafe() function returns zero if and only if
201 +** SQLite was compiled with mutexing code omitted due to the
202 +** [SQLITE_THREADSAFE] compile-time option being set to 0.
203 +**
204 +** SQLite can be compiled with or without mutexes. When
205 +** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
206 +** are enabled and SQLite is threadsafe. When the
207 +** [SQLITE_THREADSAFE] macro is 0,
208 +** the mutexes are omitted. Without the mutexes, it is not safe
209 +** to use SQLite concurrently from more than one thread.
210 +**
211 +** Enabling mutexes incurs a measurable performance penalty.
212 +** So if speed is of utmost importance, it makes sense to disable
213 +** the mutexes. But for maximum safety, mutexes should be enabled.
214 +** ^The default behavior is for mutexes to be enabled.
215 +**
216 +** This interface can be used by an application to make sure that the
217 +** version of SQLite that it is linking against was compiled with
218 +** the desired setting of the [SQLITE_THREADSAFE] macro.
219 +**
220 +** This interface only reports on the compile-time mutex setting
221 +** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with
222 +** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
223 +** can be fully or partially disabled using a call to [sqlite3_config()]
224 +** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
225 +** or [SQLITE_CONFIG_SERIALIZED]. ^(The return value of the
226 +** sqlite3_threadsafe() function shows only the compile-time setting of
227 +** thread safety, not any run-time changes to that setting made by
228 +** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
229 +** is unchanged by calls to sqlite3_config().)^
230 +**
231 +** See the [threading mode] documentation for additional information.
232 +*/
233 +SQLITE_API int sqlite3_threadsafe(void);
234 +
235 +/*
236 +** CAPI3REF: Database Connection Handle
237 +** KEYWORDS: {database connection} {database connections}
238 +**
239 +** Each open SQLite database is represented by a pointer to an instance of
240 +** the opaque structure named "sqlite3". It is useful to think of an sqlite3
241 +** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
242 +** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
243 +** and [sqlite3_close_v2()] are its destructors. There are many other
244 +** interfaces (such as
245 +** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
246 +** [sqlite3_busy_timeout()] to name but three) that are methods on an
247 +** sqlite3 object.
248 +*/
249 +typedef struct sqlite3 sqlite3;
250 +
251 +/*
252 +** CAPI3REF: 64-Bit Integer Types
253 +** KEYWORDS: sqlite_int64 sqlite_uint64
254 +**
255 +** Because there is no cross-platform way to specify 64-bit integer types
256 +** SQLite includes typedefs for 64-bit signed and unsigned integers.
257 +**
258 +** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
259 +** The sqlite_int64 and sqlite_uint64 types are supported for backwards
260 +** compatibility only.
261 +**
262 +** ^The sqlite3_int64 and sqlite_int64 types can store integer values
263 +** between -9223372036854775808 and +9223372036854775807 inclusive. ^The
264 +** sqlite3_uint64 and sqlite_uint64 types can store integer values
265 +** between 0 and +18446744073709551615 inclusive.
266 +*/
267 +#ifdef SQLITE_INT64_TYPE
268 + typedef SQLITE_INT64_TYPE sqlite_int64;
269 +# ifdef SQLITE_UINT64_TYPE
270 + typedef SQLITE_UINT64_TYPE sqlite_uint64;
271 +# else
272 + typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
273 +# endif
274 +#elif defined(_MSC_VER) || defined(__BORLANDC__)
275 + typedef __int64 sqlite_int64;
276 + typedef unsigned __int64 sqlite_uint64;
277 +#else
278 + typedef long long int sqlite_int64;
279 + typedef unsigned long long int sqlite_uint64;
280 +#endif
281 +typedef sqlite_int64 sqlite3_int64;
282 +typedef sqlite_uint64 sqlite3_uint64;
283 +
284 +/*
285 +** If compiling for a processor that lacks floating point support,
286 +** substitute integer for floating-point.
287 +*/
288 +#ifdef SQLITE_OMIT_FLOATING_POINT
289 +# define double sqlite3_int64
290 +#endif
291 +
292 +/*
293 +** CAPI3REF: Closing A Database Connection
294 +** DESTRUCTOR: sqlite3
295 +**
296 +** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
297 +** for the [sqlite3] object.
298 +** ^Calls to sqlite3_close() and sqlite3_close_v2() return [SQLITE_OK] if
299 +** the [sqlite3] object is successfully destroyed and all associated
300 +** resources are deallocated.
301 +**
302 +** Ideally, applications should [sqlite3_finalize | finalize] all
303 +** [prepared statements], [sqlite3_blob_close | close] all [BLOB handles], and
304 +** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated
305 +** with the [sqlite3] object prior to attempting to close the object.
306 +** ^If the database connection is associated with unfinalized prepared
307 +** statements, BLOB handlers, and/or unfinished sqlite3_backup objects then
308 +** sqlite3_close() will leave the database connection open and return
309 +** [SQLITE_BUSY]. ^If sqlite3_close_v2() is called with unfinalized prepared
310 +** statements, unclosed BLOB handlers, and/or unfinished sqlite3_backups,
311 +** it returns [SQLITE_OK] regardless, but instead of deallocating the database
312 +** connection immediately, it marks the database connection as an unusable
313 +** "zombie" and makes arrangements to automatically deallocate the database
314 +** connection after all prepared statements are finalized, all BLOB handles
315 +** are closed, and all backups have finished. The sqlite3_close_v2() interface
316 +** is intended for use with host languages that are garbage collected, and
317 +** where the order in which destructors are called is arbitrary.
318 +**
319 +** ^If an [sqlite3] object is destroyed while a transaction is open,
320 +** the transaction is automatically rolled back.
321 +**
322 +** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
323 +** must be either a NULL
324 +** pointer or an [sqlite3] object pointer obtained
325 +** from [sqlite3_open()], [sqlite3_open16()], or
326 +** [sqlite3_open_v2()], and not previously closed.
327 +** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
328 +** argument is a harmless no-op.
329 +*/
330 +SQLITE_API int sqlite3_close(sqlite3*);
331 +SQLITE_API int sqlite3_close_v2(sqlite3*);
332 +
333 +/*
334 +** The type for a callback function.
335 +** This is legacy and deprecated. It is included for historical
336 +** compatibility and is not documented.
337 +*/
338 +typedef int (*sqlite3_callback)(void*,int,char**, char**);
339 +
340 +/*
341 +** CAPI3REF: One-Step Query Execution Interface
342 +** METHOD: sqlite3
343 +**
344 +** The sqlite3_exec() interface is a convenience wrapper around
345 +** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
346 +** that allows an application to run multiple statements of SQL
347 +** without having to use a lot of C code.
348 +**
349 +** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
350 +** semicolon-separate SQL statements passed into its 2nd argument,
351 +** in the context of the [database connection] passed in as its 1st
352 +** argument. ^If the callback function of the 3rd argument to
353 +** sqlite3_exec() is not NULL, then it is invoked for each result row
354 +** coming out of the evaluated SQL statements. ^The 4th argument to
355 +** sqlite3_exec() is relayed through to the 1st argument of each
356 +** callback invocation. ^If the callback pointer to sqlite3_exec()
357 +** is NULL, then no callback is ever invoked and result rows are
358 +** ignored.
359 +**
360 +** ^If an error occurs while evaluating the SQL statements passed into
361 +** sqlite3_exec(), then execution of the current statement stops and
362 +** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec()
363 +** is not NULL then any error message is written into memory obtained
364 +** from [sqlite3_malloc()] and passed back through the 5th parameter.
365 +** To avoid memory leaks, the application should invoke [sqlite3_free()]
366 +** on error message strings returned through the 5th parameter of
367 +** sqlite3_exec() after the error message string is no longer needed.
368 +** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
369 +** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
370 +** NULL before returning.
371 +**
372 +** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
373 +** routine returns SQLITE_ABORT without invoking the callback again and
374 +** without running any subsequent SQL statements.
375 +**
376 +** ^The 2nd argument to the sqlite3_exec() callback function is the
377 +** number of columns in the result. ^The 3rd argument to the sqlite3_exec()
378 +** callback is an array of pointers to strings obtained as if from
379 +** [sqlite3_column_text()], one for each column. ^If an element of a
380 +** result row is NULL then the corresponding string pointer for the
381 +** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
382 +** sqlite3_exec() callback is an array of pointers to strings where each
383 +** entry represents the name of corresponding result column as obtained
384 +** from [sqlite3_column_name()].
385 +**
386 +** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
387 +** to an empty string, or a pointer that contains only whitespace and/or
388 +** SQL comments, then no SQL statements are evaluated and the database
389 +** is not changed.
390 +**
391 +** Restrictions:
392 +**
393 +** <ul>
394 +** <li> The application must ensure that the 1st parameter to sqlite3_exec()
395 +** is a valid and open [database connection].
396 +** <li> The application must not close the [database connection] specified by
397 +** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
398 +** <li> The application must not modify the SQL statement text passed into
399 +** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
400 +** </ul>
401 +*/
402 +SQLITE_API int sqlite3_exec(
403 + sqlite3*, /* An open database */
404 + const char *sql, /* SQL to be evaluated */
405 + int (*callback)(void*,int,char**,char**), /* Callback function */
406 + void *, /* 1st argument to callback */
407 + char **errmsg /* Error msg written here */
408 +);
409 +
410 +/*
411 +** CAPI3REF: Result Codes
412 +** KEYWORDS: {result code definitions}
413 +**
414 +** Many SQLite functions return an integer result code from the set shown
415 +** here in order to indicate success or failure.
416 +**
417 +** New error codes may be added in future versions of SQLite.
418 +**
419 +** See also: [extended result code definitions]
420 +*/
421 +#define SQLITE_OK 0 /* Successful result */
422 +/* beginning-of-error-codes */
423 +#define SQLITE_ERROR 1 /* Generic error */
424 +#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
425 +#define SQLITE_PERM 3 /* Access permission denied */
426 +#define SQLITE_ABORT 4 /* Callback routine requested an abort */
427 +#define SQLITE_BUSY 5 /* The database file is locked */
428 +#define SQLITE_LOCKED 6 /* A table in the database is locked */
429 +#define SQLITE_NOMEM 7 /* A malloc() failed */
430 +#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
431 +#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
432 +#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
433 +#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
434 +#define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */
435 +#define SQLITE_FULL 13 /* Insertion failed because database is full */
436 +#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
437 +#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
438 +#define SQLITE_EMPTY 16 /* Internal use only */
439 +#define SQLITE_SCHEMA 17 /* The database schema changed */
440 +#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
441 +#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
442 +#define SQLITE_MISMATCH 20 /* Data type mismatch */
443 +#define SQLITE_MISUSE 21 /* Library used incorrectly */
444 +#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
445 +#define SQLITE_AUTH 23 /* Authorization denied */
446 +#define SQLITE_FORMAT 24 /* Not used */
447 +#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
448 +#define SQLITE_NOTADB 26 /* File opened that is not a database file */
449 +#define SQLITE_NOTICE 27 /* Notifications from sqlite3_log() */
450 +#define SQLITE_WARNING 28 /* Warnings from sqlite3_log() */
451 +#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
452 +#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
453 +/* end-of-error-codes */
454 +
455 +/*
456 +** CAPI3REF: Extended Result Codes
457 +** KEYWORDS: {extended result code definitions}
458 +**
459 +** In its default configuration, SQLite API routines return one of 30 integer
460 +** [result codes]. However, experience has shown that many of
461 +** these result codes are too coarse-grained. They do not provide as
462 +** much information about problems as programmers might like. In an effort to
463 +** address this, newer versions of SQLite (version 3.3.8 [dateof:3.3.8]
464 +** and later) include
465 +** support for additional result codes that provide more detailed information
466 +** about errors. These [extended result codes] are enabled or disabled
467 +** on a per database connection basis using the
468 +** [sqlite3_extended_result_codes()] API. Or, the extended code for
469 +** the most recent error can be obtained using
470 +** [sqlite3_extended_errcode()].
471 +*/
472 +#define SQLITE_ERROR_MISSING_COLLSEQ (SQLITE_ERROR | (1<<8))
473 +#define SQLITE_ERROR_RETRY (SQLITE_ERROR | (2<<8))
474 +#define SQLITE_ERROR_SNAPSHOT (SQLITE_ERROR | (3<<8))
475 +#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
476 +#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
477 +#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))
478 +#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))
479 +#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))
480 +#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))
481 +#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))
482 +#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))
483 +#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))
484 +#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
485 +#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
486 +#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))
487 +#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8))
488 +#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
489 +#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8))
490 +#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8))
491 +#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8))
492 +#define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8))
493 +#define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8))
494 +#define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8))
495 +#define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8))
496 +#define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8))
497 +#define SQLITE_IOERR_DELETE_NOENT (SQLITE_IOERR | (23<<8))
498 +#define SQLITE_IOERR_MMAP (SQLITE_IOERR | (24<<8))
499 +#define SQLITE_IOERR_GETTEMPPATH (SQLITE_IOERR | (25<<8))
500 +#define SQLITE_IOERR_CONVPATH (SQLITE_IOERR | (26<<8))
501 +#define SQLITE_IOERR_VNODE (SQLITE_IOERR | (27<<8))
502 +#define SQLITE_IOERR_AUTH (SQLITE_IOERR | (28<<8))
503 +#define SQLITE_IOERR_BEGIN_ATOMIC (SQLITE_IOERR | (29<<8))
504 +#define SQLITE_IOERR_COMMIT_ATOMIC (SQLITE_IOERR | (30<<8))
505 +#define SQLITE_IOERR_ROLLBACK_ATOMIC (SQLITE_IOERR | (31<<8))
506 +#define SQLITE_IOERR_DATA (SQLITE_IOERR | (32<<8))
507 +#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))
508 +#define SQLITE_LOCKED_VTAB (SQLITE_LOCKED | (2<<8))
509 +#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))
510 +#define SQLITE_BUSY_SNAPSHOT (SQLITE_BUSY | (2<<8))
511 +#define SQLITE_BUSY_TIMEOUT (SQLITE_BUSY | (3<<8))
512 +#define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8))
513 +#define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8))
514 +#define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8))
515 +#define SQLITE_CANTOPEN_CONVPATH (SQLITE_CANTOPEN | (4<<8))
516 +#define SQLITE_CANTOPEN_DIRTYWAL (SQLITE_CANTOPEN | (5<<8)) /* Not Used */
517 +#define SQLITE_CANTOPEN_SYMLINK (SQLITE_CANTOPEN | (6<<8))
518 +#define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8))
519 +#define SQLITE_CORRUPT_SEQUENCE (SQLITE_CORRUPT | (2<<8))
520 +#define SQLITE_CORRUPT_INDEX (SQLITE_CORRUPT | (3<<8))
521 +#define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8))
522 +#define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8))
523 +#define SQLITE_READONLY_ROLLBACK (SQLITE_READONLY | (3<<8))
524 +#define SQLITE_READONLY_DBMOVED (SQLITE_READONLY | (4<<8))
525 +#define SQLITE_READONLY_CANTINIT (SQLITE_READONLY | (5<<8))
526 +#define SQLITE_READONLY_DIRECTORY (SQLITE_READONLY | (6<<8))
527 +#define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8))
528 +#define SQLITE_CONSTRAINT_CHECK (SQLITE_CONSTRAINT | (1<<8))
529 +#define SQLITE_CONSTRAINT_COMMITHOOK (SQLITE_CONSTRAINT | (2<<8))
530 +#define SQLITE_CONSTRAINT_FOREIGNKEY (SQLITE_CONSTRAINT | (3<<8))
531 +#define SQLITE_CONSTRAINT_FUNCTION (SQLITE_CONSTRAINT | (4<<8))
532 +#define SQLITE_CONSTRAINT_NOTNULL (SQLITE_CONSTRAINT | (5<<8))
533 +#define SQLITE_CONSTRAINT_PRIMARYKEY (SQLITE_CONSTRAINT | (6<<8))
534 +#define SQLITE_CONSTRAINT_TRIGGER (SQLITE_CONSTRAINT | (7<<8))
535 +#define SQLITE_CONSTRAINT_UNIQUE (SQLITE_CONSTRAINT | (8<<8))
536 +#define SQLITE_CONSTRAINT_VTAB (SQLITE_CONSTRAINT | (9<<8))
537 +#define SQLITE_CONSTRAINT_ROWID (SQLITE_CONSTRAINT |(10<<8))
538 +#define SQLITE_CONSTRAINT_PINNED (SQLITE_CONSTRAINT |(11<<8))
539 +#define SQLITE_NOTICE_RECOVER_WAL (SQLITE_NOTICE | (1<<8))
540 +#define SQLITE_NOTICE_RECOVER_ROLLBACK (SQLITE_NOTICE | (2<<8))
541 +#define SQLITE_WARNING_AUTOINDEX (SQLITE_WARNING | (1<<8))
542 +#define SQLITE_AUTH_USER (SQLITE_AUTH | (1<<8))
543 +#define SQLITE_OK_LOAD_PERMANENTLY (SQLITE_OK | (1<<8))
544 +#define SQLITE_OK_SYMLINK (SQLITE_OK | (2<<8))
545 +
546 +/*
547 +** CAPI3REF: Flags For File Open Operations
548 +**
549 +** These bit values are intended for use in the
550 +** 3rd parameter to the [sqlite3_open_v2()] interface and
551 +** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
552 +*/
553 +#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
554 +#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
555 +#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */
556 +#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */
557 +#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */
558 +#define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */
559 +#define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */
560 +#define SQLITE_OPEN_MEMORY 0x00000080 /* Ok for sqlite3_open_v2() */
561 +#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */
562 +#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */
563 +#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */
564 +#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */
565 +#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */
566 +#define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */
567 +#define SQLITE_OPEN_SUPER_JOURNAL 0x00004000 /* VFS only */
568 +#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */
569 +#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */
570 +#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */
571 +#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
572 +#define SQLITE_OPEN_WAL 0x00080000 /* VFS only */
573 +#define SQLITE_OPEN_NOFOLLOW 0x01000000 /* Ok for sqlite3_open_v2() */
574 +
575 +/* Reserved: 0x00F00000 */
576 +/* Legacy compatibility: */
577 +#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */
578 +
579 +
580 +/*
581 +** CAPI3REF: Device Characteristics
582 +**
583 +** The xDeviceCharacteristics method of the [sqlite3_io_methods]
584 +** object returns an integer which is a vector of these
585 +** bit values expressing I/O characteristics of the mass storage
586 +** device that holds the file that the [sqlite3_io_methods]
587 +** refers to.
588 +**
589 +** The SQLITE_IOCAP_ATOMIC property means that all writes of
590 +** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
591 +** mean that writes of blocks that are nnn bytes in size and
592 +** are aligned to an address which is an integer multiple of
593 +** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
594 +** that when data is appended to a file, the data is appended
595 +** first then the size of the file is extended, never the other
596 +** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
597 +** information is written to disk in the same order as calls
598 +** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
599 +** after reboot following a crash or power loss, the only bytes in a
600 +** file that were written at the application level might have changed
601 +** and that adjacent bytes, even bytes within the same sector are
602 +** guaranteed to be unchanged. The SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN
603 +** flag indicates that a file cannot be deleted when open. The
604 +** SQLITE_IOCAP_IMMUTABLE flag indicates that the file is on
605 +** read-only media and cannot be changed even by processes with
606 +** elevated privileges.
607 +**
608 +** The SQLITE_IOCAP_BATCH_ATOMIC property means that the underlying
609 +** filesystem supports doing multiple write operations atomically when those
610 +** write operations are bracketed by [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] and
611 +** [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE].
612 +*/
613 +#define SQLITE_IOCAP_ATOMIC 0x00000001
614 +#define SQLITE_IOCAP_ATOMIC512 0x00000002
615 +#define SQLITE_IOCAP_ATOMIC1K 0x00000004
616 +#define SQLITE_IOCAP_ATOMIC2K 0x00000008
617 +#define SQLITE_IOCAP_ATOMIC4K 0x00000010
618 +#define SQLITE_IOCAP_ATOMIC8K 0x00000020
619 +#define SQLITE_IOCAP_ATOMIC16K 0x00000040
620 +#define SQLITE_IOCAP_ATOMIC32K 0x00000080
621 +#define SQLITE_IOCAP_ATOMIC64K 0x00000100
622 +#define SQLITE_IOCAP_SAFE_APPEND 0x00000200
623 +#define SQLITE_IOCAP_SEQUENTIAL 0x00000400
624 +#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800
625 +#define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000
626 +#define SQLITE_IOCAP_IMMUTABLE 0x00002000
627 +#define SQLITE_IOCAP_BATCH_ATOMIC 0x00004000
628 +
629 +/*
630 +** CAPI3REF: File Locking Levels
631 +**
632 +** SQLite uses one of these integer values as the second
633 +** argument to calls it makes to the xLock() and xUnlock() methods
634 +** of an [sqlite3_io_methods] object.
635 +*/
636 +#define SQLITE_LOCK_NONE 0
637 +#define SQLITE_LOCK_SHARED 1
638 +#define SQLITE_LOCK_RESERVED 2
639 +#define SQLITE_LOCK_PENDING 3
640 +#define SQLITE_LOCK_EXCLUSIVE 4
641 +
642 +/*
643 +** CAPI3REF: Synchronization Type Flags
644 +**
645 +** When SQLite invokes the xSync() method of an
646 +** [sqlite3_io_methods] object it uses a combination of
647 +** these integer values as the second argument.
648 +**
649 +** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
650 +** sync operation only needs to flush data to mass storage. Inode
651 +** information need not be flushed. If the lower four bits of the flag
652 +** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
653 +** If the lower four bits equal SQLITE_SYNC_FULL, that means
654 +** to use Mac OS X style fullsync instead of fsync().
655 +**
656 +** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
657 +** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
658 +** settings. The [synchronous pragma] determines when calls to the
659 +** xSync VFS method occur and applies uniformly across all platforms.
660 +** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
661 +** energetic or rigorous or forceful the sync operations are and
662 +** only make a difference on Mac OSX for the default SQLite code.
663 +** (Third-party VFS implementations might also make the distinction
664 +** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
665 +** operating systems natively supported by SQLite, only Mac OSX
666 +** cares about the difference.)
667 +*/
668 +#define SQLITE_SYNC_NORMAL 0x00002
669 +#define SQLITE_SYNC_FULL 0x00003
670 +#define SQLITE_SYNC_DATAONLY 0x00010
671 +
672 +/*
673 +** CAPI3REF: OS Interface Open File Handle
674 +**
675 +** An [sqlite3_file] object represents an open file in the
676 +** [sqlite3_vfs | OS interface layer]. Individual OS interface
677 +** implementations will
678 +** want to subclass this object by appending additional fields
679 +** for their own use. The pMethods entry is a pointer to an
680 +** [sqlite3_io_methods] object that defines methods for performing
681 +** I/O operations on the open file.
682 +*/
683 +typedef struct sqlite3_file sqlite3_file;
684 +struct sqlite3_file {
685 + const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
686 +};
687 +
688 +/*
689 +** CAPI3REF: OS Interface File Virtual Methods Object
690 +**
691 +** Every file opened by the [sqlite3_vfs.xOpen] method populates an
692 +** [sqlite3_file] object (or, more commonly, a subclass of the
693 +** [sqlite3_file] object) with a pointer to an instance of this object.
694 +** This object defines the methods used to perform various operations
695 +** against the open file represented by the [sqlite3_file] object.
696 +**
697 +** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element
698 +** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
699 +** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed. The
700 +** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
701 +** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
702 +** to NULL.
703 +**
704 +** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
705 +** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
706 +** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
707 +** flag may be ORed in to indicate that only the data of the file
708 +** and not its inode needs to be synced.
709 +**
710 +** The integer values to xLock() and xUnlock() are one of
711 +** <ul>
712 +** <li> [SQLITE_LOCK_NONE],
713 +** <li> [SQLITE_LOCK_SHARED],
714 +** <li> [SQLITE_LOCK_RESERVED],
715 +** <li> [SQLITE_LOCK_PENDING], or
716 +** <li> [SQLITE_LOCK_EXCLUSIVE].
717 +** </ul>
718 +** xLock() increases the lock. xUnlock() decreases the lock.
719 +** The xCheckReservedLock() method checks whether any database connection,
720 +** either in this process or in some other process, is holding a RESERVED,
721 +** PENDING, or EXCLUSIVE lock on the file. It returns true
722 +** if such a lock exists and false otherwise.
723 +**
724 +** The xFileControl() method is a generic interface that allows custom
725 +** VFS implementations to directly control an open file using the
726 +** [sqlite3_file_control()] interface. The second "op" argument is an
727 +** integer opcode. The third argument is a generic pointer intended to
728 +** point to a structure that may contain arguments or space in which to
729 +** write return values. Potential uses for xFileControl() might be
730 +** functions to enable blocking locks with timeouts, to change the
731 +** locking strategy (for example to use dot-file locks), to inquire
732 +** about the status of a lock, or to break stale locks. The SQLite
733 +** core reserves all opcodes less than 100 for its own use.
734 +** A [file control opcodes | list of opcodes] less than 100 is available.
735 +** Applications that define a custom xFileControl method should use opcodes
736 +** greater than 100 to avoid conflicts. VFS implementations should
737 +** return [SQLITE_NOTFOUND] for file control opcodes that they do not
738 +** recognize.
739 +**
740 +** The xSectorSize() method returns the sector size of the
741 +** device that underlies the file. The sector size is the
742 +** minimum write that can be performed without disturbing
743 +** other bytes in the file. The xDeviceCharacteristics()
744 +** method returns a bit vector describing behaviors of the
745 +** underlying device:
746 +**
747 +** <ul>
748 +** <li> [SQLITE_IOCAP_ATOMIC]
749 +** <li> [SQLITE_IOCAP_ATOMIC512]
750 +** <li> [SQLITE_IOCAP_ATOMIC1K]
751 +** <li> [SQLITE_IOCAP_ATOMIC2K]
752 +** <li> [SQLITE_IOCAP_ATOMIC4K]
753 +** <li> [SQLITE_IOCAP_ATOMIC8K]
754 +** <li> [SQLITE_IOCAP_ATOMIC16K]
755 +** <li> [SQLITE_IOCAP_ATOMIC32K]
756 +** <li> [SQLITE_IOCAP_ATOMIC64K]
757 +** <li> [SQLITE_IOCAP_SAFE_APPEND]
758 +** <li> [SQLITE_IOCAP_SEQUENTIAL]
759 +** <li> [SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN]
760 +** <li> [SQLITE_IOCAP_POWERSAFE_OVERWRITE]
761 +** <li> [SQLITE_IOCAP_IMMUTABLE]
762 +** <li> [SQLITE_IOCAP_BATCH_ATOMIC]
763 +** </ul>
764 +**
765 +** The SQLITE_IOCAP_ATOMIC property means that all writes of
766 +** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
767 +** mean that writes of blocks that are nnn bytes in size and
768 +** are aligned to an address which is an integer multiple of
769 +** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
770 +** that when data is appended to a file, the data is appended
771 +** first then the size of the file is extended, never the other
772 +** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
773 +** information is written to disk in the same order as calls
774 +** to xWrite().
775 +**
776 +** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
777 +** in the unread portions of the buffer with zeros. A VFS that
778 +** fails to zero-fill short reads might seem to work. However,
779 +** failure to zero-fill short reads will eventually lead to
780 +** database corruption.
781 +*/
782 +typedef struct sqlite3_io_methods sqlite3_io_methods;
783 +struct sqlite3_io_methods {
784 + int iVersion;
785 + int (*xClose)(sqlite3_file*);
786 + int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
787 + int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
788 + int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
789 + int (*xSync)(sqlite3_file*, int flags);
790 + int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
791 + int (*xLock)(sqlite3_file*, int);
792 + int (*xUnlock)(sqlite3_file*, int);
793 + int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
794 + int (*xFileControl)(sqlite3_file*, int op, void *pArg);
795 + int (*xSectorSize)(sqlite3_file*);
796 + int (*xDeviceCharacteristics)(sqlite3_file*);
797 + /* Methods above are valid for version 1 */
798 + int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
799 + int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
800 + void (*xShmBarrier)(sqlite3_file*);
801 + int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
802 + /* Methods above are valid for version 2 */
803 + int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
804 + int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
805 + /* Methods above are valid for version 3 */
806 + /* Additional methods may be added in future releases */
807 +};
808 +
809 +/*
810 +** CAPI3REF: Standard File Control Opcodes
811 +** KEYWORDS: {file control opcodes} {file control opcode}
812 +**
813 +** These integer constants are opcodes for the xFileControl method
814 +** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
815 +** interface.
816 +**
817 +** <ul>
818 +** <li>[[SQLITE_FCNTL_LOCKSTATE]]
819 +** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
820 +** opcode causes the xFileControl method to write the current state of
821 +** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
822 +** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
823 +** into an integer that the pArg argument points to. This capability
824 +** is used during testing and is only available when the SQLITE_TEST
825 +** compile-time option is used.
826 +**
827 +** <li>[[SQLITE_FCNTL_SIZE_HINT]]
828 +** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
829 +** layer a hint of how large the database file will grow to be during the
830 +** current transaction. This hint is not guaranteed to be accurate but it
831 +** is often close. The underlying VFS might choose to preallocate database
832 +** file space based on this hint in order to help writes to the database
833 +** file run faster.
834 +**
835 +** <li>[[SQLITE_FCNTL_SIZE_LIMIT]]
836 +** The [SQLITE_FCNTL_SIZE_LIMIT] opcode is used by in-memory VFS that
837 +** implements [sqlite3_deserialize()] to set an upper bound on the size
838 +** of the in-memory database. The argument is a pointer to a [sqlite3_int64].
839 +** If the integer pointed to is negative, then it is filled in with the
840 +** current limit. Otherwise the limit is set to the larger of the value
841 +** of the integer pointed to and the current database size. The integer
842 +** pointed to is set to the new limit.
843 +**
844 +** <li>[[SQLITE_FCNTL_CHUNK_SIZE]]
845 +** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
846 +** extends and truncates the database file in chunks of a size specified
847 +** by the user. The fourth argument to [sqlite3_file_control()] should
848 +** point to an integer (type int) containing the new chunk-size to use
849 +** for the nominated database. Allocating database file space in large
850 +** chunks (say 1MB at a time), may reduce file-system fragmentation and
851 +** improve performance on some systems.
852 +**
853 +** <li>[[SQLITE_FCNTL_FILE_POINTER]]
854 +** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
855 +** to the [sqlite3_file] object associated with a particular database
856 +** connection. See also [SQLITE_FCNTL_JOURNAL_POINTER].
857 +**
858 +** <li>[[SQLITE_FCNTL_JOURNAL_POINTER]]
859 +** The [SQLITE_FCNTL_JOURNAL_POINTER] opcode is used to obtain a pointer
860 +** to the [sqlite3_file] object associated with the journal file (either
861 +** the [rollback journal] or the [write-ahead log]) for a particular database
862 +** connection. See also [SQLITE_FCNTL_FILE_POINTER].
863 +**
864 +** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
865 +** No longer in use.
866 +**
867 +** <li>[[SQLITE_FCNTL_SYNC]]
868 +** The [SQLITE_FCNTL_SYNC] opcode is generated internally by SQLite and
869 +** sent to the VFS immediately before the xSync method is invoked on a
870 +** database file descriptor. Or, if the xSync method is not invoked
871 +** because the user has configured SQLite with
872 +** [PRAGMA synchronous | PRAGMA synchronous=OFF] it is invoked in place
873 +** of the xSync method. In most cases, the pointer argument passed with
874 +** this file-control is NULL. However, if the database file is being synced
875 +** as part of a multi-database commit, the argument points to a nul-terminated
876 +** string containing the transactions super-journal file name. VFSes that
877 +** do not need this signal should silently ignore this opcode. Applications
878 +** should not call [sqlite3_file_control()] with this opcode as doing so may
879 +** disrupt the operation of the specialized VFSes that do require it.
880 +**
881 +** <li>[[SQLITE_FCNTL_COMMIT_PHASETWO]]
882 +** The [SQLITE_FCNTL_COMMIT_PHASETWO] opcode is generated internally by SQLite
883 +** and sent to the VFS after a transaction has been committed immediately
884 +** but before the database is unlocked. VFSes that do not need this signal
885 +** should silently ignore this opcode. Applications should not call
886 +** [sqlite3_file_control()] with this opcode as doing so may disrupt the
887 +** operation of the specialized VFSes that do require it.
888 +**
889 +** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
890 +** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
891 +** retry counts and intervals for certain disk I/O operations for the
892 +** windows [VFS] in order to provide robustness in the presence of
893 +** anti-virus programs. By default, the windows VFS will retry file read,
894 +** file write, and file delete operations up to 10 times, with a delay
895 +** of 25 milliseconds before the first retry and with the delay increasing
896 +** by an additional 25 milliseconds with each subsequent retry. This
897 +** opcode allows these two values (10 retries and 25 milliseconds of delay)
898 +** to be adjusted. The values are changed for all database connections
899 +** within the same process. The argument is a pointer to an array of two
900 +** integers where the first integer is the new retry count and the second
901 +** integer is the delay. If either integer is negative, then the setting
902 +** is not changed but instead the prior value of that setting is written
903 +** into the array entry, allowing the current retry settings to be
904 +** interrogated. The zDbName parameter is ignored.
905 +**
906 +** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
907 +** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
908 +** persistent [WAL | Write Ahead Log] setting. By default, the auxiliary
909 +** write ahead log ([WAL file]) and shared memory
910 +** files used for transaction control
911 +** are automatically deleted when the latest connection to the database
912 +** closes. Setting persistent WAL mode causes those files to persist after
913 +** close. Persisting the files is useful when other processes that do not
914 +** have write permission on the directory containing the database file want
915 +** to read the database file, as the WAL and shared memory files must exist
916 +** in order for the database to be readable. The fourth parameter to
917 +** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
918 +** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
919 +** WAL mode. If the integer is -1, then it is overwritten with the current
920 +** WAL persistence setting.
921 +**
922 +** <li>[[SQLITE_FCNTL_POWERSAFE_OVERWRITE]]
923 +** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
924 +** persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting
925 +** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the
926 +** xDeviceCharacteristics methods. The fourth parameter to
927 +** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
928 +** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
929 +** mode. If the integer is -1, then it is overwritten with the current
930 +** zero-damage mode setting.
931 +**
932 +** <li>[[SQLITE_FCNTL_OVERWRITE]]
933 +** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
934 +** a write transaction to indicate that, unless it is rolled back for some
935 +** reason, the entire database file will be overwritten by the current
936 +** transaction. This is used by VACUUM operations.
937 +**
938 +** <li>[[SQLITE_FCNTL_VFSNAME]]
939 +** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
940 +** all [VFSes] in the VFS stack. The names are of all VFS shims and the
941 +** final bottom-level VFS are written into memory obtained from
942 +** [sqlite3_malloc()] and the result is stored in the char* variable
943 +** that the fourth parameter of [sqlite3_file_control()] points to.
944 +** The caller is responsible for freeing the memory when done. As with
945 +** all file-control actions, there is no guarantee that this will actually
946 +** do anything. Callers should initialize the char* variable to a NULL
947 +** pointer in case this file-control is not implemented. This file-control
948 +** is intended for diagnostic use only.
949 +**
950 +** <li>[[SQLITE_FCNTL_VFS_POINTER]]
951 +** ^The [SQLITE_FCNTL_VFS_POINTER] opcode finds a pointer to the top-level
952 +** [VFSes] currently in use. ^(The argument X in
953 +** sqlite3_file_control(db,SQLITE_FCNTL_VFS_POINTER,X) must be
954 +** of type "[sqlite3_vfs] **". This opcodes will set *X
955 +** to a pointer to the top-level VFS.)^
956 +** ^When there are multiple VFS shims in the stack, this opcode finds the
957 +** upper-most shim only.
958 +**
959 +** <li>[[SQLITE_FCNTL_PRAGMA]]
960 +** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
961 +** file control is sent to the open [sqlite3_file] object corresponding
962 +** to the database file to which the pragma statement refers. ^The argument
963 +** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
964 +** pointers to strings (char**) in which the second element of the array
965 +** is the name of the pragma and the third element is the argument to the
966 +** pragma or NULL if the pragma has no argument. ^The handler for an
967 +** [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element
968 +** of the char** argument point to a string obtained from [sqlite3_mprintf()]
969 +** or the equivalent and that string will become the result of the pragma or
970 +** the error message if the pragma fails. ^If the
971 +** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal
972 +** [PRAGMA] processing continues. ^If the [SQLITE_FCNTL_PRAGMA]
973 +** file control returns [SQLITE_OK], then the parser assumes that the
974 +** VFS has handled the PRAGMA itself and the parser generates a no-op
975 +** prepared statement if result string is NULL, or that returns a copy
976 +** of the result string if the string is non-NULL.
977 +** ^If the [SQLITE_FCNTL_PRAGMA] file control returns
978 +** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
979 +** that the VFS encountered an error while handling the [PRAGMA] and the
980 +** compilation of the PRAGMA fails with an error. ^The [SQLITE_FCNTL_PRAGMA]
981 +** file control occurs at the beginning of pragma statement analysis and so
982 +** it is able to override built-in [PRAGMA] statements.
983 +**
984 +** <li>[[SQLITE_FCNTL_BUSYHANDLER]]
985 +** ^The [SQLITE_FCNTL_BUSYHANDLER]
986 +** file-control may be invoked by SQLite on the database file handle
987 +** shortly after it is opened in order to provide a custom VFS with access
988 +** to the connection's busy-handler callback. The argument is of type (void**)
989 +** - an array of two (void *) values. The first (void *) actually points
990 +** to a function of type (int (*)(void *)). In order to invoke the connection's
991 +** busy-handler, this function should be invoked with the second (void *) in
992 +** the array as the only argument. If it returns non-zero, then the operation
993 +** should be retried. If it returns zero, the custom VFS should abandon the
994 +** current operation.
995 +**
996 +** <li>[[SQLITE_FCNTL_TEMPFILENAME]]
997 +** ^Applications can invoke the [SQLITE_FCNTL_TEMPFILENAME] file-control
998 +** to have SQLite generate a
999 +** temporary filename using the same algorithm that is followed to generate
1000 +** temporary filenames for TEMP tables and other internal uses. The
1001 +** argument should be a char** which will be filled with the filename
1002 +** written into memory obtained from [sqlite3_malloc()]. The caller should
1003 +** invoke [sqlite3_free()] on the result to avoid a memory leak.
1004 +**
1005 +** <li>[[SQLITE_FCNTL_MMAP_SIZE]]
1006 +** The [SQLITE_FCNTL_MMAP_SIZE] file control is used to query or set the
1007 +** maximum number of bytes that will be used for memory-mapped I/O.
1008 +** The argument is a pointer to a value of type sqlite3_int64 that
1009 +** is an advisory maximum number of bytes in the file to memory map. The
1010 +** pointer is overwritten with the old value. The limit is not changed if
1011 +** the value originally pointed to is negative, and so the current limit
1012 +** can be queried by passing in a pointer to a negative number. This
1013 +** file-control is used internally to implement [PRAGMA mmap_size].
1014 +**
1015 +** <li>[[SQLITE_FCNTL_TRACE]]
1016 +** The [SQLITE_FCNTL_TRACE] file control provides advisory information
1017 +** to the VFS about what the higher layers of the SQLite stack are doing.
1018 +** This file control is used by some VFS activity tracing [shims].
1019 +** The argument is a zero-terminated string. Higher layers in the
1020 +** SQLite stack may generate instances of this file control if
1021 +** the [SQLITE_USE_FCNTL_TRACE] compile-time option is enabled.
1022 +**
1023 +** <li>[[SQLITE_FCNTL_HAS_MOVED]]
1024 +** The [SQLITE_FCNTL_HAS_MOVED] file control interprets its argument as a
1025 +** pointer to an integer and it writes a boolean into that integer depending
1026 +** on whether or not the file has been renamed, moved, or deleted since it
1027 +** was first opened.
1028 +**
1029 +** <li>[[SQLITE_FCNTL_WIN32_GET_HANDLE]]
1030 +** The [SQLITE_FCNTL_WIN32_GET_HANDLE] opcode can be used to obtain the
1031 +** underlying native file handle associated with a file handle. This file
1032 +** control interprets its argument as a pointer to a native file handle and
1033 +** writes the resulting value there.
1034 +**
1035 +** <li>[[SQLITE_FCNTL_WIN32_SET_HANDLE]]
1036 +** The [SQLITE_FCNTL_WIN32_SET_HANDLE] opcode is used for debugging. This
1037 +** opcode causes the xFileControl method to swap the file handle with the one
1038 +** pointed to by the pArg argument. This capability is used during testing
1039 +** and only needs to be supported when SQLITE_TEST is defined.
1040 +**
1041 +** <li>[[SQLITE_FCNTL_WAL_BLOCK]]
1042 +** The [SQLITE_FCNTL_WAL_BLOCK] is a signal to the VFS layer that it might
1043 +** be advantageous to block on the next WAL lock if the lock is not immediately
1044 +** available. The WAL subsystem issues this signal during rare
1045 +** circumstances in order to fix a problem with priority inversion.
1046 +** Applications should <em>not</em> use this file-control.
1047 +**
1048 +** <li>[[SQLITE_FCNTL_ZIPVFS]]
1049 +** The [SQLITE_FCNTL_ZIPVFS] opcode is implemented by zipvfs only. All other
1050 +** VFS should return SQLITE_NOTFOUND for this opcode.
1051 +**
1052 +** <li>[[SQLITE_FCNTL_RBU]]
1053 +** The [SQLITE_FCNTL_RBU] opcode is implemented by the special VFS used by
1054 +** the RBU extension only. All other VFS should return SQLITE_NOTFOUND for
1055 +** this opcode.
1056 +**
1057 +** <li>[[SQLITE_FCNTL_BEGIN_ATOMIC_WRITE]]
1058 +** If the [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] opcode returns SQLITE_OK, then
1059 +** the file descriptor is placed in "batch write mode", which
1060 +** means all subsequent write operations will be deferred and done
1061 +** atomically at the next [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]. Systems
1062 +** that do not support batch atomic writes will return SQLITE_NOTFOUND.
1063 +** ^Following a successful SQLITE_FCNTL_BEGIN_ATOMIC_WRITE and prior to
1064 +** the closing [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] or
1065 +** [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE], SQLite will make
1066 +** no VFS interface calls on the same [sqlite3_file] file descriptor
1067 +** except for calls to the xWrite method and the xFileControl method
1068 +** with [SQLITE_FCNTL_SIZE_HINT].
1069 +**
1070 +** <li>[[SQLITE_FCNTL_COMMIT_ATOMIC_WRITE]]
1071 +** The [SQLITE_FCNTL_COMMIT_ATOMIC_WRITE] opcode causes all write
1072 +** operations since the previous successful call to
1073 +** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be performed atomically.
1074 +** This file control returns [SQLITE_OK] if and only if the writes were
1075 +** all performed successfully and have been committed to persistent storage.
1076 +** ^Regardless of whether or not it is successful, this file control takes
1077 +** the file descriptor out of batch write mode so that all subsequent
1078 +** write operations are independent.
1079 +** ^SQLite will never invoke SQLITE_FCNTL_COMMIT_ATOMIC_WRITE without
1080 +** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
1081 +**
1082 +** <li>[[SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE]]
1083 +** The [SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE] opcode causes all write
1084 +** operations since the previous successful call to
1085 +** [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE] to be rolled back.
1086 +** ^This file control takes the file descriptor out of batch write mode
1087 +** so that all subsequent write operations are independent.
1088 +** ^SQLite will never invoke SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE without
1089 +** a prior successful call to [SQLITE_FCNTL_BEGIN_ATOMIC_WRITE].
1090 +**
1091 +** <li>[[SQLITE_FCNTL_LOCK_TIMEOUT]]
1092 +** The [SQLITE_FCNTL_LOCK_TIMEOUT] opcode is used to configure a VFS
1093 +** to block for up to M milliseconds before failing when attempting to
1094 +** obtain a file lock using the xLock or xShmLock methods of the VFS.
1095 +** The parameter is a pointer to a 32-bit signed integer that contains
1096 +** the value that M is to be set to. Before returning, the 32-bit signed
1097 +** integer is overwritten with the previous value of M.
1098 +**
1099 +** <li>[[SQLITE_FCNTL_DATA_VERSION]]
1100 +** The [SQLITE_FCNTL_DATA_VERSION] opcode is used to detect changes to
1101 +** a database file. The argument is a pointer to a 32-bit unsigned integer.
1102 +** The "data version" for the pager is written into the pointer. The
1103 +** "data version" changes whenever any change occurs to the corresponding
1104 +** database file, either through SQL statements on the same database
1105 +** connection or through transactions committed by separate database
1106 +** connections possibly in other processes. The [sqlite3_total_changes()]
1107 +** interface can be used to find if any database on the connection has changed,
1108 +** but that interface responds to changes on TEMP as well as MAIN and does
1109 +** not provide a mechanism to detect changes to MAIN only. Also, the
1110 +** [sqlite3_total_changes()] interface responds to internal changes only and
1111 +** omits changes made by other database connections. The
1112 +** [PRAGMA data_version] command provides a mechanism to detect changes to
1113 +** a single attached database that occur due to other database connections,
1114 +** but omits changes implemented by the database connection on which it is
1115 +** called. This file control is the only mechanism to detect changes that
1116 +** happen either internally or externally and that are associated with
1117 +** a particular attached database.
1118 +**
1119 +** <li>[[SQLITE_FCNTL_CKPT_START]]
1120 +** The [SQLITE_FCNTL_CKPT_START] opcode is invoked from within a checkpoint
1121 +** in wal mode before the client starts to copy pages from the wal
1122 +** file to the database file.
1123 +**
1124 +** <li>[[SQLITE_FCNTL_CKPT_DONE]]
1125 +** The [SQLITE_FCNTL_CKPT_DONE] opcode is invoked from within a checkpoint
1126 +** in wal mode after the client has finished copying pages from the wal
1127 +** file to the database file, but before the *-shm file is updated to
1128 +** record the fact that the pages have been checkpointed.
1129 +** </ul>
1130 +*/
1131 +#define SQLITE_FCNTL_LOCKSTATE 1
1132 +#define SQLITE_FCNTL_GET_LOCKPROXYFILE 2
1133 +#define SQLITE_FCNTL_SET_LOCKPROXYFILE 3
1134 +#define SQLITE_FCNTL_LAST_ERRNO 4
1135 +#define SQLITE_FCNTL_SIZE_HINT 5
1136 +#define SQLITE_FCNTL_CHUNK_SIZE 6
1137 +#define SQLITE_FCNTL_FILE_POINTER 7
1138 +#define SQLITE_FCNTL_SYNC_OMITTED 8
1139 +#define SQLITE_FCNTL_WIN32_AV_RETRY 9
1140 +#define SQLITE_FCNTL_PERSIST_WAL 10
1141 +#define SQLITE_FCNTL_OVERWRITE 11
1142 +#define SQLITE_FCNTL_VFSNAME 12
1143 +#define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13
1144 +#define SQLITE_FCNTL_PRAGMA 14
1145 +#define SQLITE_FCNTL_BUSYHANDLER 15
1146 +#define SQLITE_FCNTL_TEMPFILENAME 16
1147 +#define SQLITE_FCNTL_MMAP_SIZE 18
1148 +#define SQLITE_FCNTL_TRACE 19
1149 +#define SQLITE_FCNTL_HAS_MOVED 20
1150 +#define SQLITE_FCNTL_SYNC 21
1151 +#define SQLITE_FCNTL_COMMIT_PHASETWO 22
1152 +#define SQLITE_FCNTL_WIN32_SET_HANDLE 23
1153 +#define SQLITE_FCNTL_WAL_BLOCK 24
1154 +#define SQLITE_FCNTL_ZIPVFS 25
1155 +#define SQLITE_FCNTL_RBU 26
1156 +#define SQLITE_FCNTL_VFS_POINTER 27
1157 +#define SQLITE_FCNTL_JOURNAL_POINTER 28
1158 +#define SQLITE_FCNTL_WIN32_GET_HANDLE 29
1159 +#define SQLITE_FCNTL_PDB 30
1160 +#define SQLITE_FCNTL_BEGIN_ATOMIC_WRITE 31
1161 +#define SQLITE_FCNTL_COMMIT_ATOMIC_WRITE 32
1162 +#define SQLITE_FCNTL_ROLLBACK_ATOMIC_WRITE 33
1163 +#define SQLITE_FCNTL_LOCK_TIMEOUT 34
1164 +#define SQLITE_FCNTL_DATA_VERSION 35
1165 +#define SQLITE_FCNTL_SIZE_LIMIT 36
1166 +#define SQLITE_FCNTL_CKPT_DONE 37
1167 +#define SQLITE_FCNTL_RESERVE_BYTES 38
1168 +#define SQLITE_FCNTL_CKPT_START 39
1169 +
1170 +/* deprecated names */
1171 +#define SQLITE_GET_LOCKPROXYFILE SQLITE_FCNTL_GET_LOCKPROXYFILE
1172 +#define SQLITE_SET_LOCKPROXYFILE SQLITE_FCNTL_SET_LOCKPROXYFILE
1173 +#define SQLITE_LAST_ERRNO SQLITE_FCNTL_LAST_ERRNO
1174 +
1175 +
1176 +/*
1177 +** CAPI3REF: Mutex Handle
1178 +**
1179 +** The mutex module within SQLite defines [sqlite3_mutex] to be an
1180 +** abstract type for a mutex object. The SQLite core never looks
1181 +** at the internal representation of an [sqlite3_mutex]. It only
1182 +** deals with pointers to the [sqlite3_mutex] object.
1183 +**
1184 +** Mutexes are created using [sqlite3_mutex_alloc()].
1185 +*/
1186 +typedef struct sqlite3_mutex sqlite3_mutex;
1187 +
1188 +/*
1189 +** CAPI3REF: Loadable Extension Thunk
1190 +**
1191 +** A pointer to the opaque sqlite3_api_routines structure is passed as
1192 +** the third parameter to entry points of [loadable extensions]. This
1193 +** structure must be typedefed in order to work around compiler warnings
1194 +** on some platforms.
1195 +*/
1196 +typedef struct sqlite3_api_routines sqlite3_api_routines;
1197 +
1198 +/*
1199 +** CAPI3REF: OS Interface Object
1200 +**
1201 +** An instance of the sqlite3_vfs object defines the interface between
1202 +** the SQLite core and the underlying operating system. The "vfs"
1203 +** in the name of the object stands for "virtual file system". See
1204 +** the [VFS | VFS documentation] for further information.
1205 +**
1206 +** The VFS interface is sometimes extended by adding new methods onto
1207 +** the end. Each time such an extension occurs, the iVersion field
1208 +** is incremented. The iVersion value started out as 1 in
1209 +** SQLite [version 3.5.0] on [dateof:3.5.0], then increased to 2
1210 +** with SQLite [version 3.7.0] on [dateof:3.7.0], and then increased
1211 +** to 3 with SQLite [version 3.7.6] on [dateof:3.7.6]. Additional fields
1212 +** may be appended to the sqlite3_vfs object and the iVersion value
1213 +** may increase again in future versions of SQLite.
1214 +** Note that due to an oversight, the structure
1215 +** of the sqlite3_vfs object changed in the transition from
1216 +** SQLite [version 3.5.9] to [version 3.6.0] on [dateof:3.6.0]
1217 +** and yet the iVersion field was not increased.
1218 +**
1219 +** The szOsFile field is the size of the subclassed [sqlite3_file]
1220 +** structure used by this VFS. mxPathname is the maximum length of
1221 +** a pathname in this VFS.
1222 +**
1223 +** Registered sqlite3_vfs objects are kept on a linked list formed by
1224 +** the pNext pointer. The [sqlite3_vfs_register()]
1225 +** and [sqlite3_vfs_unregister()] interfaces manage this list
1226 +** in a thread-safe way. The [sqlite3_vfs_find()] interface
1227 +** searches the list. Neither the application code nor the VFS
1228 +** implementation should use the pNext pointer.
1229 +**
1230 +** The pNext field is the only field in the sqlite3_vfs
1231 +** structure that SQLite will ever modify. SQLite will only access
1232 +** or modify this field while holding a particular static mutex.
1233 +** The application should never modify anything within the sqlite3_vfs
1234 +** object once the object has been registered.
1235 +**
1236 +** The zName field holds the name of the VFS module. The name must
1237 +** be unique across all VFS modules.
1238 +**
1239 +** [[sqlite3_vfs.xOpen]]
1240 +** ^SQLite guarantees that the zFilename parameter to xOpen
1241 +** is either a NULL pointer or string obtained
1242 +** from xFullPathname() with an optional suffix added.
1243 +** ^If a suffix is added to the zFilename parameter, it will
1244 +** consist of a single "-" character followed by no more than
1245 +** 11 alphanumeric and/or "-" characters.
1246 +** ^SQLite further guarantees that
1247 +** the string will be valid and unchanged until xClose() is
1248 +** called. Because of the previous sentence,
1249 +** the [sqlite3_file] can safely store a pointer to the
1250 +** filename if it needs to remember the filename for some reason.
1251 +** If the zFilename parameter to xOpen is a NULL pointer then xOpen
1252 +** must invent its own temporary name for the file. ^Whenever the
1253 +** xFilename parameter is NULL it will also be the case that the
1254 +** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
1255 +**
1256 +** The flags argument to xOpen() includes all bits set in
1257 +** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
1258 +** or [sqlite3_open16()] is used, then flags includes at least
1259 +** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
1260 +** If xOpen() opens a file read-only then it sets *pOutFlags to
1261 +** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set.
1262 +**
1263 +** ^(SQLite will also add one of the following flags to the xOpen()
1264 +** call, depending on the object being opened:
1265 +**
1266 +** <ul>
1267 +** <li> [SQLITE_OPEN_MAIN_DB]
1268 +** <li> [SQLITE_OPEN_MAIN_JOURNAL]
1269 +** <li> [SQLITE_OPEN_TEMP_DB]
1270 +** <li> [SQLITE_OPEN_TEMP_JOURNAL]
1271 +** <li> [SQLITE_OPEN_TRANSIENT_DB]
1272 +** <li> [SQLITE_OPEN_SUBJOURNAL]
1273 +** <li> [SQLITE_OPEN_SUPER_JOURNAL]
1274 +** <li> [SQLITE_OPEN_WAL]
1275 +** </ul>)^
1276 +**
1277 +** The file I/O implementation can use the object type flags to
1278 +** change the way it deals with files. For example, an application
1279 +** that does not care about crash recovery or rollback might make
1280 +** the open of a journal file a no-op. Writes to this journal would
1281 +** also be no-ops, and any attempt to read the journal would return
1282 +** SQLITE_IOERR. Or the implementation might recognize that a database
1283 +** file will be doing page-aligned sector reads and writes in a random
1284 +** order and set up its I/O subsystem accordingly.
1285 +**
1286 +** SQLite might also add one of the following flags to the xOpen method:
1287 +**
1288 +** <ul>
1289 +** <li> [SQLITE_OPEN_DELETEONCLOSE]
1290 +** <li> [SQLITE_OPEN_EXCLUSIVE]
1291 +** </ul>
1292 +**
1293 +** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
1294 +** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE]
1295 +** will be set for TEMP databases and their journals, transient
1296 +** databases, and subjournals.
1297 +**
1298 +** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
1299 +** with the [SQLITE_OPEN_CREATE] flag, which are both directly
1300 +** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
1301 +** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
1302 +** SQLITE_OPEN_CREATE, is used to indicate that file should always
1303 +** be created, and that it is an error if it already exists.
1304 +** It is <i>not</i> used to indicate the file should be opened
1305 +** for exclusive access.
1306 +**
1307 +** ^At least szOsFile bytes of memory are allocated by SQLite
1308 +** to hold the [sqlite3_file] structure passed as the third
1309 +** argument to xOpen. The xOpen method does not have to
1310 +** allocate the structure; it should just fill it in. Note that
1311 +** the xOpen method must set the sqlite3_file.pMethods to either
1312 +** a valid [sqlite3_io_methods] object or to NULL. xOpen must do
1313 +** this even if the open fails. SQLite expects that the sqlite3_file.pMethods
1314 +** element will be valid after xOpen returns regardless of the success
1315 +** or failure of the xOpen call.
1316 +**
1317 +** [[sqlite3_vfs.xAccess]]
1318 +** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
1319 +** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
1320 +** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
1321 +** to test whether a file is at least readable. The SQLITE_ACCESS_READ
1322 +** flag is never actually used and is not implemented in the built-in
1323 +** VFSes of SQLite. The file is named by the second argument and can be a
1324 +** directory. The xAccess method returns [SQLITE_OK] on success or some
1325 +** non-zero error code if there is an I/O error or if the name of
1326 +** the file given in the second argument is illegal. If SQLITE_OK
1327 +** is returned, then non-zero or zero is written into *pResOut to indicate
1328 +** whether or not the file is accessible.
1329 +**
1330 +** ^SQLite will always allocate at least mxPathname+1 bytes for the
1331 +** output buffer xFullPathname. The exact size of the output buffer
1332 +** is also passed as a parameter to both methods. If the output buffer
1333 +** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
1334 +** handled as a fatal error by SQLite, vfs implementations should endeavor
1335 +** to prevent this by setting mxPathname to a sufficiently large value.
1336 +**
1337 +** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
1338 +** interfaces are not strictly a part of the filesystem, but they are
1339 +** included in the VFS structure for completeness.
1340 +** The xRandomness() function attempts to return nBytes bytes
1341 +** of good-quality randomness into zOut. The return value is
1342 +** the actual number of bytes of randomness obtained.
1343 +** The xSleep() method causes the calling thread to sleep for at
1344 +** least the number of microseconds given. ^The xCurrentTime()
1345 +** method returns a Julian Day Number for the current date and time as
1346 +** a floating point value.
1347 +** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
1348 +** Day Number multiplied by 86400000 (the number of milliseconds in
1349 +** a 24-hour day).
1350 +** ^SQLite will use the xCurrentTimeInt64() method to get the current
1351 +** date and time if that method is available (if iVersion is 2 or
1352 +** greater and the function pointer is not NULL) and will fall back
1353 +** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
1354 +**
1355 +** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
1356 +** are not used by the SQLite core. These optional interfaces are provided
1357 +** by some VFSes to facilitate testing of the VFS code. By overriding
1358 +** system calls with functions under its control, a test program can
1359 +** simulate faults and error conditions that would otherwise be difficult
1360 +** or impossible to induce. The set of system calls that can be overridden
1361 +** varies from one VFS to another, and from one version of the same VFS to the
1362 +** next. Applications that use these interfaces must be prepared for any
1363 +** or all of these interfaces to be NULL or for their behavior to change
1364 +** from one release to the next. Applications must not attempt to access
1365 +** any of these methods if the iVersion of the VFS is less than 3.
1366 +*/
1367 +typedef struct sqlite3_vfs sqlite3_vfs;
1368 +typedef void (*sqlite3_syscall_ptr)(void);
1369 +struct sqlite3_vfs {
1370 + int iVersion; /* Structure version number (currently 3) */
1371 + int szOsFile; /* Size of subclassed sqlite3_file */
1372 + int mxPathname; /* Maximum file pathname length */
1373 + sqlite3_vfs *pNext; /* Next registered VFS */
1374 + const char *zName; /* Name of this virtual file system */
1375 + void *pAppData; /* Pointer to application-specific data */
1376 + int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
1377 + int flags, int *pOutFlags);
1378 + int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
1379 + int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
1380 + int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
1381 + void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
1382 + void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
1383 + void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
1384 + void (*xDlClose)(sqlite3_vfs*, void*);
1385 + int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
1386 + int (*xSleep)(sqlite3_vfs*, int microseconds);
1387 + int (*xCurrentTime)(sqlite3_vfs*, double*);
1388 + int (*xGetLastError)(sqlite3_vfs*, int, char *);
1389 + /*
1390 + ** The methods above are in version 1 of the sqlite_vfs object
1391 + ** definition. Those that follow are added in version 2 or later
1392 + */
1393 + int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
1394 + /*
1395 + ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
1396 + ** Those below are for version 3 and greater.
1397 + */
1398 + int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
1399 + sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
1400 + const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
1401 + /*
1402 + ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
1403 + ** New fields may be appended in future versions. The iVersion
1404 + ** value will increment whenever this happens.
1405 + */
1406 +};
1407 +
1408 +/*
1409 +** CAPI3REF: Flags for the xAccess VFS method
1410 +**
1411 +** These integer constants can be used as the third parameter to
1412 +** the xAccess method of an [sqlite3_vfs] object. They determine
1413 +** what kind of permissions the xAccess method is looking for.
1414 +** With SQLITE_ACCESS_EXISTS, the xAccess method
1415 +** simply checks whether the file exists.
1416 +** With SQLITE_ACCESS_READWRITE, the xAccess method
1417 +** checks whether the named directory is both readable and writable
1418 +** (in other words, if files can be added, removed, and renamed within
1419 +** the directory).
1420 +** The SQLITE_ACCESS_READWRITE constant is currently used only by the
1421 +** [temp_store_directory pragma], though this could change in a future
1422 +** release of SQLite.
1423 +** With SQLITE_ACCESS_READ, the xAccess method
1424 +** checks whether the file is readable. The SQLITE_ACCESS_READ constant is
1425 +** currently unused, though it might be used in a future release of
1426 +** SQLite.
1427 +*/
1428 +#define SQLITE_ACCESS_EXISTS 0
1429 +#define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */
1430 +#define SQLITE_ACCESS_READ 2 /* Unused */
1431 +
1432 +/*
1433 +** CAPI3REF: Flags for the xShmLock VFS method
1434 +**
1435 +** These integer constants define the various locking operations
1436 +** allowed by the xShmLock method of [sqlite3_io_methods]. The
1437 +** following are the only legal combinations of flags to the
1438 +** xShmLock method:
1439 +**
1440 +** <ul>
1441 +** <li> SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
1442 +** <li> SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
1443 +** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
1444 +** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
1445 +** </ul>
1446 +**
1447 +** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
1448 +** was given on the corresponding lock.
1449 +**
1450 +** The xShmLock method can transition between unlocked and SHARED or
1451 +** between unlocked and EXCLUSIVE. It cannot transition between SHARED
1452 +** and EXCLUSIVE.
1453 +*/
1454 +#define SQLITE_SHM_UNLOCK 1
1455 +#define SQLITE_SHM_LOCK 2
1456 +#define SQLITE_SHM_SHARED 4
1457 +#define SQLITE_SHM_EXCLUSIVE 8
1458 +
1459 +/*
1460 +** CAPI3REF: Maximum xShmLock index
1461 +**
1462 +** The xShmLock method on [sqlite3_io_methods] may use values
1463 +** between 0 and this upper bound as its "offset" argument.
1464 +** The SQLite core will never attempt to acquire or release a
1465 +** lock outside of this range
1466 +*/
1467 +#define SQLITE_SHM_NLOCK 8
1468 +
1469 +
1470 +/*
1471 +** CAPI3REF: Initialize The SQLite Library
1472 +**
1473 +** ^The sqlite3_initialize() routine initializes the
1474 +** SQLite library. ^The sqlite3_shutdown() routine
1475 +** deallocates any resources that were allocated by sqlite3_initialize().
1476 +** These routines are designed to aid in process initialization and
1477 +** shutdown on embedded systems. Workstation applications using
1478 +** SQLite normally do not need to invoke either of these routines.
1479 +**
1480 +** A call to sqlite3_initialize() is an "effective" call if it is
1481 +** the first time sqlite3_initialize() is invoked during the lifetime of
1482 +** the process, or if it is the first time sqlite3_initialize() is invoked
1483 +** following a call to sqlite3_shutdown(). ^(Only an effective call
1484 +** of sqlite3_initialize() does any initialization. All other calls
1485 +** are harmless no-ops.)^
1486 +**
1487 +** A call to sqlite3_shutdown() is an "effective" call if it is the first
1488 +** call to sqlite3_shutdown() since the last sqlite3_initialize(). ^(Only
1489 +** an effective call to sqlite3_shutdown() does any deinitialization.
1490 +** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
1491 +**
1492 +** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
1493 +** is not. The sqlite3_shutdown() interface must only be called from a
1494 +** single thread. All open [database connections] must be closed and all
1495 +** other SQLite resources must be deallocated prior to invoking
1496 +** sqlite3_shutdown().
1497 +**
1498 +** Among other things, ^sqlite3_initialize() will invoke
1499 +** sqlite3_os_init(). Similarly, ^sqlite3_shutdown()
1500 +** will invoke sqlite3_os_end().
1501 +**
1502 +** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
1503 +** ^If for some reason, sqlite3_initialize() is unable to initialize
1504 +** the library (perhaps it is unable to allocate a needed resource such
1505 +** as a mutex) it returns an [error code] other than [SQLITE_OK].
1506 +**
1507 +** ^The sqlite3_initialize() routine is called internally by many other
1508 +** SQLite interfaces so that an application usually does not need to
1509 +** invoke sqlite3_initialize() directly. For example, [sqlite3_open()]
1510 +** calls sqlite3_initialize() so the SQLite library will be automatically
1511 +** initialized when [sqlite3_open()] is called if it has not be initialized
1512 +** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
1513 +** compile-time option, then the automatic calls to sqlite3_initialize()
1514 +** are omitted and the application must call sqlite3_initialize() directly
1515 +** prior to using any other SQLite interface. For maximum portability,
1516 +** it is recommended that applications always invoke sqlite3_initialize()
1517 +** directly prior to using any other SQLite interface. Future releases
1518 +** of SQLite may require this. In other words, the behavior exhibited
1519 +** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
1520 +** default behavior in some future release of SQLite.
1521 +**
1522 +** The sqlite3_os_init() routine does operating-system specific
1523 +** initialization of the SQLite library. The sqlite3_os_end()
1524 +** routine undoes the effect of sqlite3_os_init(). Typical tasks
1525 +** performed by these routines include allocation or deallocation
1526 +** of static resources, initialization of global variables,
1527 +** setting up a default [sqlite3_vfs] module, or setting up
1528 +** a default configuration using [sqlite3_config()].
1529 +**
1530 +** The application should never invoke either sqlite3_os_init()
1531 +** or sqlite3_os_end() directly. The application should only invoke
1532 +** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init()
1533 +** interface is called automatically by sqlite3_initialize() and
1534 +** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
1535 +** implementations for sqlite3_os_init() and sqlite3_os_end()
1536 +** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
1537 +** When [custom builds | built for other platforms]
1538 +** (using the [SQLITE_OS_OTHER=1] compile-time
1539 +** option) the application must supply a suitable implementation for
1540 +** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
1541 +** implementation of sqlite3_os_init() or sqlite3_os_end()
1542 +** must return [SQLITE_OK] on success and some other [error code] upon
1543 +** failure.
1544 +*/
1545 +SQLITE_API int sqlite3_initialize(void);
1546 +SQLITE_API int sqlite3_shutdown(void);
1547 +SQLITE_API int sqlite3_os_init(void);
1548 +SQLITE_API int sqlite3_os_end(void);
1549 +
1550 +/*
1551 +** CAPI3REF: Configuring The SQLite Library
1552 +**
1553 +** The sqlite3_config() interface is used to make global configuration
1554 +** changes to SQLite in order to tune SQLite to the specific needs of
1555 +** the application. The default configuration is recommended for most
1556 +** applications and so this routine is usually not necessary. It is
1557 +** provided to support rare applications with unusual needs.
1558 +**
1559 +** <b>The sqlite3_config() interface is not threadsafe. The application
1560 +** must ensure that no other SQLite interfaces are invoked by other
1561 +** threads while sqlite3_config() is running.</b>
1562 +**
1563 +** The sqlite3_config() interface
1564 +** may only be invoked prior to library initialization using
1565 +** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
1566 +** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
1567 +** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
1568 +** Note, however, that ^sqlite3_config() can be called as part of the
1569 +** implementation of an application-defined [sqlite3_os_init()].
1570 +**
1571 +** The first argument to sqlite3_config() is an integer
1572 +** [configuration option] that determines
1573 +** what property of SQLite is to be configured. Subsequent arguments
1574 +** vary depending on the [configuration option]
1575 +** in the first argument.
1576 +**
1577 +** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
1578 +** ^If the option is unknown or SQLite is unable to set the option
1579 +** then this routine returns a non-zero [error code].
1580 +*/
1581 +SQLITE_API int sqlite3_config(int, ...);
1582 +
1583 +/*
1584 +** CAPI3REF: Configure database connections
1585 +** METHOD: sqlite3
1586 +**
1587 +** The sqlite3_db_config() interface is used to make configuration
1588 +** changes to a [database connection]. The interface is similar to
1589 +** [sqlite3_config()] except that the changes apply to a single
1590 +** [database connection] (specified in the first argument).
1591 +**
1592 +** The second argument to sqlite3_db_config(D,V,...) is the
1593 +** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code
1594 +** that indicates what aspect of the [database connection] is being configured.
1595 +** Subsequent arguments vary depending on the configuration verb.
1596 +**
1597 +** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
1598 +** the call is considered successful.
1599 +*/
1600 +SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
1601 +
1602 +/*
1603 +** CAPI3REF: Memory Allocation Routines
1604 +**
1605 +** An instance of this object defines the interface between SQLite
1606 +** and low-level memory allocation routines.
1607 +**
1608 +** This object is used in only one place in the SQLite interface.
1609 +** A pointer to an instance of this object is the argument to
1610 +** [sqlite3_config()] when the configuration option is
1611 +** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].
1612 +** By creating an instance of this object
1613 +** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
1614 +** during configuration, an application can specify an alternative
1615 +** memory allocation subsystem for SQLite to use for all of its
1616 +** dynamic memory needs.
1617 +**
1618 +** Note that SQLite comes with several [built-in memory allocators]
1619 +** that are perfectly adequate for the overwhelming majority of applications
1620 +** and that this object is only useful to a tiny minority of applications
1621 +** with specialized memory allocation requirements. This object is
1622 +** also used during testing of SQLite in order to specify an alternative
1623 +** memory allocator that simulates memory out-of-memory conditions in
1624 +** order to verify that SQLite recovers gracefully from such
1625 +** conditions.
1626 +**
1627 +** The xMalloc, xRealloc, and xFree methods must work like the
1628 +** malloc(), realloc() and free() functions from the standard C library.
1629 +** ^SQLite guarantees that the second argument to
1630 +** xRealloc is always a value returned by a prior call to xRoundup.
1631 +**
1632 +** xSize should return the allocated size of a memory allocation
1633 +** previously obtained from xMalloc or xRealloc. The allocated size
1634 +** is always at least as big as the requested size but may be larger.
1635 +**
1636 +** The xRoundup method returns what would be the allocated size of
1637 +** a memory allocation given a particular requested size. Most memory
1638 +** allocators round up memory allocations at least to the next multiple
1639 +** of 8. Some allocators round up to a larger multiple or to a power of 2.
1640 +** Every memory allocation request coming in through [sqlite3_malloc()]
1641 +** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0,
1642 +** that causes the corresponding memory allocation to fail.
1643 +**
1644 +** The xInit method initializes the memory allocator. For example,
1645 +** it might allocate any required mutexes or initialize internal data
1646 +** structures. The xShutdown method is invoked (indirectly) by
1647 +** [sqlite3_shutdown()] and should deallocate any resources acquired
1648 +** by xInit. The pAppData pointer is used as the only parameter to
1649 +** xInit and xShutdown.
1650 +**
1651 +** SQLite holds the [SQLITE_MUTEX_STATIC_MAIN] mutex when it invokes
1652 +** the xInit method, so the xInit method need not be threadsafe. The
1653 +** xShutdown method is only called from [sqlite3_shutdown()] so it does
1654 +** not need to be threadsafe either. For all other methods, SQLite
1655 +** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
1656 +** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
1657 +** it is by default) and so the methods are automatically serialized.
1658 +** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
1659 +** methods must be threadsafe or else make their own arrangements for
1660 +** serialization.
1661 +**
1662 +** SQLite will never invoke xInit() more than once without an intervening
1663 +** call to xShutdown().
1664 +*/
1665 +typedef struct sqlite3_mem_methods sqlite3_mem_methods;
1666 +struct sqlite3_mem_methods {
1667 + void *(*xMalloc)(int); /* Memory allocation function */
1668 + void (*xFree)(void*); /* Free a prior allocation */
1669 + void *(*xRealloc)(void*,int); /* Resize an allocation */
1670 + int (*xSize)(void*); /* Return the size of an allocation */
1671 + int (*xRoundup)(int); /* Round up request size to allocation size */
1672 + int (*xInit)(void*); /* Initialize the memory allocator */
1673 + void (*xShutdown)(void*); /* Deinitialize the memory allocator */
1674 + void *pAppData; /* Argument to xInit() and xShutdown() */
1675 +};
1676 +
1677 +/*
1678 +** CAPI3REF: Configuration Options
1679 +** KEYWORDS: {configuration option}
1680 +**
1681 +** These constants are the available integer configuration options that
1682 +** can be passed as the first argument to the [sqlite3_config()] interface.
1683 +**
1684 +** New configuration options may be added in future releases of SQLite.
1685 +** Existing configuration options might be discontinued. Applications
1686 +** should check the return code from [sqlite3_config()] to make sure that
1687 +** the call worked. The [sqlite3_config()] interface will return a
1688 +** non-zero [error code] if a discontinued or unsupported configuration option
1689 +** is invoked.
1690 +**
1691 +** <dl>
1692 +** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
1693 +** <dd>There are no arguments to this option. ^This option sets the
1694 +** [threading mode] to Single-thread. In other words, it disables
1695 +** all mutexing and puts SQLite into a mode where it can only be used
1696 +** by a single thread. ^If SQLite is compiled with
1697 +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1698 +** it is not possible to change the [threading mode] from its default
1699 +** value of Single-thread and so [sqlite3_config()] will return
1700 +** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
1701 +** configuration option.</dd>
1702 +**
1703 +** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
1704 +** <dd>There are no arguments to this option. ^This option sets the
1705 +** [threading mode] to Multi-thread. In other words, it disables
1706 +** mutexing on [database connection] and [prepared statement] objects.
1707 +** The application is responsible for serializing access to
1708 +** [database connections] and [prepared statements]. But other mutexes
1709 +** are enabled so that SQLite will be safe to use in a multi-threaded
1710 +** environment as long as no two threads attempt to use the same
1711 +** [database connection] at the same time. ^If SQLite is compiled with
1712 +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1713 +** it is not possible to set the Multi-thread [threading mode] and
1714 +** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1715 +** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
1716 +**
1717 +** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
1718 +** <dd>There are no arguments to this option. ^This option sets the
1719 +** [threading mode] to Serialized. In other words, this option enables
1720 +** all mutexes including the recursive
1721 +** mutexes on [database connection] and [prepared statement] objects.
1722 +** In this mode (which is the default when SQLite is compiled with
1723 +** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
1724 +** to [database connections] and [prepared statements] so that the
1725 +** application is free to use the same [database connection] or the
1726 +** same [prepared statement] in different threads at the same time.
1727 +** ^If SQLite is compiled with
1728 +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1729 +** it is not possible to set the Serialized [threading mode] and
1730 +** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1731 +** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
1732 +**
1733 +** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
1734 +** <dd> ^(The SQLITE_CONFIG_MALLOC option takes a single argument which is
1735 +** a pointer to an instance of the [sqlite3_mem_methods] structure.
1736 +** The argument specifies
1737 +** alternative low-level memory allocation routines to be used in place of
1738 +** the memory allocation routines built into SQLite.)^ ^SQLite makes
1739 +** its own private copy of the content of the [sqlite3_mem_methods] structure
1740 +** before the [sqlite3_config()] call returns.</dd>
1741 +**
1742 +** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
1743 +** <dd> ^(The SQLITE_CONFIG_GETMALLOC option takes a single argument which
1744 +** is a pointer to an instance of the [sqlite3_mem_methods] structure.
1745 +** The [sqlite3_mem_methods]
1746 +** structure is filled with the currently defined memory allocation routines.)^
1747 +** This option can be used to overload the default memory allocation
1748 +** routines with a wrapper that simulations memory allocation failure or
1749 +** tracks memory usage, for example. </dd>
1750 +**
1751 +** [[SQLITE_CONFIG_SMALL_MALLOC]] <dt>SQLITE_CONFIG_SMALL_MALLOC</dt>
1752 +** <dd> ^The SQLITE_CONFIG_SMALL_MALLOC option takes single argument of
1753 +** type int, interpreted as a boolean, which if true provides a hint to
1754 +** SQLite that it should avoid large memory allocations if possible.
1755 +** SQLite will run faster if it is free to make large memory allocations,
1756 +** but some application might prefer to run slower in exchange for
1757 +** guarantees about memory fragmentation that are possible if large
1758 +** allocations are avoided. This hint is normally off.
1759 +** </dd>
1760 +**
1761 +** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
1762 +** <dd> ^The SQLITE_CONFIG_MEMSTATUS option takes single argument of type int,
1763 +** interpreted as a boolean, which enables or disables the collection of
1764 +** memory allocation statistics. ^(When memory allocation statistics are
1765 +** disabled, the following SQLite interfaces become non-operational:
1766 +** <ul>
1767 +** <li> [sqlite3_hard_heap_limit64()]
1768 +** <li> [sqlite3_memory_used()]
1769 +** <li> [sqlite3_memory_highwater()]
1770 +** <li> [sqlite3_soft_heap_limit64()]
1771 +** <li> [sqlite3_status64()]
1772 +** </ul>)^
1773 +** ^Memory allocation statistics are enabled by default unless SQLite is
1774 +** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
1775 +** allocation statistics are disabled by default.
1776 +** </dd>
1777 +**
1778 +** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
1779 +** <dd> The SQLITE_CONFIG_SCRATCH option is no longer used.
1780 +** </dd>
1781 +**
1782 +** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
1783 +** <dd> ^The SQLITE_CONFIG_PAGECACHE option specifies a memory pool
1784 +** that SQLite can use for the database page cache with the default page
1785 +** cache implementation.
1786 +** This configuration option is a no-op if an application-defined page
1787 +** cache implementation is loaded using the [SQLITE_CONFIG_PCACHE2].
1788 +** ^There are three arguments to SQLITE_CONFIG_PAGECACHE: A pointer to
1789 +** 8-byte aligned memory (pMem), the size of each page cache line (sz),
1790 +** and the number of cache lines (N).
1791 +** The sz argument should be the size of the largest database page
1792 +** (a power of two between 512 and 65536) plus some extra bytes for each
1793 +** page header. ^The number of extra bytes needed by the page header
1794 +** can be determined using [SQLITE_CONFIG_PCACHE_HDRSZ].
1795 +** ^It is harmless, apart from the wasted memory,
1796 +** for the sz parameter to be larger than necessary. The pMem
1797 +** argument must be either a NULL pointer or a pointer to an 8-byte
1798 +** aligned block of memory of at least sz*N bytes, otherwise
1799 +** subsequent behavior is undefined.
1800 +** ^When pMem is not NULL, SQLite will strive to use the memory provided
1801 +** to satisfy page cache needs, falling back to [sqlite3_malloc()] if
1802 +** a page cache line is larger than sz bytes or if all of the pMem buffer
1803 +** is exhausted.
1804 +** ^If pMem is NULL and N is non-zero, then each database connection
1805 +** does an initial bulk allocation for page cache memory
1806 +** from [sqlite3_malloc()] sufficient for N cache lines if N is positive or
1807 +** of -1024*N bytes if N is negative, . ^If additional
1808 +** page cache memory is needed beyond what is provided by the initial
1809 +** allocation, then SQLite goes to [sqlite3_malloc()] separately for each
1810 +** additional cache line. </dd>
1811 +**
1812 +** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
1813 +** <dd> ^The SQLITE_CONFIG_HEAP option specifies a static memory buffer
1814 +** that SQLite will use for all of its dynamic memory allocation needs
1815 +** beyond those provided for by [SQLITE_CONFIG_PAGECACHE].
1816 +** ^The SQLITE_CONFIG_HEAP option is only available if SQLite is compiled
1817 +** with either [SQLITE_ENABLE_MEMSYS3] or [SQLITE_ENABLE_MEMSYS5] and returns
1818 +** [SQLITE_ERROR] if invoked otherwise.
1819 +** ^There are three arguments to SQLITE_CONFIG_HEAP:
1820 +** An 8-byte aligned pointer to the memory,
1821 +** the number of bytes in the memory buffer, and the minimum allocation size.
1822 +** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
1823 +** to using its default memory allocator (the system malloc() implementation),
1824 +** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the
1825 +** memory pointer is not NULL then the alternative memory
1826 +** allocator is engaged to handle all of SQLites memory allocation needs.
1827 +** The first pointer (the memory pointer) must be aligned to an 8-byte
1828 +** boundary or subsequent behavior of SQLite will be undefined.
1829 +** The minimum allocation size is capped at 2**12. Reasonable values
1830 +** for the minimum allocation size are 2**5 through 2**8.</dd>
1831 +**
1832 +** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
1833 +** <dd> ^(The SQLITE_CONFIG_MUTEX option takes a single argument which is a
1834 +** pointer to an instance of the [sqlite3_mutex_methods] structure.
1835 +** The argument specifies alternative low-level mutex routines to be used
1836 +** in place the mutex routines built into SQLite.)^ ^SQLite makes a copy of
1837 +** the content of the [sqlite3_mutex_methods] structure before the call to
1838 +** [sqlite3_config()] returns. ^If SQLite is compiled with
1839 +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1840 +** the entire mutexing subsystem is omitted from the build and hence calls to
1841 +** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
1842 +** return [SQLITE_ERROR].</dd>
1843 +**
1844 +** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
1845 +** <dd> ^(The SQLITE_CONFIG_GETMUTEX option takes a single argument which
1846 +** is a pointer to an instance of the [sqlite3_mutex_methods] structure. The
1847 +** [sqlite3_mutex_methods]
1848 +** structure is filled with the currently defined mutex routines.)^
1849 +** This option can be used to overload the default mutex allocation
1850 +** routines with a wrapper used to track mutex usage for performance
1851 +** profiling or testing, for example. ^If SQLite is compiled with
1852 +** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1853 +** the entire mutexing subsystem is omitted from the build and hence calls to
1854 +** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
1855 +** return [SQLITE_ERROR].</dd>
1856 +**
1857 +** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
1858 +** <dd> ^(The SQLITE_CONFIG_LOOKASIDE option takes two arguments that determine
1859 +** the default size of lookaside memory on each [database connection].
1860 +** The first argument is the
1861 +** size of each lookaside buffer slot and the second is the number of
1862 +** slots allocated to each database connection.)^ ^(SQLITE_CONFIG_LOOKASIDE
1863 +** sets the <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
1864 +** option to [sqlite3_db_config()] can be used to change the lookaside
1865 +** configuration on individual connections.)^ </dd>
1866 +**
1867 +** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
1868 +** <dd> ^(The SQLITE_CONFIG_PCACHE2 option takes a single argument which is
1869 +** a pointer to an [sqlite3_pcache_methods2] object. This object specifies
1870 +** the interface to a custom page cache implementation.)^
1871 +** ^SQLite makes a copy of the [sqlite3_pcache_methods2] object.</dd>
1872 +**
1873 +** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
1874 +** <dd> ^(The SQLITE_CONFIG_GETPCACHE2 option takes a single argument which
1875 +** is a pointer to an [sqlite3_pcache_methods2] object. SQLite copies of
1876 +** the current page cache implementation into that object.)^ </dd>
1877 +**
1878 +** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
1879 +** <dd> The SQLITE_CONFIG_LOG option is used to configure the SQLite
1880 +** global [error log].
1881 +** (^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
1882 +** function with a call signature of void(*)(void*,int,const char*),
1883 +** and a pointer to void. ^If the function pointer is not NULL, it is
1884 +** invoked by [sqlite3_log()] to process each logging event. ^If the
1885 +** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
1886 +** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
1887 +** passed through as the first parameter to the application-defined logger
1888 +** function whenever that function is invoked. ^The second parameter to
1889 +** the logger function is a copy of the first parameter to the corresponding
1890 +** [sqlite3_log()] call and is intended to be a [result code] or an
1891 +** [extended result code]. ^The third parameter passed to the logger is
1892 +** log message after formatting via [sqlite3_snprintf()].
1893 +** The SQLite logging interface is not reentrant; the logger function
1894 +** supplied by the application must not invoke any SQLite interface.
1895 +** In a multi-threaded application, the application-defined logger
1896 +** function must be threadsafe. </dd>
1897 +**
1898 +** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
1899 +** <dd>^(The SQLITE_CONFIG_URI option takes a single argument of type int.
1900 +** If non-zero, then URI handling is globally enabled. If the parameter is zero,
1901 +** then URI handling is globally disabled.)^ ^If URI handling is globally
1902 +** enabled, all filenames passed to [sqlite3_open()], [sqlite3_open_v2()],
1903 +** [sqlite3_open16()] or
1904 +** specified as part of [ATTACH] commands are interpreted as URIs, regardless
1905 +** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
1906 +** connection is opened. ^If it is globally disabled, filenames are
1907 +** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
1908 +** database connection is opened. ^(By default, URI handling is globally
1909 +** disabled. The default value may be changed by compiling with the
1910 +** [SQLITE_USE_URI] symbol defined.)^
1911 +**
1912 +** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
1913 +** <dd>^The SQLITE_CONFIG_COVERING_INDEX_SCAN option takes a single integer
1914 +** argument which is interpreted as a boolean in order to enable or disable
1915 +** the use of covering indices for full table scans in the query optimizer.
1916 +** ^The default setting is determined
1917 +** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
1918 +** if that compile-time option is omitted.
1919 +** The ability to disable the use of covering indices for full table scans
1920 +** is because some incorrectly coded legacy applications might malfunction
1921 +** when the optimization is enabled. Providing the ability to
1922 +** disable the optimization allows the older, buggy application code to work
1923 +** without change even with newer versions of SQLite.
1924 +**
1925 +** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]
1926 +** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
1927 +** <dd> These options are obsolete and should not be used by new code.
1928 +** They are retained for backwards compatibility but are now no-ops.
1929 +** </dd>
1930 +**
1931 +** [[SQLITE_CONFIG_SQLLOG]]
1932 +** <dt>SQLITE_CONFIG_SQLLOG
1933 +** <dd>This option is only available if sqlite is compiled with the
1934 +** [SQLITE_ENABLE_SQLLOG] pre-processor macro defined. The first argument should
1935 +** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
1936 +** The second should be of type (void*). The callback is invoked by the library
1937 +** in three separate circumstances, identified by the value passed as the
1938 +** fourth parameter. If the fourth parameter is 0, then the database connection
1939 +** passed as the second argument has just been opened. The third argument
1940 +** points to a buffer containing the name of the main database file. If the
1941 +** fourth parameter is 1, then the SQL statement that the third parameter
1942 +** points to has just been executed. Or, if the fourth parameter is 2, then
1943 +** the connection being passed as the second parameter is being closed. The
1944 +** third parameter is passed NULL In this case. An example of using this
1945 +** configuration option can be seen in the "test_sqllog.c" source file in
1946 +** the canonical SQLite source tree.</dd>
1947 +**
1948 +** [[SQLITE_CONFIG_MMAP_SIZE]]
1949 +** <dt>SQLITE_CONFIG_MMAP_SIZE
1950 +** <dd>^SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer (sqlite3_int64) values
1951 +** that are the default mmap size limit (the default setting for
1952 +** [PRAGMA mmap_size]) and the maximum allowed mmap size limit.
1953 +** ^The default setting can be overridden by each database connection using
1954 +** either the [PRAGMA mmap_size] command, or by using the
1955 +** [SQLITE_FCNTL_MMAP_SIZE] file control. ^(The maximum allowed mmap size
1956 +** will be silently truncated if necessary so that it does not exceed the
1957 +** compile-time maximum mmap size set by the
1958 +** [SQLITE_MAX_MMAP_SIZE] compile-time option.)^
1959 +** ^If either argument to this option is negative, then that argument is
1960 +** changed to its compile-time default.
1961 +**
1962 +** [[SQLITE_CONFIG_WIN32_HEAPSIZE]]
1963 +** <dt>SQLITE_CONFIG_WIN32_HEAPSIZE
1964 +** <dd>^The SQLITE_CONFIG_WIN32_HEAPSIZE option is only available if SQLite is
1965 +** compiled for Windows with the [SQLITE_WIN32_MALLOC] pre-processor macro
1966 +** defined. ^SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
1967 +** that specifies the maximum size of the created heap.
1968 +**
1969 +** [[SQLITE_CONFIG_PCACHE_HDRSZ]]
1970 +** <dt>SQLITE_CONFIG_PCACHE_HDRSZ
1971 +** <dd>^The SQLITE_CONFIG_PCACHE_HDRSZ option takes a single parameter which
1972 +** is a pointer to an integer and writes into that integer the number of extra
1973 +** bytes per page required for each page in [SQLITE_CONFIG_PAGECACHE].
1974 +** The amount of extra space required can change depending on the compiler,
1975 +** target platform, and SQLite version.
1976 +**
1977 +** [[SQLITE_CONFIG_PMASZ]]
1978 +** <dt>SQLITE_CONFIG_PMASZ
1979 +** <dd>^The SQLITE_CONFIG_PMASZ option takes a single parameter which
1980 +** is an unsigned integer and sets the "Minimum PMA Size" for the multithreaded
1981 +** sorter to that integer. The default minimum PMA Size is set by the
1982 +** [SQLITE_SORTER_PMASZ] compile-time option. New threads are launched
1983 +** to help with sort operations when multithreaded sorting
1984 +** is enabled (using the [PRAGMA threads] command) and the amount of content
1985 +** to be sorted exceeds the page size times the minimum of the
1986 +** [PRAGMA cache_size] setting and this value.
1987 +**
1988 +** [[SQLITE_CONFIG_STMTJRNL_SPILL]]
1989 +** <dt>SQLITE_CONFIG_STMTJRNL_SPILL
1990 +** <dd>^The SQLITE_CONFIG_STMTJRNL_SPILL option takes a single parameter which
1991 +** becomes the [statement journal] spill-to-disk threshold.
1992 +** [Statement journals] are held in memory until their size (in bytes)
1993 +** exceeds this threshold, at which point they are written to disk.
1994 +** Or if the threshold is -1, statement journals are always held
1995 +** exclusively in memory.
1996 +** Since many statement journals never become large, setting the spill
1997 +** threshold to a value such as 64KiB can greatly reduce the amount of
1998 +** I/O required to support statement rollback.
1999 +** The default value for this setting is controlled by the
2000 +** [SQLITE_STMTJRNL_SPILL] compile-time option.
2001 +**
2002 +** [[SQLITE_CONFIG_SORTERREF_SIZE]]
2003 +** <dt>SQLITE_CONFIG_SORTERREF_SIZE
2004 +** <dd>The SQLITE_CONFIG_SORTERREF_SIZE option accepts a single parameter
2005 +** of type (int) - the new value of the sorter-reference size threshold.
2006 +** Usually, when SQLite uses an external sort to order records according
2007 +** to an ORDER BY clause, all fields required by the caller are present in the
2008 +** sorted records. However, if SQLite determines based on the declared type
2009 +** of a table column that its values are likely to be very large - larger
2010 +** than the configured sorter-reference size threshold - then a reference
2011 +** is stored in each sorted record and the required column values loaded
2012 +** from the database as records are returned in sorted order. The default
2013 +** value for this option is to never use this optimization. Specifying a
2014 +** negative value for this option restores the default behaviour.
2015 +** This option is only available if SQLite is compiled with the
2016 +** [SQLITE_ENABLE_SORTER_REFERENCES] compile-time option.
2017 +**
2018 +** [[SQLITE_CONFIG_MEMDB_MAXSIZE]]
2019 +** <dt>SQLITE_CONFIG_MEMDB_MAXSIZE
2020 +** <dd>The SQLITE_CONFIG_MEMDB_MAXSIZE option accepts a single parameter
2021 +** [sqlite3_int64] parameter which is the default maximum size for an in-memory
2022 +** database created using [sqlite3_deserialize()]. This default maximum
2023 +** size can be adjusted up or down for individual databases using the
2024 +** [SQLITE_FCNTL_SIZE_LIMIT] [sqlite3_file_control|file-control]. If this
2025 +** configuration setting is never used, then the default maximum is determined
2026 +** by the [SQLITE_MEMDB_DEFAULT_MAXSIZE] compile-time option. If that
2027 +** compile-time option is not set, then the default maximum is 1073741824.
2028 +** </dl>
2029 +*/
2030 +#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
2031 +#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
2032 +#define SQLITE_CONFIG_SERIALIZED 3 /* nil */
2033 +#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
2034 +#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
2035 +#define SQLITE_CONFIG_SCRATCH 6 /* No longer used */
2036 +#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
2037 +#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
2038 +#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
2039 +#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
2040 +#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
2041 +/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
2042 +#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
2043 +#define SQLITE_CONFIG_PCACHE 14 /* no-op */
2044 +#define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
2045 +#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
2046 +#define SQLITE_CONFIG_URI 17 /* int */
2047 +#define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */
2048 +#define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
2049 +#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */
2050 +#define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
2051 +#define SQLITE_CONFIG_MMAP_SIZE 22 /* sqlite3_int64, sqlite3_int64 */
2052 +#define SQLITE_CONFIG_WIN32_HEAPSIZE 23 /* int nByte */
2053 +#define SQLITE_CONFIG_PCACHE_HDRSZ 24 /* int *psz */
2054 +#define SQLITE_CONFIG_PMASZ 25 /* unsigned int szPma */
2055 +#define SQLITE_CONFIG_STMTJRNL_SPILL 26 /* int nByte */
2056 +#define SQLITE_CONFIG_SMALL_MALLOC 27 /* boolean */
2057 +#define SQLITE_CONFIG_SORTERREF_SIZE 28 /* int nByte */
2058 +#define SQLITE_CONFIG_MEMDB_MAXSIZE 29 /* sqlite3_int64 */
2059 +
2060 +/*
2061 +** CAPI3REF: Database Connection Configuration Options
2062 +**
2063 +** These constants are the available integer configuration options that
2064 +** can be passed as the second argument to the [sqlite3_db_config()] interface.
2065 +**
2066 +** New configuration options may be added in future releases of SQLite.
2067 +** Existing configuration options might be discontinued. Applications
2068 +** should check the return code from [sqlite3_db_config()] to make sure that
2069 +** the call worked. ^The [sqlite3_db_config()] interface will return a
2070 +** non-zero [error code] if a discontinued or unsupported configuration option
2071 +** is invoked.
2072 +**
2073 +** <dl>
2074 +** [[SQLITE_DBCONFIG_LOOKASIDE]]
2075 +** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
2076 +** <dd> ^This option takes three additional arguments that determine the
2077 +** [lookaside memory allocator] configuration for the [database connection].
2078 +** ^The first argument (the third parameter to [sqlite3_db_config()] is a
2079 +** pointer to a memory buffer to use for lookaside memory.
2080 +** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
2081 +** may be NULL in which case SQLite will allocate the
2082 +** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
2083 +** size of each lookaside buffer slot. ^The third argument is the number of
2084 +** slots. The size of the buffer in the first argument must be greater than
2085 +** or equal to the product of the second and third arguments. The buffer
2086 +** must be aligned to an 8-byte boundary. ^If the second argument to
2087 +** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
2088 +** rounded down to the next smaller multiple of 8. ^(The lookaside memory
2089 +** configuration for a database connection can only be changed when that
2090 +** connection is not currently using lookaside memory, or in other words
2091 +** when the "current value" returned by
2092 +** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
2093 +** Any attempt to change the lookaside memory configuration when lookaside
2094 +** memory is in use leaves the configuration unchanged and returns
2095 +** [SQLITE_BUSY].)^</dd>
2096 +**
2097 +** [[SQLITE_DBCONFIG_ENABLE_FKEY]]
2098 +** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
2099 +** <dd> ^This option is used to enable or disable the enforcement of
2100 +** [foreign key constraints]. There should be two additional arguments.
2101 +** The first argument is an integer which is 0 to disable FK enforcement,
2102 +** positive to enable FK enforcement or negative to leave FK enforcement
2103 +** unchanged. The second parameter is a pointer to an integer into which
2104 +** is written 0 or 1 to indicate whether FK enforcement is off or on
2105 +** following this call. The second parameter may be a NULL pointer, in
2106 +** which case the FK enforcement setting is not reported back. </dd>
2107 +**
2108 +** [[SQLITE_DBCONFIG_ENABLE_TRIGGER]]
2109 +** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
2110 +** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
2111 +** There should be two additional arguments.
2112 +** The first argument is an integer which is 0 to disable triggers,
2113 +** positive to enable triggers or negative to leave the setting unchanged.
2114 +** The second parameter is a pointer to an integer into which
2115 +** is written 0 or 1 to indicate whether triggers are disabled or enabled
2116 +** following this call. The second parameter may be a NULL pointer, in
2117 +** which case the trigger setting is not reported back. </dd>
2118 +**
2119 +** [[SQLITE_DBCONFIG_ENABLE_VIEW]]
2120 +** <dt>SQLITE_DBCONFIG_ENABLE_VIEW</dt>
2121 +** <dd> ^This option is used to enable or disable [CREATE VIEW | views].
2122 +** There should be two additional arguments.
2123 +** The first argument is an integer which is 0 to disable views,
2124 +** positive to enable views or negative to leave the setting unchanged.
2125 +** The second parameter is a pointer to an integer into which
2126 +** is written 0 or 1 to indicate whether views are disabled or enabled
2127 +** following this call. The second parameter may be a NULL pointer, in
2128 +** which case the view setting is not reported back. </dd>
2129 +**
2130 +** [[SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER]]
2131 +** <dt>SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER</dt>
2132 +** <dd> ^This option is used to enable or disable the
2133 +** [fts3_tokenizer()] function which is part of the
2134 +** [FTS3] full-text search engine extension.
2135 +** There should be two additional arguments.
2136 +** The first argument is an integer which is 0 to disable fts3_tokenizer() or
2137 +** positive to enable fts3_tokenizer() or negative to leave the setting
2138 +** unchanged.
2139 +** The second parameter is a pointer to an integer into which
2140 +** is written 0 or 1 to indicate whether fts3_tokenizer is disabled or enabled
2141 +** following this call. The second parameter may be a NULL pointer, in
2142 +** which case the new setting is not reported back. </dd>
2143 +**
2144 +** [[SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION]]
2145 +** <dt>SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION</dt>
2146 +** <dd> ^This option is used to enable or disable the [sqlite3_load_extension()]
2147 +** interface independently of the [load_extension()] SQL function.
2148 +** The [sqlite3_enable_load_extension()] API enables or disables both the
2149 +** C-API [sqlite3_load_extension()] and the SQL function [load_extension()].
2150 +** There should be two additional arguments.
2151 +** When the first argument to this interface is 1, then only the C-API is
2152 +** enabled and the SQL function remains disabled. If the first argument to
2153 +** this interface is 0, then both the C-API and the SQL function are disabled.
2154 +** If the first argument is -1, then no changes are made to state of either the
2155 +** C-API or the SQL function.
2156 +** The second parameter is a pointer to an integer into which
2157 +** is written 0 or 1 to indicate whether [sqlite3_load_extension()] interface
2158 +** is disabled or enabled following this call. The second parameter may
2159 +** be a NULL pointer, in which case the new setting is not reported back.
2160 +** </dd>
2161 +**
2162 +** [[SQLITE_DBCONFIG_MAINDBNAME]] <dt>SQLITE_DBCONFIG_MAINDBNAME</dt>
2163 +** <dd> ^This option is used to change the name of the "main" database
2164 +** schema. ^The sole argument is a pointer to a constant UTF8 string
2165 +** which will become the new schema name in place of "main". ^SQLite
2166 +** does not make a copy of the new main schema name string, so the application
2167 +** must ensure that the argument passed into this DBCONFIG option is unchanged
2168 +** until after the database connection closes.
2169 +** </dd>
2170 +**
2171 +** [[SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE]]
2172 +** <dt>SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE</dt>
2173 +** <dd> Usually, when a database in wal mode is closed or detached from a
2174 +** database handle, SQLite checks if this will mean that there are now no
2175 +** connections at all to the database. If so, it performs a checkpoint
2176 +** operation before closing the connection. This option may be used to
2177 +** override this behaviour. The first parameter passed to this operation
2178 +** is an integer - positive to disable checkpoints-on-close, or zero (the
2179 +** default) to enable them, and negative to leave the setting unchanged.
2180 +** The second parameter is a pointer to an integer
2181 +** into which is written 0 or 1 to indicate whether checkpoints-on-close
2182 +** have been disabled - 0 if they are not disabled, 1 if they are.
2183 +** </dd>
2184 +**
2185 +** [[SQLITE_DBCONFIG_ENABLE_QPSG]] <dt>SQLITE_DBCONFIG_ENABLE_QPSG</dt>
2186 +** <dd>^(The SQLITE_DBCONFIG_ENABLE_QPSG option activates or deactivates
2187 +** the [query planner stability guarantee] (QPSG). When the QPSG is active,
2188 +** a single SQL query statement will always use the same algorithm regardless
2189 +** of values of [bound parameters].)^ The QPSG disables some query optimizations
2190 +** that look at the values of bound parameters, which can make some queries
2191 +** slower. But the QPSG has the advantage of more predictable behavior. With
2192 +** the QPSG active, SQLite will always use the same query plan in the field as
2193 +** was used during testing in the lab.
2194 +** The first argument to this setting is an integer which is 0 to disable
2195 +** the QPSG, positive to enable QPSG, or negative to leave the setting
2196 +** unchanged. The second parameter is a pointer to an integer into which
2197 +** is written 0 or 1 to indicate whether the QPSG is disabled or enabled
2198 +** following this call.
2199 +** </dd>
2200 +**
2201 +** [[SQLITE_DBCONFIG_TRIGGER_EQP]] <dt>SQLITE_DBCONFIG_TRIGGER_EQP</dt>
2202 +** <dd> By default, the output of EXPLAIN QUERY PLAN commands does not
2203 +** include output for any operations performed by trigger programs. This
2204 +** option is used to set or clear (the default) a flag that governs this
2205 +** behavior. The first parameter passed to this operation is an integer -
2206 +** positive to enable output for trigger programs, or zero to disable it,
2207 +** or negative to leave the setting unchanged.
2208 +** The second parameter is a pointer to an integer into which is written
2209 +** 0 or 1 to indicate whether output-for-triggers has been disabled - 0 if
2210 +** it is not disabled, 1 if it is.
2211 +** </dd>
2212 +**
2213 +** [[SQLITE_DBCONFIG_RESET_DATABASE]] <dt>SQLITE_DBCONFIG_RESET_DATABASE</dt>
2214 +** <dd> Set the SQLITE_DBCONFIG_RESET_DATABASE flag and then run
2215 +** [VACUUM] in order to reset a database back to an empty database
2216 +** with no schema and no content. The following process works even for
2217 +** a badly corrupted database file:
2218 +** <ol>
2219 +** <li> If the database connection is newly opened, make sure it has read the
2220 +** database schema by preparing then discarding some query against the
2221 +** database, or calling sqlite3_table_column_metadata(), ignoring any
2222 +** errors. This step is only necessary if the application desires to keep
2223 +** the database in WAL mode after the reset if it was in WAL mode before
2224 +** the reset.
2225 +** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 1, 0);
2226 +** <li> [sqlite3_exec](db, "[VACUUM]", 0, 0, 0);
2227 +** <li> sqlite3_db_config(db, SQLITE_DBCONFIG_RESET_DATABASE, 0, 0);
2228 +** </ol>
2229 +** Because resetting a database is destructive and irreversible, the
2230 +** process requires the use of this obscure API and multiple steps to help
2231 +** ensure that it does not happen by accident.
2232 +**
2233 +** [[SQLITE_DBCONFIG_DEFENSIVE]] <dt>SQLITE_DBCONFIG_DEFENSIVE</dt>
2234 +** <dd>The SQLITE_DBCONFIG_DEFENSIVE option activates or deactivates the
2235 +** "defensive" flag for a database connection. When the defensive
2236 +** flag is enabled, language features that allow ordinary SQL to
2237 +** deliberately corrupt the database file are disabled. The disabled
2238 +** features include but are not limited to the following:
2239 +** <ul>
2240 +** <li> The [PRAGMA writable_schema=ON] statement.
2241 +** <li> The [PRAGMA journal_mode=OFF] statement.
2242 +** <li> Writes to the [sqlite_dbpage] virtual table.
2243 +** <li> Direct writes to [shadow tables].
2244 +** </ul>
2245 +** </dd>
2246 +**
2247 +** [[SQLITE_DBCONFIG_WRITABLE_SCHEMA]] <dt>SQLITE_DBCONFIG_WRITABLE_SCHEMA</dt>
2248 +** <dd>The SQLITE_DBCONFIG_WRITABLE_SCHEMA option activates or deactivates the
2249 +** "writable_schema" flag. This has the same effect and is logically equivalent
2250 +** to setting [PRAGMA writable_schema=ON] or [PRAGMA writable_schema=OFF].
2251 +** The first argument to this setting is an integer which is 0 to disable
2252 +** the writable_schema, positive to enable writable_schema, or negative to
2253 +** leave the setting unchanged. The second parameter is a pointer to an
2254 +** integer into which is written 0 or 1 to indicate whether the writable_schema
2255 +** is enabled or disabled following this call.
2256 +** </dd>
2257 +**
2258 +** [[SQLITE_DBCONFIG_LEGACY_ALTER_TABLE]]
2259 +** <dt>SQLITE_DBCONFIG_LEGACY_ALTER_TABLE</dt>
2260 +** <dd>The SQLITE_DBCONFIG_LEGACY_ALTER_TABLE option activates or deactivates
2261 +** the legacy behavior of the [ALTER TABLE RENAME] command such it
2262 +** behaves as it did prior to [version 3.24.0] (2018-06-04). See the
2263 +** "Compatibility Notice" on the [ALTER TABLE RENAME documentation] for
2264 +** additional information. This feature can also be turned on and off
2265 +** using the [PRAGMA legacy_alter_table] statement.
2266 +** </dd>
2267 +**
2268 +** [[SQLITE_DBCONFIG_DQS_DML]]
2269 +** <dt>SQLITE_DBCONFIG_DQS_DML</td>
2270 +** <dd>The SQLITE_DBCONFIG_DQS_DML option activates or deactivates
2271 +** the legacy [double-quoted string literal] misfeature for DML statements
2272 +** only, that is DELETE, INSERT, SELECT, and UPDATE statements. The
2273 +** default value of this setting is determined by the [-DSQLITE_DQS]
2274 +** compile-time option.
2275 +** </dd>
2276 +**
2277 +** [[SQLITE_DBCONFIG_DQS_DDL]]
2278 +** <dt>SQLITE_DBCONFIG_DQS_DDL</td>
2279 +** <dd>The SQLITE_DBCONFIG_DQS option activates or deactivates
2280 +** the legacy [double-quoted string literal] misfeature for DDL statements,
2281 +** such as CREATE TABLE and CREATE INDEX. The
2282 +** default value of this setting is determined by the [-DSQLITE_DQS]
2283 +** compile-time option.
2284 +** </dd>
2285 +**
2286 +** [[SQLITE_DBCONFIG_TRUSTED_SCHEMA]]
2287 +** <dt>SQLITE_DBCONFIG_TRUSTED_SCHEMA</td>
2288 +** <dd>The SQLITE_DBCONFIG_TRUSTED_SCHEMA option tells SQLite to
2289 +** assume that database schemas are untainted by malicious content.
2290 +** When the SQLITE_DBCONFIG_TRUSTED_SCHEMA option is disabled, SQLite
2291 +** takes additional defensive steps to protect the application from harm
2292 +** including:
2293 +** <ul>
2294 +** <li> Prohibit the use of SQL functions inside triggers, views,
2295 +** CHECK constraints, DEFAULT clauses, expression indexes,
2296 +** partial indexes, or generated columns
2297 +** unless those functions are tagged with [SQLITE_INNOCUOUS].
2298 +** <li> Prohibit the use of virtual tables inside of triggers or views
2299 +** unless those virtual tables are tagged with [SQLITE_VTAB_INNOCUOUS].
2300 +** </ul>
2301 +** This setting defaults to "on" for legacy compatibility, however
2302 +** all applications are advised to turn it off if possible. This setting
2303 +** can also be controlled using the [PRAGMA trusted_schema] statement.
2304 +** </dd>
2305 +**
2306 +** [[SQLITE_DBCONFIG_LEGACY_FILE_FORMAT]]
2307 +** <dt>SQLITE_DBCONFIG_LEGACY_FILE_FORMAT</td>
2308 +** <dd>The SQLITE_DBCONFIG_LEGACY_FILE_FORMAT option activates or deactivates
2309 +** the legacy file format flag. When activated, this flag causes all newly
2310 +** created database file to have a schema format version number (the 4-byte
2311 +** integer found at offset 44 into the database header) of 1. This in turn
2312 +** means that the resulting database file will be readable and writable by
2313 +** any SQLite version back to 3.0.0 ([dateof:3.0.0]). Without this setting,
2314 +** newly created databases are generally not understandable by SQLite versions
2315 +** prior to 3.3.0 ([dateof:3.3.0]). As these words are written, there
2316 +** is now scarcely any need to generated database files that are compatible
2317 +** all the way back to version 3.0.0, and so this setting is of little
2318 +** practical use, but is provided so that SQLite can continue to claim the
2319 +** ability to generate new database files that are compatible with version
2320 +** 3.0.0.
2321 +** <p>Note that when the SQLITE_DBCONFIG_LEGACY_FILE_FORMAT setting is on,
2322 +** the [VACUUM] command will fail with an obscure error when attempting to
2323 +** process a table with generated columns and a descending index. This is
2324 +** not considered a bug since SQLite versions 3.3.0 and earlier do not support
2325 +** either generated columns or decending indexes.
2326 +** </dd>
2327 +** </dl>
2328 +*/
2329 +#define SQLITE_DBCONFIG_MAINDBNAME 1000 /* const char* */
2330 +#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
2331 +#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */
2332 +#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */
2333 +#define SQLITE_DBCONFIG_ENABLE_FTS3_TOKENIZER 1004 /* int int* */
2334 +#define SQLITE_DBCONFIG_ENABLE_LOAD_EXTENSION 1005 /* int int* */
2335 +#define SQLITE_DBCONFIG_NO_CKPT_ON_CLOSE 1006 /* int int* */
2336 +#define SQLITE_DBCONFIG_ENABLE_QPSG 1007 /* int int* */
2337 +#define SQLITE_DBCONFIG_TRIGGER_EQP 1008 /* int int* */
2338 +#define SQLITE_DBCONFIG_RESET_DATABASE 1009 /* int int* */
2339 +#define SQLITE_DBCONFIG_DEFENSIVE 1010 /* int int* */
2340 +#define SQLITE_DBCONFIG_WRITABLE_SCHEMA 1011 /* int int* */
2341 +#define SQLITE_DBCONFIG_LEGACY_ALTER_TABLE 1012 /* int int* */
2342 +#define SQLITE_DBCONFIG_DQS_DML 1013 /* int int* */
2343 +#define SQLITE_DBCONFIG_DQS_DDL 1014 /* int int* */
2344 +#define SQLITE_DBCONFIG_ENABLE_VIEW 1015 /* int int* */
2345 +#define SQLITE_DBCONFIG_LEGACY_FILE_FORMAT 1016 /* int int* */
2346 +#define SQLITE_DBCONFIG_TRUSTED_SCHEMA 1017 /* int int* */
2347 +#define SQLITE_DBCONFIG_MAX 1017 /* Largest DBCONFIG */
2348 +
2349 +/*
2350 +** CAPI3REF: Enable Or Disable Extended Result Codes
2351 +** METHOD: sqlite3
2352 +**
2353 +** ^The sqlite3_extended_result_codes() routine enables or disables the
2354 +** [extended result codes] feature of SQLite. ^The extended result
2355 +** codes are disabled by default for historical compatibility.
2356 +*/
2357 +SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
2358 +
2359 +/*
2360 +** CAPI3REF: Last Insert Rowid
2361 +** METHOD: sqlite3
2362 +**
2363 +** ^Each entry in most SQLite tables (except for [WITHOUT ROWID] tables)
2364 +** has a unique 64-bit signed
2365 +** integer key called the [ROWID | "rowid"]. ^The rowid is always available
2366 +** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
2367 +** names are not also used by explicitly declared columns. ^If
2368 +** the table has a column of type [INTEGER PRIMARY KEY] then that column
2369 +** is another alias for the rowid.
2370 +**
2371 +** ^The sqlite3_last_insert_rowid(D) interface usually returns the [rowid] of
2372 +** the most recent successful [INSERT] into a rowid table or [virtual table]
2373 +** on database connection D. ^Inserts into [WITHOUT ROWID] tables are not
2374 +** recorded. ^If no successful [INSERT]s into rowid tables have ever occurred
2375 +** on the database connection D, then sqlite3_last_insert_rowid(D) returns
2376 +** zero.
2377 +**
2378 +** As well as being set automatically as rows are inserted into database
2379 +** tables, the value returned by this function may be set explicitly by
2380 +** [sqlite3_set_last_insert_rowid()]
2381 +**
2382 +** Some virtual table implementations may INSERT rows into rowid tables as
2383 +** part of committing a transaction (e.g. to flush data accumulated in memory
2384 +** to disk). In this case subsequent calls to this function return the rowid
2385 +** associated with these internal INSERT operations, which leads to
2386 +** unintuitive results. Virtual table implementations that do write to rowid
2387 +** tables in this way can avoid this problem by restoring the original
2388 +** rowid value using [sqlite3_set_last_insert_rowid()] before returning
2389 +** control to the user.
2390 +**
2391 +** ^(If an [INSERT] occurs within a trigger then this routine will
2392 +** return the [rowid] of the inserted row as long as the trigger is
2393 +** running. Once the trigger program ends, the value returned
2394 +** by this routine reverts to what it was before the trigger was fired.)^
2395 +**
2396 +** ^An [INSERT] that fails due to a constraint violation is not a
2397 +** successful [INSERT] and does not change the value returned by this
2398 +** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
2399 +** and INSERT OR ABORT make no changes to the return value of this
2400 +** routine when their insertion fails. ^(When INSERT OR REPLACE
2401 +** encounters a constraint violation, it does not fail. The
2402 +** INSERT continues to completion after deleting rows that caused
2403 +** the constraint problem so INSERT OR REPLACE will always change
2404 +** the return value of this interface.)^
2405 +**
2406 +** ^For the purposes of this routine, an [INSERT] is considered to
2407 +** be successful even if it is subsequently rolled back.
2408 +**
2409 +** This function is accessible to SQL statements via the
2410 +** [last_insert_rowid() SQL function].
2411 +**
2412 +** If a separate thread performs a new [INSERT] on the same
2413 +** database connection while the [sqlite3_last_insert_rowid()]
2414 +** function is running and thus changes the last insert [rowid],
2415 +** then the value returned by [sqlite3_last_insert_rowid()] is
2416 +** unpredictable and might not equal either the old or the new
2417 +** last insert [rowid].
2418 +*/
2419 +SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
2420 +
2421 +/*
2422 +** CAPI3REF: Set the Last Insert Rowid value.
2423 +** METHOD: sqlite3
2424 +**
2425 +** The sqlite3_set_last_insert_rowid(D, R) method allows the application to
2426 +** set the value returned by calling sqlite3_last_insert_rowid(D) to R
2427 +** without inserting a row into the database.
2428 +*/
2429 +SQLITE_API void sqlite3_set_last_insert_rowid(sqlite3*,sqlite3_int64);
2430 +
2431 +/*
2432 +** CAPI3REF: Count The Number Of Rows Modified
2433 +** METHOD: sqlite3
2434 +**
2435 +** ^This function returns the number of rows modified, inserted or
2436 +** deleted by the most recently completed INSERT, UPDATE or DELETE
2437 +** statement on the database connection specified by the only parameter.
2438 +** ^Executing any other type of SQL statement does not modify the value
2439 +** returned by this function.
2440 +**
2441 +** ^Only changes made directly by the INSERT, UPDATE or DELETE statement are
2442 +** considered - auxiliary changes caused by [CREATE TRIGGER | triggers],
2443 +** [foreign key actions] or [REPLACE] constraint resolution are not counted.
2444 +**
2445 +** Changes to a view that are intercepted by
2446 +** [INSTEAD OF trigger | INSTEAD OF triggers] are not counted. ^The value
2447 +** returned by sqlite3_changes() immediately after an INSERT, UPDATE or
2448 +** DELETE statement run on a view is always zero. Only changes made to real
2449 +** tables are counted.
2450 +**
2451 +** Things are more complicated if the sqlite3_changes() function is
2452 +** executed while a trigger program is running. This may happen if the
2453 +** program uses the [changes() SQL function], or if some other callback
2454 +** function invokes sqlite3_changes() directly. Essentially:
2455 +**
2456 +** <ul>
2457 +** <li> ^(Before entering a trigger program the value returned by
2458 +** sqlite3_changes() function is saved. After the trigger program
2459 +** has finished, the original value is restored.)^
2460 +**
2461 +** <li> ^(Within a trigger program each INSERT, UPDATE and DELETE
2462 +** statement sets the value returned by sqlite3_changes()
2463 +** upon completion as normal. Of course, this value will not include
2464 +** any changes performed by sub-triggers, as the sqlite3_changes()
2465 +** value will be saved and restored after each sub-trigger has run.)^
2466 +** </ul>
2467 +**
2468 +** ^This means that if the changes() SQL function (or similar) is used
2469 +** by the first INSERT, UPDATE or DELETE statement within a trigger, it
2470 +** returns the value as set when the calling statement began executing.
2471 +** ^If it is used by the second or subsequent such statement within a trigger
2472 +** program, the value returned reflects the number of rows modified by the
2473 +** previous INSERT, UPDATE or DELETE statement within the same trigger.
2474 +**
2475 +** If a separate thread makes changes on the same database connection
2476 +** while [sqlite3_changes()] is running then the value returned
2477 +** is unpredictable and not meaningful.
2478 +**
2479 +** See also:
2480 +** <ul>
2481 +** <li> the [sqlite3_total_changes()] interface
2482 +** <li> the [count_changes pragma]
2483 +** <li> the [changes() SQL function]
2484 +** <li> the [data_version pragma]
2485 +** </ul>
2486 +*/
2487 +SQLITE_API int sqlite3_changes(sqlite3*);
2488 +
2489 +/*
2490 +** CAPI3REF: Total Number Of Rows Modified
2491 +** METHOD: sqlite3
2492 +**
2493 +** ^This function returns the total number of rows inserted, modified or
2494 +** deleted by all [INSERT], [UPDATE] or [DELETE] statements completed
2495 +** since the database connection was opened, including those executed as
2496 +** part of trigger programs. ^Executing any other type of SQL statement
2497 +** does not affect the value returned by sqlite3_total_changes().
2498 +**
2499 +** ^Changes made as part of [foreign key actions] are included in the
2500 +** count, but those made as part of REPLACE constraint resolution are
2501 +** not. ^Changes to a view that are intercepted by INSTEAD OF triggers
2502 +** are not counted.
2503 +**
2504 +** The [sqlite3_total_changes(D)] interface only reports the number
2505 +** of rows that changed due to SQL statement run against database
2506 +** connection D. Any changes by other database connections are ignored.
2507 +** To detect changes against a database file from other database
2508 +** connections use the [PRAGMA data_version] command or the
2509 +** [SQLITE_FCNTL_DATA_VERSION] [file control].
2510 +**
2511 +** If a separate thread makes changes on the same database connection
2512 +** while [sqlite3_total_changes()] is running then the value
2513 +** returned is unpredictable and not meaningful.
2514 +**
2515 +** See also:
2516 +** <ul>
2517 +** <li> the [sqlite3_changes()] interface
2518 +** <li> the [count_changes pragma]
2519 +** <li> the [changes() SQL function]
2520 +** <li> the [data_version pragma]
2521 +** <li> the [SQLITE_FCNTL_DATA_VERSION] [file control]
2522 +** </ul>
2523 +*/
2524 +SQLITE_API int sqlite3_total_changes(sqlite3*);
2525 +
2526 +/*
2527 +** CAPI3REF: Interrupt A Long-Running Query
2528 +** METHOD: sqlite3
2529 +**
2530 +** ^This function causes any pending database operation to abort and
2531 +** return at its earliest opportunity. This routine is typically
2532 +** called in response to a user action such as pressing "Cancel"
2533 +** or Ctrl-C where the user wants a long query operation to halt
2534 +** immediately.
2535 +**
2536 +** ^It is safe to call this routine from a thread different from the
2537 +** thread that is currently running the database operation. But it
2538 +** is not safe to call this routine with a [database connection] that
2539 +** is closed or might close before sqlite3_interrupt() returns.
2540 +**
2541 +** ^If an SQL operation is very nearly finished at the time when
2542 +** sqlite3_interrupt() is called, then it might not have an opportunity
2543 +** to be interrupted and might continue to completion.
2544 +**
2545 +** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
2546 +** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
2547 +** that is inside an explicit transaction, then the entire transaction
2548 +** will be rolled back automatically.
2549 +**
2550 +** ^The sqlite3_interrupt(D) call is in effect until all currently running
2551 +** SQL statements on [database connection] D complete. ^Any new SQL statements
2552 +** that are started after the sqlite3_interrupt() call and before the
2553 +** running statement count reaches zero are interrupted as if they had been
2554 +** running prior to the sqlite3_interrupt() call. ^New SQL statements
2555 +** that are started after the running statement count reaches zero are
2556 +** not effected by the sqlite3_interrupt().
2557 +** ^A call to sqlite3_interrupt(D) that occurs when there are no running
2558 +** SQL statements is a no-op and has no effect on SQL statements
2559 +** that are started after the sqlite3_interrupt() call returns.
2560 +*/
2561 +SQLITE_API void sqlite3_interrupt(sqlite3*);
2562 +
2563 +/*
2564 +** CAPI3REF: Determine If An SQL Statement Is Complete
2565 +**
2566 +** These routines are useful during command-line input to determine if the
2567 +** currently entered text seems to form a complete SQL statement or
2568 +** if additional input is needed before sending the text into
2569 +** SQLite for parsing. ^These routines return 1 if the input string
2570 +** appears to be a complete SQL statement. ^A statement is judged to be
2571 +** complete if it ends with a semicolon token and is not a prefix of a
2572 +** well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within
2573 +** string literals or quoted identifier names or comments are not
2574 +** independent tokens (they are part of the token in which they are
2575 +** embedded) and thus do not count as a statement terminator. ^Whitespace
2576 +** and comments that follow the final semicolon are ignored.
2577 +**
2578 +** ^These routines return 0 if the statement is incomplete. ^If a
2579 +** memory allocation fails, then SQLITE_NOMEM is returned.
2580 +**
2581 +** ^These routines do not parse the SQL statements thus
2582 +** will not detect syntactically incorrect SQL.
2583 +**
2584 +** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior
2585 +** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
2586 +** automatically by sqlite3_complete16(). If that initialization fails,
2587 +** then the return value from sqlite3_complete16() will be non-zero
2588 +** regardless of whether or not the input SQL is complete.)^
2589 +**
2590 +** The input to [sqlite3_complete()] must be a zero-terminated
2591 +** UTF-8 string.
2592 +**
2593 +** The input to [sqlite3_complete16()] must be a zero-terminated
2594 +** UTF-16 string in native byte order.
2595 +*/
2596 +SQLITE_API int sqlite3_complete(const char *sql);
2597 +SQLITE_API int sqlite3_complete16(const void *sql);
2598 +
2599 +/*
2600 +** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
2601 +** KEYWORDS: {busy-handler callback} {busy handler}
2602 +** METHOD: sqlite3
2603 +**
2604 +** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
2605 +** that might be invoked with argument P whenever
2606 +** an attempt is made to access a database table associated with
2607 +** [database connection] D when another thread
2608 +** or process has the table locked.
2609 +** The sqlite3_busy_handler() interface is used to implement
2610 +** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
2611 +**
2612 +** ^If the busy callback is NULL, then [SQLITE_BUSY]
2613 +** is returned immediately upon encountering the lock. ^If the busy callback
2614 +** is not NULL, then the callback might be invoked with two arguments.
2615 +**
2616 +** ^The first argument to the busy handler is a copy of the void* pointer which
2617 +** is the third argument to sqlite3_busy_handler(). ^The second argument to
2618 +** the busy handler callback is the number of times that the busy handler has
2619 +** been invoked previously for the same locking event. ^If the
2620 +** busy callback returns 0, then no additional attempts are made to
2621 +** access the database and [SQLITE_BUSY] is returned
2622 +** to the application.
2623 +** ^If the callback returns non-zero, then another attempt
2624 +** is made to access the database and the cycle repeats.
2625 +**
2626 +** The presence of a busy handler does not guarantee that it will be invoked
2627 +** when there is lock contention. ^If SQLite determines that invoking the busy
2628 +** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
2629 +** to the application instead of invoking the
2630 +** busy handler.
2631 +** Consider a scenario where one process is holding a read lock that
2632 +** it is trying to promote to a reserved lock and
2633 +** a second process is holding a reserved lock that it is trying
2634 +** to promote to an exclusive lock. The first process cannot proceed
2635 +** because it is blocked by the second and the second process cannot
2636 +** proceed because it is blocked by the first. If both processes
2637 +** invoke the busy handlers, neither will make any progress. Therefore,
2638 +** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
2639 +** will induce the first process to release its read lock and allow
2640 +** the second process to proceed.
2641 +**
2642 +** ^The default busy callback is NULL.
2643 +**
2644 +** ^(There can only be a single busy handler defined for each
2645 +** [database connection]. Setting a new busy handler clears any
2646 +** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()]
2647 +** or evaluating [PRAGMA busy_timeout=N] will change the
2648 +** busy handler and thus clear any previously set busy handler.
2649 +**
2650 +** The busy callback should not take any actions which modify the
2651 +** database connection that invoked the busy handler. In other words,
2652 +** the busy handler is not reentrant. Any such actions
2653 +** result in undefined behavior.
2654 +**
2655 +** A busy handler must not close the database connection
2656 +** or [prepared statement] that invoked the busy handler.
2657 +*/
2658 +SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);
2659 +
2660 +/*
2661 +** CAPI3REF: Set A Busy Timeout
2662 +** METHOD: sqlite3
2663 +**
2664 +** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
2665 +** for a specified amount of time when a table is locked. ^The handler
2666 +** will sleep multiple times until at least "ms" milliseconds of sleeping
2667 +** have accumulated. ^After at least "ms" milliseconds of sleeping,
2668 +** the handler returns 0 which causes [sqlite3_step()] to return
2669 +** [SQLITE_BUSY].
2670 +**
2671 +** ^Calling this routine with an argument less than or equal to zero
2672 +** turns off all busy handlers.
2673 +**
2674 +** ^(There can only be a single busy handler for a particular
2675 +** [database connection] at any given moment. If another busy handler
2676 +** was defined (using [sqlite3_busy_handler()]) prior to calling
2677 +** this routine, that other busy handler is cleared.)^
2678 +**
2679 +** See also: [PRAGMA busy_timeout]
2680 +*/
2681 +SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
2682 +
2683 +/*
2684 +** CAPI3REF: Convenience Routines For Running Queries
2685 +** METHOD: sqlite3
2686 +**
2687 +** This is a legacy interface that is preserved for backwards compatibility.
2688 +** Use of this interface is not recommended.
2689 +**
2690 +** Definition: A <b>result table</b> is memory data structure created by the
2691 +** [sqlite3_get_table()] interface. A result table records the
2692 +** complete query results from one or more queries.
2693 +**
2694 +** The table conceptually has a number of rows and columns. But
2695 +** these numbers are not part of the result table itself. These
2696 +** numbers are obtained separately. Let N be the number of rows
2697 +** and M be the number of columns.
2698 +**
2699 +** A result table is an array of pointers to zero-terminated UTF-8 strings.
2700 +** There are (N+1)*M elements in the array. The first M pointers point
2701 +** to zero-terminated strings that contain the names of the columns.
2702 +** The remaining entries all point to query results. NULL values result
2703 +** in NULL pointers. All other values are in their UTF-8 zero-terminated
2704 +** string representation as returned by [sqlite3_column_text()].
2705 +**
2706 +** A result table might consist of one or more memory allocations.
2707 +** It is not safe to pass a result table directly to [sqlite3_free()].
2708 +** A result table should be deallocated using [sqlite3_free_table()].
2709 +**
2710 +** ^(As an example of the result table format, suppose a query result
2711 +** is as follows:
2712 +**
2713 +** <blockquote><pre>
2714 +** Name | Age
2715 +** -----------------------
2716 +** Alice | 43
2717 +** Bob | 28
2718 +** Cindy | 21
2719 +** </pre></blockquote>
2720 +**
2721 +** There are two columns (M==2) and three rows (N==3). Thus the
2722 +** result table has 8 entries. Suppose the result table is stored
2723 +** in an array named azResult. Then azResult holds this content:
2724 +**
2725 +** <blockquote><pre>
2726 +** azResult&#91;0] = "Name";
2727 +** azResult&#91;1] = "Age";
2728 +** azResult&#91;2] = "Alice";
2729 +** azResult&#91;3] = "43";
2730 +** azResult&#91;4] = "Bob";
2731 +** azResult&#91;5] = "28";
2732 +** azResult&#91;6] = "Cindy";
2733 +** azResult&#91;7] = "21";
2734 +** </pre></blockquote>)^
2735 +**
2736 +** ^The sqlite3_get_table() function evaluates one or more
2737 +** semicolon-separated SQL statements in the zero-terminated UTF-8
2738 +** string of its 2nd parameter and returns a result table to the
2739 +** pointer given in its 3rd parameter.
2740 +**
2741 +** After the application has finished with the result from sqlite3_get_table(),
2742 +** it must pass the result table pointer to sqlite3_free_table() in order to
2743 +** release the memory that was malloced. Because of the way the
2744 +** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
2745 +** function must not try to call [sqlite3_free()] directly. Only
2746 +** [sqlite3_free_table()] is able to release the memory properly and safely.
2747 +**
2748 +** The sqlite3_get_table() interface is implemented as a wrapper around
2749 +** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access
2750 +** to any internal data structures of SQLite. It uses only the public
2751 +** interface defined here. As a consequence, errors that occur in the
2752 +** wrapper layer outside of the internal [sqlite3_exec()] call are not
2753 +** reflected in subsequent calls to [sqlite3_errcode()] or
2754 +** [sqlite3_errmsg()].
2755 +*/
2756 +SQLITE_API int sqlite3_get_table(
2757 + sqlite3 *db, /* An open database */
2758 + const char *zSql, /* SQL to be evaluated */
2759 + char ***pazResult, /* Results of the query */
2760 + int *pnRow, /* Number of result rows written here */
2761 + int *pnColumn, /* Number of result columns written here */
2762 + char **pzErrmsg /* Error msg written here */
2763 +);
2764 +SQLITE_API void sqlite3_free_table(char **result);
2765 +
2766 +/*
2767 +** CAPI3REF: Formatted String Printing Functions
2768 +**
2769 +** These routines are work-alikes of the "printf()" family of functions
2770 +** from the standard C library.
2771 +** These routines understand most of the common formatting options from
2772 +** the standard library printf()
2773 +** plus some additional non-standard formats ([%q], [%Q], [%w], and [%z]).
2774 +** See the [built-in printf()] documentation for details.
2775 +**
2776 +** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
2777 +** results into memory obtained from [sqlite3_malloc64()].
2778 +** The strings returned by these two routines should be
2779 +** released by [sqlite3_free()]. ^Both routines return a
2780 +** NULL pointer if [sqlite3_malloc64()] is unable to allocate enough
2781 +** memory to hold the resulting string.
2782 +**
2783 +** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
2784 +** the standard C library. The result is written into the
2785 +** buffer supplied as the second parameter whose size is given by
2786 +** the first parameter. Note that the order of the
2787 +** first two parameters is reversed from snprintf().)^ This is an
2788 +** historical accident that cannot be fixed without breaking
2789 +** backwards compatibility. ^(Note also that sqlite3_snprintf()
2790 +** returns a pointer to its buffer instead of the number of
2791 +** characters actually written into the buffer.)^ We admit that
2792 +** the number of characters written would be a more useful return
2793 +** value but we cannot change the implementation of sqlite3_snprintf()
2794 +** now without breaking compatibility.
2795 +**
2796 +** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
2797 +** guarantees that the buffer is always zero-terminated. ^The first
2798 +** parameter "n" is the total size of the buffer, including space for
2799 +** the zero terminator. So the longest string that can be completely
2800 +** written will be n-1 characters.
2801 +**
2802 +** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
2803 +**
2804 +** See also: [built-in printf()], [printf() SQL function]
2805 +*/
2806 +SQLITE_API char *sqlite3_mprintf(const char*,...);
2807 +SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
2808 +SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
2809 +SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
2810 +
2811 +/*
2812 +** CAPI3REF: Memory Allocation Subsystem
2813 +**
2814 +** The SQLite core uses these three routines for all of its own
2815 +** internal memory allocation needs. "Core" in the previous sentence
2816 +** does not include operating-system specific [VFS] implementation. The
2817 +** Windows VFS uses native malloc() and free() for some operations.
2818 +**
2819 +** ^The sqlite3_malloc() routine returns a pointer to a block
2820 +** of memory at least N bytes in length, where N is the parameter.
2821 +** ^If sqlite3_malloc() is unable to obtain sufficient free
2822 +** memory, it returns a NULL pointer. ^If the parameter N to
2823 +** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
2824 +** a NULL pointer.
2825 +**
2826 +** ^The sqlite3_malloc64(N) routine works just like
2827 +** sqlite3_malloc(N) except that N is an unsigned 64-bit integer instead
2828 +** of a signed 32-bit integer.
2829 +**
2830 +** ^Calling sqlite3_free() with a pointer previously returned
2831 +** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
2832 +** that it might be reused. ^The sqlite3_free() routine is
2833 +** a no-op if is called with a NULL pointer. Passing a NULL pointer
2834 +** to sqlite3_free() is harmless. After being freed, memory
2835 +** should neither be read nor written. Even reading previously freed
2836 +** memory might result in a segmentation fault or other severe error.
2837 +** Memory corruption, a segmentation fault, or other severe error
2838 +** might result if sqlite3_free() is called with a non-NULL pointer that
2839 +** was not obtained from sqlite3_malloc() or sqlite3_realloc().
2840 +**
2841 +** ^The sqlite3_realloc(X,N) interface attempts to resize a
2842 +** prior memory allocation X to be at least N bytes.
2843 +** ^If the X parameter to sqlite3_realloc(X,N)
2844 +** is a NULL pointer then its behavior is identical to calling
2845 +** sqlite3_malloc(N).
2846 +** ^If the N parameter to sqlite3_realloc(X,N) is zero or
2847 +** negative then the behavior is exactly the same as calling
2848 +** sqlite3_free(X).
2849 +** ^sqlite3_realloc(X,N) returns a pointer to a memory allocation
2850 +** of at least N bytes in size or NULL if insufficient memory is available.
2851 +** ^If M is the size of the prior allocation, then min(N,M) bytes
2852 +** of the prior allocation are copied into the beginning of buffer returned
2853 +** by sqlite3_realloc(X,N) and the prior allocation is freed.
2854 +** ^If sqlite3_realloc(X,N) returns NULL and N is positive, then the
2855 +** prior allocation is not freed.
2856 +**
2857 +** ^The sqlite3_realloc64(X,N) interfaces works the same as
2858 +** sqlite3_realloc(X,N) except that N is a 64-bit unsigned integer instead
2859 +** of a 32-bit signed integer.
2860 +**
2861 +** ^If X is a memory allocation previously obtained from sqlite3_malloc(),
2862 +** sqlite3_malloc64(), sqlite3_realloc(), or sqlite3_realloc64(), then
2863 +** sqlite3_msize(X) returns the size of that memory allocation in bytes.
2864 +** ^The value returned by sqlite3_msize(X) might be larger than the number
2865 +** of bytes requested when X was allocated. ^If X is a NULL pointer then
2866 +** sqlite3_msize(X) returns zero. If X points to something that is not
2867 +** the beginning of memory allocation, or if it points to a formerly
2868 +** valid memory allocation that has now been freed, then the behavior
2869 +** of sqlite3_msize(X) is undefined and possibly harmful.
2870 +**
2871 +** ^The memory returned by sqlite3_malloc(), sqlite3_realloc(),
2872 +** sqlite3_malloc64(), and sqlite3_realloc64()
2873 +** is always aligned to at least an 8 byte boundary, or to a
2874 +** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
2875 +** option is used.
2876 +**
2877 +** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
2878 +** must be either NULL or else pointers obtained from a prior
2879 +** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
2880 +** not yet been released.
2881 +**
2882 +** The application must not read or write any part of
2883 +** a block of memory after it has been released using
2884 +** [sqlite3_free()] or [sqlite3_realloc()].
2885 +*/
2886 +SQLITE_API void *sqlite3_malloc(int);
2887 +SQLITE_API void *sqlite3_malloc64(sqlite3_uint64);
2888 +SQLITE_API void *sqlite3_realloc(void*, int);
2889 +SQLITE_API void *sqlite3_realloc64(void*, sqlite3_uint64);
2890 +SQLITE_API void sqlite3_free(void*);
2891 +SQLITE_API sqlite3_uint64 sqlite3_msize(void*);
2892 +
2893 +/*
2894 +** CAPI3REF: Memory Allocator Statistics
2895 +**
2896 +** SQLite provides these two interfaces for reporting on the status
2897 +** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
2898 +** routines, which form the built-in memory allocation subsystem.
2899 +**
2900 +** ^The [sqlite3_memory_used()] routine returns the number of bytes
2901 +** of memory currently outstanding (malloced but not freed).
2902 +** ^The [sqlite3_memory_highwater()] routine returns the maximum
2903 +** value of [sqlite3_memory_used()] since the high-water mark
2904 +** was last reset. ^The values returned by [sqlite3_memory_used()] and
2905 +** [sqlite3_memory_highwater()] include any overhead
2906 +** added by SQLite in its implementation of [sqlite3_malloc()],
2907 +** but not overhead added by the any underlying system library
2908 +** routines that [sqlite3_malloc()] may call.
2909 +**
2910 +** ^The memory high-water mark is reset to the current value of
2911 +** [sqlite3_memory_used()] if and only if the parameter to
2912 +** [sqlite3_memory_highwater()] is true. ^The value returned
2913 +** by [sqlite3_memory_highwater(1)] is the high-water mark
2914 +** prior to the reset.
2915 +*/
2916 +SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
2917 +SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
2918 +
2919 +/*
2920 +** CAPI3REF: Pseudo-Random Number Generator
2921 +**
2922 +** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
2923 +** select random [ROWID | ROWIDs] when inserting new records into a table that
2924 +** already uses the largest possible [ROWID]. The PRNG is also used for
2925 +** the built-in random() and randomblob() SQL functions. This interface allows
2926 +** applications to access the same PRNG for other purposes.
2927 +**
2928 +** ^A call to this routine stores N bytes of randomness into buffer P.
2929 +** ^The P parameter can be a NULL pointer.
2930 +**
2931 +** ^If this routine has not been previously called or if the previous
2932 +** call had N less than one or a NULL pointer for P, then the PRNG is
2933 +** seeded using randomness obtained from the xRandomness method of
2934 +** the default [sqlite3_vfs] object.
2935 +** ^If the previous call to this routine had an N of 1 or more and a
2936 +** non-NULL P then the pseudo-randomness is generated
2937 +** internally and without recourse to the [sqlite3_vfs] xRandomness
2938 +** method.
2939 +*/
2940 +SQLITE_API void sqlite3_randomness(int N, void *P);
2941 +
2942 +/*
2943 +** CAPI3REF: Compile-Time Authorization Callbacks
2944 +** METHOD: sqlite3
2945 +** KEYWORDS: {authorizer callback}
2946 +**
2947 +** ^This routine registers an authorizer callback with a particular
2948 +** [database connection], supplied in the first argument.
2949 +** ^The authorizer callback is invoked as SQL statements are being compiled
2950 +** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
2951 +** [sqlite3_prepare_v3()], [sqlite3_prepare16()], [sqlite3_prepare16_v2()],
2952 +** and [sqlite3_prepare16_v3()]. ^At various
2953 +** points during the compilation process, as logic is being created
2954 +** to perform various actions, the authorizer callback is invoked to
2955 +** see if those actions are allowed. ^The authorizer callback should
2956 +** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
2957 +** specific action but allow the SQL statement to continue to be
2958 +** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
2959 +** rejected with an error. ^If the authorizer callback returns
2960 +** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
2961 +** then the [sqlite3_prepare_v2()] or equivalent call that triggered
2962 +** the authorizer will fail with an error message.
2963 +**
2964 +** When the callback returns [SQLITE_OK], that means the operation
2965 +** requested is ok. ^When the callback returns [SQLITE_DENY], the
2966 +** [sqlite3_prepare_v2()] or equivalent call that triggered the
2967 +** authorizer will fail with an error message explaining that
2968 +** access is denied.
2969 +**
2970 +** ^The first parameter to the authorizer callback is a copy of the third
2971 +** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
2972 +** to the callback is an integer [SQLITE_COPY | action code] that specifies
2973 +** the particular action to be authorized. ^The third through sixth parameters
2974 +** to the callback are either NULL pointers or zero-terminated strings
2975 +** that contain additional details about the action to be authorized.
2976 +** Applications must always be prepared to encounter a NULL pointer in any
2977 +** of the third through the sixth parameters of the authorization callback.
2978 +**
2979 +** ^If the action code is [SQLITE_READ]
2980 +** and the callback returns [SQLITE_IGNORE] then the
2981 +** [prepared statement] statement is constructed to substitute
2982 +** a NULL value in place of the table column that would have
2983 +** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
2984 +** return can be used to deny an untrusted user access to individual
2985 +** columns of a table.
2986 +** ^When a table is referenced by a [SELECT] but no column values are
2987 +** extracted from that table (for example in a query like
2988 +** "SELECT count(*) FROM tab") then the [SQLITE_READ] authorizer callback
2989 +** is invoked once for that table with a column name that is an empty string.
2990 +** ^If the action code is [SQLITE_DELETE] and the callback returns
2991 +** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
2992 +** [truncate optimization] is disabled and all rows are deleted individually.
2993 +**
2994 +** An authorizer is used when [sqlite3_prepare | preparing]
2995 +** SQL statements from an untrusted source, to ensure that the SQL statements
2996 +** do not try to access data they are not allowed to see, or that they do not
2997 +** try to execute malicious statements that damage the database. For
2998 +** example, an application may allow a user to enter arbitrary
2999 +** SQL queries for evaluation by a database. But the application does
3000 +** not want the user to be able to make arbitrary changes to the
3001 +** database. An authorizer could then be put in place while the
3002 +** user-entered SQL is being [sqlite3_prepare | prepared] that
3003 +** disallows everything except [SELECT] statements.
3004 +**
3005 +** Applications that need to process SQL from untrusted sources
3006 +** might also consider lowering resource limits using [sqlite3_limit()]
3007 +** and limiting database size using the [max_page_count] [PRAGMA]
3008 +** in addition to using an authorizer.
3009 +**
3010 +** ^(Only a single authorizer can be in place on a database connection
3011 +** at a time. Each call to sqlite3_set_authorizer overrides the
3012 +** previous call.)^ ^Disable the authorizer by installing a NULL callback.
3013 +** The authorizer is disabled by default.
3014 +**
3015 +** The authorizer callback must not do anything that will modify
3016 +** the database connection that invoked the authorizer callback.
3017 +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
3018 +** database connections for the meaning of "modify" in this paragraph.
3019 +**
3020 +** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
3021 +** statement might be re-prepared during [sqlite3_step()] due to a
3022 +** schema change. Hence, the application should ensure that the
3023 +** correct authorizer callback remains in place during the [sqlite3_step()].
3024 +**
3025 +** ^Note that the authorizer callback is invoked only during
3026 +** [sqlite3_prepare()] or its variants. Authorization is not
3027 +** performed during statement evaluation in [sqlite3_step()], unless
3028 +** as stated in the previous paragraph, sqlite3_step() invokes
3029 +** sqlite3_prepare_v2() to reprepare a statement after a schema change.
3030 +*/
3031 +SQLITE_API int sqlite3_set_authorizer(
3032 + sqlite3*,
3033 + int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
3034 + void *pUserData
3035 +);
3036 +
3037 +/*
3038 +** CAPI3REF: Authorizer Return Codes
3039 +**
3040 +** The [sqlite3_set_authorizer | authorizer callback function] must
3041 +** return either [SQLITE_OK] or one of these two constants in order
3042 +** to signal SQLite whether or not the action is permitted. See the
3043 +** [sqlite3_set_authorizer | authorizer documentation] for additional
3044 +** information.
3045 +**
3046 +** Note that SQLITE_IGNORE is also used as a [conflict resolution mode]
3047 +** returned from the [sqlite3_vtab_on_conflict()] interface.
3048 +*/
3049 +#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
3050 +#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
3051 +
3052 +/*
3053 +** CAPI3REF: Authorizer Action Codes
3054 +**
3055 +** The [sqlite3_set_authorizer()] interface registers a callback function
3056 +** that is invoked to authorize certain SQL statement actions. The
3057 +** second parameter to the callback is an integer code that specifies
3058 +** what action is being authorized. These are the integer action codes that
3059 +** the authorizer callback may be passed.
3060 +**
3061 +** These action code values signify what kind of operation is to be
3062 +** authorized. The 3rd and 4th parameters to the authorization
3063 +** callback function will be parameters or NULL depending on which of these
3064 +** codes is used as the second parameter. ^(The 5th parameter to the
3065 +** authorizer callback is the name of the database ("main", "temp",
3066 +** etc.) if applicable.)^ ^The 6th parameter to the authorizer callback
3067 +** is the name of the inner-most trigger or view that is responsible for
3068 +** the access attempt or NULL if this access attempt is directly from
3069 +** top-level SQL code.
3070 +*/
3071 +/******************************************* 3rd ************ 4th ***********/
3072 +#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
3073 +#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
3074 +#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
3075 +#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
3076 +#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
3077 +#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
3078 +#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
3079 +#define SQLITE_CREATE_VIEW 8 /* View Name NULL */
3080 +#define SQLITE_DELETE 9 /* Table Name NULL */
3081 +#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
3082 +#define SQLITE_DROP_TABLE 11 /* Table Name NULL */
3083 +#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
3084 +#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
3085 +#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
3086 +#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
3087 +#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
3088 +#define SQLITE_DROP_VIEW 17 /* View Name NULL */
3089 +#define SQLITE_INSERT 18 /* Table Name NULL */
3090 +#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
3091 +#define SQLITE_READ 20 /* Table Name Column Name */
3092 +#define SQLITE_SELECT 21 /* NULL NULL */
3093 +#define SQLITE_TRANSACTION 22 /* Operation NULL */
3094 +#define SQLITE_UPDATE 23 /* Table Name Column Name */
3095 +#define SQLITE_ATTACH 24 /* Filename NULL */
3096 +#define SQLITE_DETACH 25 /* Database Name NULL */
3097 +#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
3098 +#define SQLITE_REINDEX 27 /* Index Name NULL */
3099 +#define SQLITE_ANALYZE 28 /* Table Name NULL */
3100 +#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
3101 +#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
3102 +#define SQLITE_FUNCTION 31 /* NULL Function Name */
3103 +#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */
3104 +#define SQLITE_COPY 0 /* No longer used */
3105 +#define SQLITE_RECURSIVE 33 /* NULL NULL */
3106 +
3107 +/*
3108 +** CAPI3REF: Tracing And Profiling Functions
3109 +** METHOD: sqlite3
3110 +**
3111 +** These routines are deprecated. Use the [sqlite3_trace_v2()] interface
3112 +** instead of the routines described here.
3113 +**
3114 +** These routines register callback functions that can be used for
3115 +** tracing and profiling the execution of SQL statements.
3116 +**
3117 +** ^The callback function registered by sqlite3_trace() is invoked at
3118 +** various times when an SQL statement is being run by [sqlite3_step()].
3119 +** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
3120 +** SQL statement text as the statement first begins executing.
3121 +** ^(Additional sqlite3_trace() callbacks might occur
3122 +** as each triggered subprogram is entered. The callbacks for triggers
3123 +** contain a UTF-8 SQL comment that identifies the trigger.)^
3124 +**
3125 +** The [SQLITE_TRACE_SIZE_LIMIT] compile-time option can be used to limit
3126 +** the length of [bound parameter] expansion in the output of sqlite3_trace().
3127 +**
3128 +** ^The callback function registered by sqlite3_profile() is invoked
3129 +** as each SQL statement finishes. ^The profile callback contains
3130 +** the original statement text and an estimate of wall-clock time
3131 +** of how long that statement took to run. ^The profile callback
3132 +** time is in units of nanoseconds, however the current implementation
3133 +** is only capable of millisecond resolution so the six least significant
3134 +** digits in the time are meaningless. Future versions of SQLite
3135 +** might provide greater resolution on the profiler callback. Invoking
3136 +** either [sqlite3_trace()] or [sqlite3_trace_v2()] will cancel the
3137 +** profile callback.
3138 +*/
3139 +SQLITE_API SQLITE_DEPRECATED void *sqlite3_trace(sqlite3*,
3140 + void(*xTrace)(void*,const char*), void*);
3141 +SQLITE_API SQLITE_DEPRECATED void *sqlite3_profile(sqlite3*,
3142 + void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
3143 +
3144 +/*
3145 +** CAPI3REF: SQL Trace Event Codes
3146 +** KEYWORDS: SQLITE_TRACE
3147 +**
3148 +** These constants identify classes of events that can be monitored
3149 +** using the [sqlite3_trace_v2()] tracing logic. The M argument
3150 +** to [sqlite3_trace_v2(D,M,X,P)] is an OR-ed combination of one or more of
3151 +** the following constants. ^The first argument to the trace callback
3152 +** is one of the following constants.
3153 +**
3154 +** New tracing constants may be added in future releases.
3155 +**
3156 +** ^A trace callback has four arguments: xCallback(T,C,P,X).
3157 +** ^The T argument is one of the integer type codes above.
3158 +** ^The C argument is a copy of the context pointer passed in as the
3159 +** fourth argument to [sqlite3_trace_v2()].
3160 +** The P and X arguments are pointers whose meanings depend on T.
3161 +**
3162 +** <dl>
3163 +** [[SQLITE_TRACE_STMT]] <dt>SQLITE_TRACE_STMT</dt>
3164 +** <dd>^An SQLITE_TRACE_STMT callback is invoked when a prepared statement
3165 +** first begins running and possibly at other times during the
3166 +** execution of the prepared statement, such as at the start of each
3167 +** trigger subprogram. ^The P argument is a pointer to the
3168 +** [prepared statement]. ^The X argument is a pointer to a string which
3169 +** is the unexpanded SQL text of the prepared statement or an SQL comment
3170 +** that indicates the invocation of a trigger. ^The callback can compute
3171 +** the same text that would have been returned by the legacy [sqlite3_trace()]
3172 +** interface by using the X argument when X begins with "--" and invoking
3173 +** [sqlite3_expanded_sql(P)] otherwise.
3174 +**
3175 +** [[SQLITE_TRACE_PROFILE]] <dt>SQLITE_TRACE_PROFILE</dt>
3176 +** <dd>^An SQLITE_TRACE_PROFILE callback provides approximately the same
3177 +** information as is provided by the [sqlite3_profile()] callback.
3178 +** ^The P argument is a pointer to the [prepared statement] and the
3179 +** X argument points to a 64-bit integer which is the estimated of
3180 +** the number of nanosecond that the prepared statement took to run.
3181 +** ^The SQLITE_TRACE_PROFILE callback is invoked when the statement finishes.
3182 +**
3183 +** [[SQLITE_TRACE_ROW]] <dt>SQLITE_TRACE_ROW</dt>
3184 +** <dd>^An SQLITE_TRACE_ROW callback is invoked whenever a prepared
3185 +** statement generates a single row of result.
3186 +** ^The P argument is a pointer to the [prepared statement] and the
3187 +** X argument is unused.
3188 +**
3189 +** [[SQLITE_TRACE_CLOSE]] <dt>SQLITE_TRACE_CLOSE</dt>
3190 +** <dd>^An SQLITE_TRACE_CLOSE callback is invoked when a database
3191 +** connection closes.
3192 +** ^The P argument is a pointer to the [database connection] object
3193 +** and the X argument is unused.
3194 +** </dl>
3195 +*/
3196 +#define SQLITE_TRACE_STMT 0x01
3197 +#define SQLITE_TRACE_PROFILE 0x02
3198 +#define SQLITE_TRACE_ROW 0x04
3199 +#define SQLITE_TRACE_CLOSE 0x08
3200 +
3201 +/*
3202 +** CAPI3REF: SQL Trace Hook
3203 +** METHOD: sqlite3
3204 +**
3205 +** ^The sqlite3_trace_v2(D,M,X,P) interface registers a trace callback
3206 +** function X against [database connection] D, using property mask M
3207 +** and context pointer P. ^If the X callback is
3208 +** NULL or if the M mask is zero, then tracing is disabled. The
3209 +** M argument should be the bitwise OR-ed combination of
3210 +** zero or more [SQLITE_TRACE] constants.
3211 +**
3212 +** ^Each call to either sqlite3_trace() or sqlite3_trace_v2() overrides
3213 +** (cancels) any prior calls to sqlite3_trace() or sqlite3_trace_v2().
3214 +**
3215 +** ^The X callback is invoked whenever any of the events identified by
3216 +** mask M occur. ^The integer return value from the callback is currently
3217 +** ignored, though this may change in future releases. Callback
3218 +** implementations should return zero to ensure future compatibility.
3219 +**
3220 +** ^A trace callback is invoked with four arguments: callback(T,C,P,X).
3221 +** ^The T argument is one of the [SQLITE_TRACE]
3222 +** constants to indicate why the callback was invoked.
3223 +** ^The C argument is a copy of the context pointer.
3224 +** The P and X arguments are pointers whose meanings depend on T.
3225 +**
3226 +** The sqlite3_trace_v2() interface is intended to replace the legacy
3227 +** interfaces [sqlite3_trace()] and [sqlite3_profile()], both of which
3228 +** are deprecated.
3229 +*/
3230 +SQLITE_API int sqlite3_trace_v2(
3231 + sqlite3*,
3232 + unsigned uMask,
3233 + int(*xCallback)(unsigned,void*,void*,void*),
3234 + void *pCtx
3235 +);
3236 +
3237 +/*
3238 +** CAPI3REF: Query Progress Callbacks
3239 +** METHOD: sqlite3
3240 +**
3241 +** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
3242 +** function X to be invoked periodically during long running calls to
3243 +** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
3244 +** database connection D. An example use for this
3245 +** interface is to keep a GUI updated during a large query.
3246 +**
3247 +** ^The parameter P is passed through as the only parameter to the
3248 +** callback function X. ^The parameter N is the approximate number of
3249 +** [virtual machine instructions] that are evaluated between successive
3250 +** invocations of the callback X. ^If N is less than one then the progress
3251 +** handler is disabled.
3252 +**
3253 +** ^Only a single progress handler may be defined at one time per
3254 +** [database connection]; setting a new progress handler cancels the
3255 +** old one. ^Setting parameter X to NULL disables the progress handler.
3256 +** ^The progress handler is also disabled by setting N to a value less
3257 +** than 1.
3258 +**
3259 +** ^If the progress callback returns non-zero, the operation is
3260 +** interrupted. This feature can be used to implement a
3261 +** "Cancel" button on a GUI progress dialog box.
3262 +**
3263 +** The progress handler callback must not do anything that will modify
3264 +** the database connection that invoked the progress handler.
3265 +** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
3266 +** database connections for the meaning of "modify" in this paragraph.
3267 +**
3268 +*/
3269 +SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
3270 +
3271 +/*
3272 +** CAPI3REF: Opening A New Database Connection
3273 +** CONSTRUCTOR: sqlite3
3274 +**
3275 +** ^These routines open an SQLite database file as specified by the
3276 +** filename argument. ^The filename argument is interpreted as UTF-8 for
3277 +** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
3278 +** order for sqlite3_open16(). ^(A [database connection] handle is usually
3279 +** returned in *ppDb, even if an error occurs. The only exception is that
3280 +** if SQLite is unable to allocate memory to hold the [sqlite3] object,
3281 +** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
3282 +** object.)^ ^(If the database is opened (and/or created) successfully, then
3283 +** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The
3284 +** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
3285 +** an English language description of the error following a failure of any
3286 +** of the sqlite3_open() routines.
3287 +**
3288 +** ^The default encoding will be UTF-8 for databases created using
3289 +** sqlite3_open() or sqlite3_open_v2(). ^The default encoding for databases
3290 +** created using sqlite3_open16() will be UTF-16 in the native byte order.
3291 +**
3292 +** Whether or not an error occurs when it is opened, resources
3293 +** associated with the [database connection] handle should be released by
3294 +** passing it to [sqlite3_close()] when it is no longer required.
3295 +**
3296 +** The sqlite3_open_v2() interface works like sqlite3_open()
3297 +** except that it accepts two additional parameters for additional control
3298 +** over the new database connection. ^(The flags parameter to
3299 +** sqlite3_open_v2() must include, at a minimum, one of the following
3300 +** three flag combinations:)^
3301 +**
3302 +** <dl>
3303 +** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
3304 +** <dd>The database is opened in read-only mode. If the database does not
3305 +** already exist, an error is returned.</dd>)^
3306 +**
3307 +** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
3308 +** <dd>The database is opened for reading and writing if possible, or reading
3309 +** only if the file is write protected by the operating system. In either
3310 +** case the database must already exist, otherwise an error is returned.</dd>)^
3311 +**
3312 +** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
3313 +** <dd>The database is opened for reading and writing, and is created if
3314 +** it does not already exist. This is the behavior that is always used for
3315 +** sqlite3_open() and sqlite3_open16().</dd>)^
3316 +** </dl>
3317 +**
3318 +** In addition to the required flags, the following optional flags are
3319 +** also supported:
3320 +**
3321 +** <dl>
3322 +** ^(<dt>[SQLITE_OPEN_URI]</dt>
3323 +** <dd>The filename can be interpreted as a URI if this flag is set.</dd>)^
3324 +**
3325 +** ^(<dt>[SQLITE_OPEN_MEMORY]</dt>
3326 +** <dd>The database will be opened as an in-memory database. The database
3327 +** is named by the "filename" argument for the purposes of cache-sharing,
3328 +** if shared cache mode is enabled, but the "filename" is otherwise ignored.
3329 +** </dd>)^
3330 +**
3331 +** ^(<dt>[SQLITE_OPEN_NOMUTEX]</dt>
3332 +** <dd>The new database connection will use the "multi-thread"
3333 +** [threading mode].)^ This means that separate threads are allowed
3334 +** to use SQLite at the same time, as long as each thread is using
3335 +** a different [database connection].
3336 +**
3337 +** ^(<dt>[SQLITE_OPEN_FULLMUTEX]</dt>
3338 +** <dd>The new database connection will use the "serialized"
3339 +** [threading mode].)^ This means the multiple threads can safely
3340 +** attempt to use the same database connection at the same time.
3341 +** (Mutexes will block any actual concurrency, but in this mode
3342 +** there is no harm in trying.)
3343 +**
3344 +** ^(<dt>[SQLITE_OPEN_SHAREDCACHE]</dt>
3345 +** <dd>The database is opened [shared cache] enabled, overriding
3346 +** the default shared cache setting provided by
3347 +** [sqlite3_enable_shared_cache()].)^
3348 +**
3349 +** ^(<dt>[SQLITE_OPEN_PRIVATECACHE]</dt>
3350 +** <dd>The database is opened [shared cache] disabled, overriding
3351 +** the default shared cache setting provided by
3352 +** [sqlite3_enable_shared_cache()].)^
3353 +**
3354 +** [[OPEN_NOFOLLOW]] ^(<dt>[SQLITE_OPEN_NOFOLLOW]</dt>
3355 +** <dd>The database filename is not allowed to be a symbolic link</dd>
3356 +** </dl>)^
3357 +**
3358 +** If the 3rd parameter to sqlite3_open_v2() is not one of the
3359 +** required combinations shown above optionally combined with other
3360 +** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
3361 +** then the behavior is undefined.
3362 +**
3363 +** ^The fourth parameter to sqlite3_open_v2() is the name of the
3364 +** [sqlite3_vfs] object that defines the operating system interface that
3365 +** the new database connection should use. ^If the fourth parameter is
3366 +** a NULL pointer then the default [sqlite3_vfs] object is used.
3367 +**
3368 +** ^If the filename is ":memory:", then a private, temporary in-memory database
3369 +** is created for the connection. ^This in-memory database will vanish when
3370 +** the database connection is closed. Future versions of SQLite might
3371 +** make use of additional special filenames that begin with the ":" character.
3372 +** It is recommended that when a database filename actually does begin with
3373 +** a ":" character you should prefix the filename with a pathname such as
3374 +** "./" to avoid ambiguity.
3375 +**
3376 +** ^If the filename is an empty string, then a private, temporary
3377 +** on-disk database will be created. ^This private database will be
3378 +** automatically deleted as soon as the database connection is closed.
3379 +**
3380 +** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
3381 +**
3382 +** ^If [URI filename] interpretation is enabled, and the filename argument
3383 +** begins with "file:", then the filename is interpreted as a URI. ^URI
3384 +** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
3385 +** set in the third argument to sqlite3_open_v2(), or if it has
3386 +** been enabled globally using the [SQLITE_CONFIG_URI] option with the
3387 +** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
3388 +** URI filename interpretation is turned off
3389 +** by default, but future releases of SQLite might enable URI filename
3390 +** interpretation by default. See "[URI filenames]" for additional
3391 +** information.
3392 +**
3393 +** URI filenames are parsed according to RFC 3986. ^If the URI contains an
3394 +** authority, then it must be either an empty string or the string
3395 +** "localhost". ^If the authority is not an empty string or "localhost", an
3396 +** error is returned to the caller. ^The fragment component of a URI, if
3397 +** present, is ignored.
3398 +**
3399 +** ^SQLite uses the path component of the URI as the name of the disk file
3400 +** which contains the database. ^If the path begins with a '/' character,
3401 +** then it is interpreted as an absolute path. ^If the path does not begin
3402 +** with a '/' (meaning that the authority section is omitted from the URI)
3403 +** then the path is interpreted as a relative path.
3404 +** ^(On windows, the first component of an absolute path
3405 +** is a drive specification (e.g. "C:").)^
3406 +**
3407 +** [[core URI query parameters]]
3408 +** The query component of a URI may contain parameters that are interpreted
3409 +** either by SQLite itself, or by a [VFS | custom VFS implementation].
3410 +** SQLite and its built-in [VFSes] interpret the
3411 +** following query parameters:
3412 +**
3413 +** <ul>
3414 +** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
3415 +** a VFS object that provides the operating system interface that should
3416 +** be used to access the database file on disk. ^If this option is set to
3417 +** an empty string the default VFS object is used. ^Specifying an unknown
3418 +** VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
3419 +** present, then the VFS specified by the option takes precedence over
3420 +** the value passed as the fourth parameter to sqlite3_open_v2().
3421 +**
3422 +** <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",
3423 +** "rwc", or "memory". Attempting to set it to any other value is
3424 +** an error)^.
3425 +** ^If "ro" is specified, then the database is opened for read-only
3426 +** access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the
3427 +** third argument to sqlite3_open_v2(). ^If the mode option is set to
3428 +** "rw", then the database is opened for read-write (but not create)
3429 +** access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had
3430 +** been set. ^Value "rwc" is equivalent to setting both
3431 +** SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If the mode option is
3432 +** set to "memory" then a pure [in-memory database] that never reads
3433 +** or writes from disk is used. ^It is an error to specify a value for
3434 +** the mode parameter that is less restrictive than that specified by
3435 +** the flags passed in the third parameter to sqlite3_open_v2().
3436 +**
3437 +** <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
3438 +** "private". ^Setting it to "shared" is equivalent to setting the
3439 +** SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
3440 +** sqlite3_open_v2(). ^Setting the cache parameter to "private" is
3441 +** equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
3442 +** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
3443 +** a URI filename, its value overrides any behavior requested by setting
3444 +** SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
3445 +**
3446 +** <li> <b>psow</b>: ^The psow parameter indicates whether or not the
3447 +** [powersafe overwrite] property does or does not apply to the
3448 +** storage media on which the database file resides.
3449 +**
3450 +** <li> <b>nolock</b>: ^The nolock parameter is a boolean query parameter
3451 +** which if set disables file locking in rollback journal modes. This
3452 +** is useful for accessing a database on a filesystem that does not
3453 +** support locking. Caution: Database corruption might result if two
3454 +** or more processes write to the same database and any one of those
3455 +** processes uses nolock=1.
3456 +**
3457 +** <li> <b>immutable</b>: ^The immutable parameter is a boolean query
3458 +** parameter that indicates that the database file is stored on
3459 +** read-only media. ^When immutable is set, SQLite assumes that the
3460 +** database file cannot be changed, even by a process with higher
3461 +** privilege, and so the database is opened read-only and all locking
3462 +** and change detection is disabled. Caution: Setting the immutable
3463 +** property on a database file that does in fact change can result
3464 +** in incorrect query results and/or [SQLITE_CORRUPT] errors.
3465 +** See also: [SQLITE_IOCAP_IMMUTABLE].
3466 +**
3467 +** </ul>
3468 +**
3469 +** ^Specifying an unknown parameter in the query component of a URI is not an
3470 +** error. Future versions of SQLite might understand additional query
3471 +** parameters. See "[query parameters with special meaning to SQLite]" for
3472 +** additional information.
3473 +**
3474 +** [[URI filename examples]] <h3>URI filename examples</h3>
3475 +**
3476 +** <table border="1" align=center cellpadding=5>
3477 +** <tr><th> URI filenames <th> Results
3478 +** <tr><td> file:data.db <td>
3479 +** Open the file "data.db" in the current directory.
3480 +** <tr><td> file:/home/fred/data.db<br>
3481 +** file:///home/fred/data.db <br>
3482 +** file://localhost/home/fred/data.db <br> <td>
3483 +** Open the database file "/home/fred/data.db".
3484 +** <tr><td> file://darkstar/home/fred/data.db <td>
3485 +** An error. "darkstar" is not a recognized authority.
3486 +** <tr><td style="white-space:nowrap">
3487 +** file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
3488 +** <td> Windows only: Open the file "data.db" on fred's desktop on drive
3489 +** C:. Note that the %20 escaping in this example is not strictly
3490 +** necessary - space characters can be used literally
3491 +** in URI filenames.
3492 +** <tr><td> file:data.db?mode=ro&cache=private <td>
3493 +** Open file "data.db" in the current directory for read-only access.
3494 +** Regardless of whether or not shared-cache mode is enabled by
3495 +** default, use a private cache.
3496 +** <tr><td> file:/home/fred/data.db?vfs=unix-dotfile <td>
3497 +** Open file "/home/fred/data.db". Use the special VFS "unix-dotfile"
3498 +** that uses dot-files in place of posix advisory locking.
3499 +** <tr><td> file:data.db?mode=readonly <td>
3500 +** An error. "readonly" is not a valid option for the "mode" parameter.
3501 +** </table>
3502 +**
3503 +** ^URI hexadecimal escape sequences (%HH) are supported within the path and
3504 +** query components of a URI. A hexadecimal escape sequence consists of a
3505 +** percent sign - "%" - followed by exactly two hexadecimal digits
3506 +** specifying an octet value. ^Before the path or query components of a
3507 +** URI filename are interpreted, they are encoded using UTF-8 and all
3508 +** hexadecimal escape sequences replaced by a single byte containing the
3509 +** corresponding octet. If this process generates an invalid UTF-8 encoding,
3510 +** the results are undefined.
3511 +**
3512 +** <b>Note to Windows users:</b> The encoding used for the filename argument
3513 +** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
3514 +** codepage is currently defined. Filenames containing international
3515 +** characters must be converted to UTF-8 prior to passing them into
3516 +** sqlite3_open() or sqlite3_open_v2().
3517 +**
3518 +** <b>Note to Windows Runtime users:</b> The temporary directory must be set
3519 +** prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various
3520 +** features that require the use of temporary files may fail.
3521 +**
3522 +** See also: [sqlite3_temp_directory]
3523 +*/
3524 +SQLITE_API int sqlite3_open(
3525 + const char *filename, /* Database filename (UTF-8) */
3526 + sqlite3 **ppDb /* OUT: SQLite db handle */
3527 +);
3528 +SQLITE_API int sqlite3_open16(
3529 + const void *filename, /* Database filename (UTF-16) */
3530 + sqlite3 **ppDb /* OUT: SQLite db handle */
3531 +);
3532 +SQLITE_API int sqlite3_open_v2(
3533 + const char *filename, /* Database filename (UTF-8) */
3534 + sqlite3 **ppDb, /* OUT: SQLite db handle */
3535 + int flags, /* Flags */
3536 + const char *zVfs /* Name of VFS module to use */
3537 +);
3538 +
3539 +/*
3540 +** CAPI3REF: Obtain Values For URI Parameters
3541 +**
3542 +** These are utility routines, useful to [VFS|custom VFS implementations],
3543 +** that check if a database file was a URI that contained a specific query
3544 +** parameter, and if so obtains the value of that query parameter.
3545 +**
3546 +** The first parameter to these interfaces (hereafter referred to
3547 +** as F) must be one of:
3548 +** <ul>
3549 +** <li> A database filename pointer created by the SQLite core and
3550 +** passed into the xOpen() method of a VFS implemention, or
3551 +** <li> A filename obtained from [sqlite3_db_filename()], or
3552 +** <li> A new filename constructed using [sqlite3_create_filename()].
3553 +** </ul>
3554 +** If the F parameter is not one of the above, then the behavior is
3555 +** undefined and probably undesirable. Older versions of SQLite were
3556 +** more tolerant of invalid F parameters than newer versions.
3557 +**
3558 +** If F is a suitable filename (as described in the previous paragraph)
3559 +** and if P is the name of the query parameter, then
3560 +** sqlite3_uri_parameter(F,P) returns the value of the P
3561 +** parameter if it exists or a NULL pointer if P does not appear as a
3562 +** query parameter on F. If P is a query parameter of F and it
3563 +** has no explicit value, then sqlite3_uri_parameter(F,P) returns
3564 +** a pointer to an empty string.
3565 +**
3566 +** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
3567 +** parameter and returns true (1) or false (0) according to the value
3568 +** of P. The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
3569 +** value of query parameter P is one of "yes", "true", or "on" in any
3570 +** case or if the value begins with a non-zero number. The
3571 +** sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
3572 +** query parameter P is one of "no", "false", or "off" in any case or
3573 +** if the value begins with a numeric zero. If P is not a query
3574 +** parameter on F or if the value of P does not match any of the
3575 +** above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).
3576 +**
3577 +** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
3578 +** 64-bit signed integer and returns that integer, or D if P does not
3579 +** exist. If the value of P is something other than an integer, then
3580 +** zero is returned.
3581 +**
3582 +** The sqlite3_uri_key(F,N) returns a pointer to the name (not
3583 +** the value) of the N-th query parameter for filename F, or a NULL
3584 +** pointer if N is less than zero or greater than the number of query
3585 +** parameters minus 1. The N value is zero-based so N should be 0 to obtain
3586 +** the name of the first query parameter, 1 for the second parameter, and
3587 +** so forth.
3588 +**
3589 +** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
3590 +** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and
3591 +** is not a database file pathname pointer that the SQLite core passed
3592 +** into the xOpen VFS method, then the behavior of this routine is undefined
3593 +** and probably undesirable.
3594 +**
3595 +** Beginning with SQLite [version 3.31.0] ([dateof:3.31.0]) the input F
3596 +** parameter can also be the name of a rollback journal file or WAL file
3597 +** in addition to the main database file. Prior to version 3.31.0, these
3598 +** routines would only work if F was the name of the main database file.
3599 +** When the F parameter is the name of the rollback journal or WAL file,
3600 +** it has access to all the same query parameters as were found on the
3601 +** main database file.
3602 +**
3603 +** See the [URI filename] documentation for additional information.
3604 +*/
3605 +SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
3606 +SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
3607 +SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
3608 +SQLITE_API const char *sqlite3_uri_key(const char *zFilename, int N);
3609 +
3610 +/*
3611 +** CAPI3REF: Translate filenames
3612 +**
3613 +** These routines are available to [VFS|custom VFS implementations] for
3614 +** translating filenames between the main database file, the journal file,
3615 +** and the WAL file.
3616 +**
3617 +** If F is the name of an sqlite database file, journal file, or WAL file
3618 +** passed by the SQLite core into the VFS, then sqlite3_filename_database(F)
3619 +** returns the name of the corresponding database file.
3620 +**
3621 +** If F is the name of an sqlite database file, journal file, or WAL file
3622 +** passed by the SQLite core into the VFS, or if F is a database filename
3623 +** obtained from [sqlite3_db_filename()], then sqlite3_filename_journal(F)
3624 +** returns the name of the corresponding rollback journal file.
3625 +**
3626 +** If F is the name of an sqlite database file, journal file, or WAL file
3627 +** that was passed by the SQLite core into the VFS, or if F is a database
3628 +** filename obtained from [sqlite3_db_filename()], then
3629 +** sqlite3_filename_wal(F) returns the name of the corresponding
3630 +** WAL file.
3631 +**
3632 +** In all of the above, if F is not the name of a database, journal or WAL
3633 +** filename passed into the VFS from the SQLite core and F is not the
3634 +** return value from [sqlite3_db_filename()], then the result is
3635 +** undefined and is likely a memory access violation.
3636 +*/
3637 +SQLITE_API const char *sqlite3_filename_database(const char*);
3638 +SQLITE_API const char *sqlite3_filename_journal(const char*);
3639 +SQLITE_API const char *sqlite3_filename_wal(const char*);
3640 +
3641 +/*
3642 +** CAPI3REF: Database File Corresponding To A Journal
3643 +**
3644 +** ^If X is the name of a rollback or WAL-mode journal file that is
3645 +** passed into the xOpen method of [sqlite3_vfs], then
3646 +** sqlite3_database_file_object(X) returns a pointer to the [sqlite3_file]
3647 +** object that represents the main database file.
3648 +**
3649 +** This routine is intended for use in custom [VFS] implementations
3650 +** only. It is not a general-purpose interface.
3651 +** The argument sqlite3_file_object(X) must be a filename pointer that
3652 +** has been passed into [sqlite3_vfs].xOpen method where the
3653 +** flags parameter to xOpen contains one of the bits
3654 +** [SQLITE_OPEN_MAIN_JOURNAL] or [SQLITE_OPEN_WAL]. Any other use
3655 +** of this routine results in undefined and probably undesirable
3656 +** behavior.
3657 +*/
3658 +SQLITE_API sqlite3_file *sqlite3_database_file_object(const char*);
3659 +
3660 +/*
3661 +** CAPI3REF: Create and Destroy VFS Filenames
3662 +**
3663 +** These interfces are provided for use by [VFS shim] implementations and
3664 +** are not useful outside of that context.
3665 +**
3666 +** The sqlite3_create_filename(D,J,W,N,P) allocates memory to hold a version of
3667 +** database filename D with corresponding journal file J and WAL file W and
3668 +** with N URI parameters key/values pairs in the array P. The result from
3669 +** sqlite3_create_filename(D,J,W,N,P) is a pointer to a database filename that
3670 +** is safe to pass to routines like:
3671 +** <ul>
3672 +** <li> [sqlite3_uri_parameter()],
3673 +** <li> [sqlite3_uri_boolean()],
3674 +** <li> [sqlite3_uri_int64()],
3675 +** <li> [sqlite3_uri_key()],
3676 +** <li> [sqlite3_filename_database()],
3677 +** <li> [sqlite3_filename_journal()], or
3678 +** <li> [sqlite3_filename_wal()].
3679 +** </ul>
3680 +** If a memory allocation error occurs, sqlite3_create_filename() might
3681 +** return a NULL pointer. The memory obtained from sqlite3_create_filename(X)
3682 +** must be released by a corresponding call to sqlite3_free_filename(Y).
3683 +**
3684 +** The P parameter in sqlite3_create_filename(D,J,W,N,P) should be an array
3685 +** of 2*N pointers to strings. Each pair of pointers in this array corresponds
3686 +** to a key and value for a query parameter. The P parameter may be a NULL
3687 +** pointer if N is zero. None of the 2*N pointers in the P array may be
3688 +** NULL pointers and key pointers should not be empty strings.
3689 +** None of the D, J, or W parameters to sqlite3_create_filename(D,J,W,N,P) may
3690 +** be NULL pointers, though they can be empty strings.
3691 +**
3692 +** The sqlite3_free_filename(Y) routine releases a memory allocation
3693 +** previously obtained from sqlite3_create_filename(). Invoking
3694 +** sqlite3_free_filename(Y) where Y is a NULL pointer is a harmless no-op.
3695 +**
3696 +** If the Y parameter to sqlite3_free_filename(Y) is anything other
3697 +** than a NULL pointer or a pointer previously acquired from
3698 +** sqlite3_create_filename(), then bad things such as heap
3699 +** corruption or segfaults may occur. The value Y should be
3700 +** used again after sqlite3_free_filename(Y) has been called. This means
3701 +** that if the [sqlite3_vfs.xOpen()] method of a VFS has been called using Y,
3702 +** then the corresponding [sqlite3_module.xClose() method should also be
3703 +** invoked prior to calling sqlite3_free_filename(Y).
3704 +*/
3705 +SQLITE_API char *sqlite3_create_filename(
3706 + const char *zDatabase,
3707 + const char *zJournal,
3708 + const char *zWal,
3709 + int nParam,
3710 + const char **azParam
3711 +);
3712 +SQLITE_API void sqlite3_free_filename(char*);
3713 +
3714 +/*
3715 +** CAPI3REF: Error Codes And Messages
3716 +** METHOD: sqlite3
3717 +**
3718 +** ^If the most recent sqlite3_* API call associated with
3719 +** [database connection] D failed, then the sqlite3_errcode(D) interface
3720 +** returns the numeric [result code] or [extended result code] for that
3721 +** API call.
3722 +** ^The sqlite3_extended_errcode()
3723 +** interface is the same except that it always returns the
3724 +** [extended result code] even when extended result codes are
3725 +** disabled.
3726 +**
3727 +** The values returned by sqlite3_errcode() and/or
3728 +** sqlite3_extended_errcode() might change with each API call.
3729 +** Except, there are some interfaces that are guaranteed to never
3730 +** change the value of the error code. The error-code preserving
3731 +** interfaces are:
3732 +**
3733 +** <ul>
3734 +** <li> sqlite3_errcode()
3735 +** <li> sqlite3_extended_errcode()
3736 +** <li> sqlite3_errmsg()
3737 +** <li> sqlite3_errmsg16()
3738 +** </ul>
3739 +**
3740 +** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
3741 +** text that describes the error, as either UTF-8 or UTF-16 respectively.
3742 +** ^(Memory to hold the error message string is managed internally.
3743 +** The application does not need to worry about freeing the result.
3744 +** However, the error string might be overwritten or deallocated by
3745 +** subsequent calls to other SQLite interface functions.)^
3746 +**
3747 +** ^The sqlite3_errstr() interface returns the English-language text
3748 +** that describes the [result code], as UTF-8.
3749 +** ^(Memory to hold the error message string is managed internally
3750 +** and must not be freed by the application)^.
3751 +**
3752 +** When the serialized [threading mode] is in use, it might be the
3753 +** case that a second error occurs on a separate thread in between
3754 +** the time of the first error and the call to these interfaces.
3755 +** When that happens, the second error will be reported since these
3756 +** interfaces always report the most recent result. To avoid
3757 +** this, each thread can obtain exclusive use of the [database connection] D
3758 +** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
3759 +** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
3760 +** all calls to the interfaces listed here are completed.
3761 +**
3762 +** If an interface fails with SQLITE_MISUSE, that means the interface
3763 +** was invoked incorrectly by the application. In that case, the
3764 +** error code and message may or may not be set.
3765 +*/
3766 +SQLITE_API int sqlite3_errcode(sqlite3 *db);
3767 +SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
3768 +SQLITE_API const char *sqlite3_errmsg(sqlite3*);
3769 +SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
3770 +SQLITE_API const char *sqlite3_errstr(int);
3771 +
3772 +/*
3773 +** CAPI3REF: Prepared Statement Object
3774 +** KEYWORDS: {prepared statement} {prepared statements}
3775 +**
3776 +** An instance of this object represents a single SQL statement that
3777 +** has been compiled into binary form and is ready to be evaluated.
3778 +**
3779 +** Think of each SQL statement as a separate computer program. The
3780 +** original SQL text is source code. A prepared statement object
3781 +** is the compiled object code. All SQL must be converted into a
3782 +** prepared statement before it can be run.
3783 +**
3784 +** The life-cycle of a prepared statement object usually goes like this:
3785 +**
3786 +** <ol>
3787 +** <li> Create the prepared statement object using [sqlite3_prepare_v2()].
3788 +** <li> Bind values to [parameters] using the sqlite3_bind_*()
3789 +** interfaces.
3790 +** <li> Run the SQL by calling [sqlite3_step()] one or more times.
3791 +** <li> Reset the prepared statement using [sqlite3_reset()] then go back
3792 +** to step 2. Do this zero or more times.
3793 +** <li> Destroy the object using [sqlite3_finalize()].
3794 +** </ol>
3795 +*/
3796 +typedef struct sqlite3_stmt sqlite3_stmt;
3797 +
3798 +/*
3799 +** CAPI3REF: Run-time Limits
3800 +** METHOD: sqlite3
3801 +**
3802 +** ^(This interface allows the size of various constructs to be limited
3803 +** on a connection by connection basis. The first parameter is the
3804 +** [database connection] whose limit is to be set or queried. The
3805 +** second parameter is one of the [limit categories] that define a
3806 +** class of constructs to be size limited. The third parameter is the
3807 +** new limit for that construct.)^
3808 +**
3809 +** ^If the new limit is a negative number, the limit is unchanged.
3810 +** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
3811 +** [limits | hard upper bound]
3812 +** set at compile-time by a C preprocessor macro called
3813 +** [limits | SQLITE_MAX_<i>NAME</i>].
3814 +** (The "_LIMIT_" in the name is changed to "_MAX_".))^
3815 +** ^Attempts to increase a limit above its hard upper bound are
3816 +** silently truncated to the hard upper bound.
3817 +**
3818 +** ^Regardless of whether or not the limit was changed, the
3819 +** [sqlite3_limit()] interface returns the prior value of the limit.
3820 +** ^Hence, to find the current value of a limit without changing it,
3821 +** simply invoke this interface with the third parameter set to -1.
3822 +**
3823 +** Run-time limits are intended for use in applications that manage
3824 +** both their own internal database and also databases that are controlled
3825 +** by untrusted external sources. An example application might be a
3826 +** web browser that has its own databases for storing history and
3827 +** separate databases controlled by JavaScript applications downloaded
3828 +** off the Internet. The internal databases can be given the
3829 +** large, default limits. Databases managed by external sources can
3830 +** be given much smaller limits designed to prevent a denial of service
3831 +** attack. Developers might also want to use the [sqlite3_set_authorizer()]
3832 +** interface to further control untrusted SQL. The size of the database
3833 +** created by an untrusted script can be contained using the
3834 +** [max_page_count] [PRAGMA].
3835 +**
3836 +** New run-time limit categories may be added in future releases.
3837 +*/
3838 +SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
3839 +
3840 +/*
3841 +** CAPI3REF: Run-Time Limit Categories
3842 +** KEYWORDS: {limit category} {*limit categories}
3843 +**
3844 +** These constants define various performance limits
3845 +** that can be lowered at run-time using [sqlite3_limit()].
3846 +** The synopsis of the meanings of the various limits is shown below.
3847 +** Additional information is available at [limits | Limits in SQLite].
3848 +**
3849 +** <dl>
3850 +** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
3851 +** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
3852 +**
3853 +** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
3854 +** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
3855 +**
3856 +** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
3857 +** <dd>The maximum number of columns in a table definition or in the
3858 +** result set of a [SELECT] or the maximum number of columns in an index
3859 +** or in an ORDER BY or GROUP BY clause.</dd>)^
3860 +**
3861 +** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
3862 +** <dd>The maximum depth of the parse tree on any expression.</dd>)^
3863 +**
3864 +** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
3865 +** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
3866 +**
3867 +** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
3868 +** <dd>The maximum number of instructions in a virtual machine program
3869 +** used to implement an SQL statement. If [sqlite3_prepare_v2()] or
3870 +** the equivalent tries to allocate space for more than this many opcodes
3871 +** in a single prepared statement, an SQLITE_NOMEM error is returned.</dd>)^
3872 +**
3873 +** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
3874 +** <dd>The maximum number of arguments on a function.</dd>)^
3875 +**
3876 +** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
3877 +** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
3878 +**
3879 +** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
3880 +** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
3881 +** <dd>The maximum length of the pattern argument to the [LIKE] or
3882 +** [GLOB] operators.</dd>)^
3883 +**
3884 +** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
3885 +** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
3886 +** <dd>The maximum index number of any [parameter] in an SQL statement.)^
3887 +**
3888 +** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
3889 +** <dd>The maximum depth of recursion for triggers.</dd>)^
3890 +**
3891 +** [[SQLITE_LIMIT_WORKER_THREADS]] ^(<dt>SQLITE_LIMIT_WORKER_THREADS</dt>
3892 +** <dd>The maximum number of auxiliary worker threads that a single
3893 +** [prepared statement] may start.</dd>)^
3894 +** </dl>
3895 +*/
3896 +#define SQLITE_LIMIT_LENGTH 0
3897 +#define SQLITE_LIMIT_SQL_LENGTH 1
3898 +#define SQLITE_LIMIT_COLUMN 2
3899 +#define SQLITE_LIMIT_EXPR_DEPTH 3
3900 +#define SQLITE_LIMIT_COMPOUND_SELECT 4
3901 +#define SQLITE_LIMIT_VDBE_OP 5
3902 +#define SQLITE_LIMIT_FUNCTION_ARG 6
3903 +#define SQLITE_LIMIT_ATTACHED 7
3904 +#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8
3905 +#define SQLITE_LIMIT_VARIABLE_NUMBER 9
3906 +#define SQLITE_LIMIT_TRIGGER_DEPTH 10
3907 +#define SQLITE_LIMIT_WORKER_THREADS 11
3908 +
3909 +/*
3910 +** CAPI3REF: Prepare Flags
3911 +**
3912 +** These constants define various flags that can be passed into
3913 +** "prepFlags" parameter of the [sqlite3_prepare_v3()] and
3914 +** [sqlite3_prepare16_v3()] interfaces.
3915 +**
3916 +** New flags may be added in future releases of SQLite.
3917 +**
3918 +** <dl>
3919 +** [[SQLITE_PREPARE_PERSISTENT]] ^(<dt>SQLITE_PREPARE_PERSISTENT</dt>
3920 +** <dd>The SQLITE_PREPARE_PERSISTENT flag is a hint to the query planner
3921 +** that the prepared statement will be retained for a long time and
3922 +** probably reused many times.)^ ^Without this flag, [sqlite3_prepare_v3()]
3923 +** and [sqlite3_prepare16_v3()] assume that the prepared statement will
3924 +** be used just once or at most a few times and then destroyed using
3925 +** [sqlite3_finalize()] relatively soon. The current implementation acts
3926 +** on this hint by avoiding the use of [lookaside memory] so as not to
3927 +** deplete the limited store of lookaside memory. Future versions of
3928 +** SQLite may act on this hint differently.
3929 +**
3930 +** [[SQLITE_PREPARE_NORMALIZE]] <dt>SQLITE_PREPARE_NORMALIZE</dt>
3931 +** <dd>The SQLITE_PREPARE_NORMALIZE flag is a no-op. This flag used
3932 +** to be required for any prepared statement that wanted to use the
3933 +** [sqlite3_normalized_sql()] interface. However, the
3934 +** [sqlite3_normalized_sql()] interface is now available to all
3935 +** prepared statements, regardless of whether or not they use this
3936 +** flag.
3937 +**
3938 +** [[SQLITE_PREPARE_NO_VTAB]] <dt>SQLITE_PREPARE_NO_VTAB</dt>
3939 +** <dd>The SQLITE_PREPARE_NO_VTAB flag causes the SQL compiler
3940 +** to return an error (error code SQLITE_ERROR) if the statement uses
3941 +** any virtual tables.
3942 +** </dl>
3943 +*/
3944 +#define SQLITE_PREPARE_PERSISTENT 0x01
3945 +#define SQLITE_PREPARE_NORMALIZE 0x02
3946 +#define SQLITE_PREPARE_NO_VTAB 0x04
3947 +
3948 +/*
3949 +** CAPI3REF: Compiling An SQL Statement
3950 +** KEYWORDS: {SQL statement compiler}
3951 +** METHOD: sqlite3
3952 +** CONSTRUCTOR: sqlite3_stmt
3953 +**
3954 +** To execute an SQL statement, it must first be compiled into a byte-code
3955 +** program using one of these routines. Or, in other words, these routines
3956 +** are constructors for the [prepared statement] object.
3957 +**
3958 +** The preferred routine to use is [sqlite3_prepare_v2()]. The
3959 +** [sqlite3_prepare()] interface is legacy and should be avoided.
3960 +** [sqlite3_prepare_v3()] has an extra "prepFlags" option that is used
3961 +** for special purposes.
3962 +**
3963 +** The use of the UTF-8 interfaces is preferred, as SQLite currently
3964 +** does all parsing using UTF-8. The UTF-16 interfaces are provided
3965 +** as a convenience. The UTF-16 interfaces work by converting the
3966 +** input text into UTF-8, then invoking the corresponding UTF-8 interface.
3967 +**
3968 +** The first argument, "db", is a [database connection] obtained from a
3969 +** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
3970 +** [sqlite3_open16()]. The database connection must not have been closed.
3971 +**
3972 +** The second argument, "zSql", is the statement to be compiled, encoded
3973 +** as either UTF-8 or UTF-16. The sqlite3_prepare(), sqlite3_prepare_v2(),
3974 +** and sqlite3_prepare_v3()
3975 +** interfaces use UTF-8, and sqlite3_prepare16(), sqlite3_prepare16_v2(),
3976 +** and sqlite3_prepare16_v3() use UTF-16.
3977 +**
3978 +** ^If the nByte argument is negative, then zSql is read up to the
3979 +** first zero terminator. ^If nByte is positive, then it is the
3980 +** number of bytes read from zSql. ^If nByte is zero, then no prepared
3981 +** statement is generated.
3982 +** If the caller knows that the supplied string is nul-terminated, then
3983 +** there is a small performance advantage to passing an nByte parameter that
3984 +** is the number of bytes in the input string <i>including</i>
3985 +** the nul-terminator.
3986 +**
3987 +** ^If pzTail is not NULL then *pzTail is made to point to the first byte
3988 +** past the end of the first SQL statement in zSql. These routines only
3989 +** compile the first statement in zSql, so *pzTail is left pointing to
3990 +** what remains uncompiled.
3991 +**
3992 +** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
3993 +** executed using [sqlite3_step()]. ^If there is an error, *ppStmt is set
3994 +** to NULL. ^If the input text contains no SQL (if the input is an empty
3995 +** string or a comment) then *ppStmt is set to NULL.
3996 +** The calling procedure is responsible for deleting the compiled
3997 +** SQL statement using [sqlite3_finalize()] after it has finished with it.
3998 +** ppStmt may not be NULL.
3999 +**
4000 +** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
4001 +** otherwise an [error code] is returned.
4002 +**
4003 +** The sqlite3_prepare_v2(), sqlite3_prepare_v3(), sqlite3_prepare16_v2(),
4004 +** and sqlite3_prepare16_v3() interfaces are recommended for all new programs.
4005 +** The older interfaces (sqlite3_prepare() and sqlite3_prepare16())
4006 +** are retained for backwards compatibility, but their use is discouraged.
4007 +** ^In the "vX" interfaces, the prepared statement
4008 +** that is returned (the [sqlite3_stmt] object) contains a copy of the
4009 +** original SQL text. This causes the [sqlite3_step()] interface to
4010 +** behave differently in three ways:
4011 +**
4012 +** <ol>
4013 +** <li>
4014 +** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
4015 +** always used to do, [sqlite3_step()] will automatically recompile the SQL
4016 +** statement and try to run it again. As many as [SQLITE_MAX_SCHEMA_RETRY]
4017 +** retries will occur before sqlite3_step() gives up and returns an error.
4018 +** </li>
4019 +**
4020 +** <li>
4021 +** ^When an error occurs, [sqlite3_step()] will return one of the detailed
4022 +** [error codes] or [extended error codes]. ^The legacy behavior was that
4023 +** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
4024 +** and the application would have to make a second call to [sqlite3_reset()]
4025 +** in order to find the underlying cause of the problem. With the "v2" prepare
4026 +** interfaces, the underlying reason for the error is returned immediately.
4027 +** </li>
4028 +**
4029 +** <li>
4030 +** ^If the specific value bound to a [parameter | host parameter] in the
4031 +** WHERE clause might influence the choice of query plan for a statement,
4032 +** then the statement will be automatically recompiled, as if there had been
4033 +** a schema change, on the first [sqlite3_step()] call following any change
4034 +** to the [sqlite3_bind_text | bindings] of that [parameter].
4035 +** ^The specific value of a WHERE-clause [parameter] might influence the
4036 +** choice of query plan if the parameter is the left-hand side of a [LIKE]
4037 +** or [GLOB] operator or if the parameter is compared to an indexed column
4038 +** and the [SQLITE_ENABLE_STAT4] compile-time option is enabled.
4039 +** </li>
4040 +** </ol>
4041 +**
4042 +** <p>^sqlite3_prepare_v3() differs from sqlite3_prepare_v2() only in having
4043 +** the extra prepFlags parameter, which is a bit array consisting of zero or
4044 +** more of the [SQLITE_PREPARE_PERSISTENT|SQLITE_PREPARE_*] flags. ^The
4045 +** sqlite3_prepare_v2() interface works exactly the same as
4046 +** sqlite3_prepare_v3() with a zero prepFlags parameter.
4047 +*/
4048 +SQLITE_API int sqlite3_prepare(
4049 + sqlite3 *db, /* Database handle */
4050 + const char *zSql, /* SQL statement, UTF-8 encoded */
4051 + int nByte, /* Maximum length of zSql in bytes. */
4052 + sqlite3_stmt **ppStmt, /* OUT: Statement handle */
4053 + const char **pzTail /* OUT: Pointer to unused portion of zSql */
4054 +);
4055 +SQLITE_API int sqlite3_prepare_v2(
4056 + sqlite3 *db, /* Database handle */
4057 + const char *zSql, /* SQL statement, UTF-8 encoded */
4058 + int nByte, /* Maximum length of zSql in bytes. */
4059 + sqlite3_stmt **ppStmt, /* OUT: Statement handle */
4060 + const char **pzTail /* OUT: Pointer to unused portion of zSql */
4061 +);
4062 +SQLITE_API int sqlite3_prepare_v3(
4063 + sqlite3 *db, /* Database handle */
4064 + const char *zSql, /* SQL statement, UTF-8 encoded */
4065 + int nByte, /* Maximum length of zSql in bytes. */
4066 + unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
4067 + sqlite3_stmt **ppStmt, /* OUT: Statement handle */
4068 + const char **pzTail /* OUT: Pointer to unused portion of zSql */
4069 +);
4070 +SQLITE_API int sqlite3_prepare16(
4071 + sqlite3 *db, /* Database handle */
4072 + const void *zSql, /* SQL statement, UTF-16 encoded */
4073 + int nByte, /* Maximum length of zSql in bytes. */
4074 + sqlite3_stmt **ppStmt, /* OUT: Statement handle */
4075 + const void **pzTail /* OUT: Pointer to unused portion of zSql */
4076 +);
4077 +SQLITE_API int sqlite3_prepare16_v2(
4078 + sqlite3 *db, /* Database handle */
4079 + const void *zSql, /* SQL statement, UTF-16 encoded */
4080 + int nByte, /* Maximum length of zSql in bytes. */
4081 + sqlite3_stmt **ppStmt, /* OUT: Statement handle */
4082 + const void **pzTail /* OUT: Pointer to unused portion of zSql */
4083 +);
4084 +SQLITE_API int sqlite3_prepare16_v3(
4085 + sqlite3 *db, /* Database handle */
4086 + const void *zSql, /* SQL statement, UTF-16 encoded */
4087 + int nByte, /* Maximum length of zSql in bytes. */
4088 + unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
4089 + sqlite3_stmt **ppStmt, /* OUT: Statement handle */
4090 + const void **pzTail /* OUT: Pointer to unused portion of zSql */
4091 +);
4092 +
4093 +/*
4094 +** CAPI3REF: Retrieving Statement SQL
4095 +** METHOD: sqlite3_stmt
4096 +**
4097 +** ^The sqlite3_sql(P) interface returns a pointer to a copy of the UTF-8
4098 +** SQL text used to create [prepared statement] P if P was
4099 +** created by [sqlite3_prepare_v2()], [sqlite3_prepare_v3()],
4100 +** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
4101 +** ^The sqlite3_expanded_sql(P) interface returns a pointer to a UTF-8
4102 +** string containing the SQL text of prepared statement P with
4103 +** [bound parameters] expanded.
4104 +** ^The sqlite3_normalized_sql(P) interface returns a pointer to a UTF-8
4105 +** string containing the normalized SQL text of prepared statement P. The
4106 +** semantics used to normalize a SQL statement are unspecified and subject
4107 +** to change. At a minimum, literal values will be replaced with suitable
4108 +** placeholders.
4109 +**
4110 +** ^(For example, if a prepared statement is created using the SQL
4111 +** text "SELECT $abc,:xyz" and if parameter $abc is bound to integer 2345
4112 +** and parameter :xyz is unbound, then sqlite3_sql() will return
4113 +** the original string, "SELECT $abc,:xyz" but sqlite3_expanded_sql()
4114 +** will return "SELECT 2345,NULL".)^
4115 +**
4116 +** ^The sqlite3_expanded_sql() interface returns NULL if insufficient memory
4117 +** is available to hold the result, or if the result would exceed the
4118 +** the maximum string length determined by the [SQLITE_LIMIT_LENGTH].
4119 +**
4120 +** ^The [SQLITE_TRACE_SIZE_LIMIT] compile-time option limits the size of
4121 +** bound parameter expansions. ^The [SQLITE_OMIT_TRACE] compile-time
4122 +** option causes sqlite3_expanded_sql() to always return NULL.
4123 +**
4124 +** ^The strings returned by sqlite3_sql(P) and sqlite3_normalized_sql(P)
4125 +** are managed by SQLite and are automatically freed when the prepared
4126 +** statement is finalized.
4127 +** ^The string returned by sqlite3_expanded_sql(P), on the other hand,
4128 +** is obtained from [sqlite3_malloc()] and must be free by the application
4129 +** by passing it to [sqlite3_free()].
4130 +*/
4131 +SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
4132 +SQLITE_API char *sqlite3_expanded_sql(sqlite3_stmt *pStmt);
4133 +SQLITE_API const char *sqlite3_normalized_sql(sqlite3_stmt *pStmt);
4134 +
4135 +/*
4136 +** CAPI3REF: Determine If An SQL Statement Writes The Database
4137 +** METHOD: sqlite3_stmt
4138 +**
4139 +** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
4140 +** and only if the [prepared statement] X makes no direct changes to
4141 +** the content of the database file.
4142 +**
4143 +** Note that [application-defined SQL functions] or
4144 +** [virtual tables] might change the database indirectly as a side effect.
4145 +** ^(For example, if an application defines a function "eval()" that
4146 +** calls [sqlite3_exec()], then the following SQL statement would
4147 +** change the database file through side-effects:
4148 +**
4149 +** <blockquote><pre>
4150 +** SELECT eval('DELETE FROM t1') FROM t2;
4151 +** </pre></blockquote>
4152 +**
4153 +** But because the [SELECT] statement does not change the database file
4154 +** directly, sqlite3_stmt_readonly() would still return true.)^
4155 +**
4156 +** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
4157 +** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
4158 +** since the statements themselves do not actually modify the database but
4159 +** rather they control the timing of when other statements modify the
4160 +** database. ^The [ATTACH] and [DETACH] statements also cause
4161 +** sqlite3_stmt_readonly() to return true since, while those statements
4162 +** change the configuration of a database connection, they do not make
4163 +** changes to the content of the database files on disk.
4164 +** ^The sqlite3_stmt_readonly() interface returns true for [BEGIN] since
4165 +** [BEGIN] merely sets internal flags, but the [BEGIN|BEGIN IMMEDIATE] and
4166 +** [BEGIN|BEGIN EXCLUSIVE] commands do touch the database and so
4167 +** sqlite3_stmt_readonly() returns false for those commands.
4168 +*/
4169 +SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
4170 +
4171 +/*
4172 +** CAPI3REF: Query The EXPLAIN Setting For A Prepared Statement
4173 +** METHOD: sqlite3_stmt
4174 +**
4175 +** ^The sqlite3_stmt_isexplain(S) interface returns 1 if the
4176 +** prepared statement S is an EXPLAIN statement, or 2 if the
4177 +** statement S is an EXPLAIN QUERY PLAN.
4178 +** ^The sqlite3_stmt_isexplain(S) interface returns 0 if S is
4179 +** an ordinary statement or a NULL pointer.
4180 +*/
4181 +SQLITE_API int sqlite3_stmt_isexplain(sqlite3_stmt *pStmt);
4182 +
4183 +/*
4184 +** CAPI3REF: Determine If A Prepared Statement Has Been Reset
4185 +** METHOD: sqlite3_stmt
4186 +**
4187 +** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
4188 +** [prepared statement] S has been stepped at least once using
4189 +** [sqlite3_step(S)] but has neither run to completion (returned
4190 +** [SQLITE_DONE] from [sqlite3_step(S)]) nor
4191 +** been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S)
4192 +** interface returns false if S is a NULL pointer. If S is not a
4193 +** NULL pointer and is not a pointer to a valid [prepared statement]
4194 +** object, then the behavior is undefined and probably undesirable.
4195 +**
4196 +** This interface can be used in combination [sqlite3_next_stmt()]
4197 +** to locate all prepared statements associated with a database
4198 +** connection that are in need of being reset. This can be used,
4199 +** for example, in diagnostic routines to search for prepared
4200 +** statements that are holding a transaction open.
4201 +*/
4202 +SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
4203 +
4204 +/*
4205 +** CAPI3REF: Dynamically Typed Value Object
4206 +** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
4207 +**
4208 +** SQLite uses the sqlite3_value object to represent all values
4209 +** that can be stored in a database table. SQLite uses dynamic typing
4210 +** for the values it stores. ^Values stored in sqlite3_value objects
4211 +** can be integers, floating point values, strings, BLOBs, or NULL.
4212 +**
4213 +** An sqlite3_value object may be either "protected" or "unprotected".
4214 +** Some interfaces require a protected sqlite3_value. Other interfaces
4215 +** will accept either a protected or an unprotected sqlite3_value.
4216 +** Every interface that accepts sqlite3_value arguments specifies
4217 +** whether or not it requires a protected sqlite3_value. The
4218 +** [sqlite3_value_dup()] interface can be used to construct a new
4219 +** protected sqlite3_value from an unprotected sqlite3_value.
4220 +**
4221 +** The terms "protected" and "unprotected" refer to whether or not
4222 +** a mutex is held. An internal mutex is held for a protected
4223 +** sqlite3_value object but no mutex is held for an unprotected
4224 +** sqlite3_value object. If SQLite is compiled to be single-threaded
4225 +** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
4226 +** or if SQLite is run in one of reduced mutex modes
4227 +** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
4228 +** then there is no distinction between protected and unprotected
4229 +** sqlite3_value objects and they can be used interchangeably. However,
4230 +** for maximum code portability it is recommended that applications
4231 +** still make the distinction between protected and unprotected
4232 +** sqlite3_value objects even when not strictly required.
4233 +**
4234 +** ^The sqlite3_value objects that are passed as parameters into the
4235 +** implementation of [application-defined SQL functions] are protected.
4236 +** ^The sqlite3_value object returned by
4237 +** [sqlite3_column_value()] is unprotected.
4238 +** Unprotected sqlite3_value objects may only be used as arguments
4239 +** to [sqlite3_result_value()], [sqlite3_bind_value()], and
4240 +** [sqlite3_value_dup()].
4241 +** The [sqlite3_value_blob | sqlite3_value_type()] family of
4242 +** interfaces require protected sqlite3_value objects.
4243 +*/
4244 +typedef struct sqlite3_value sqlite3_value;
4245 +
4246 +/*
4247 +** CAPI3REF: SQL Function Context Object
4248 +**
4249 +** The context in which an SQL function executes is stored in an
4250 +** sqlite3_context object. ^A pointer to an sqlite3_context object
4251 +** is always first parameter to [application-defined SQL functions].
4252 +** The application-defined SQL function implementation will pass this
4253 +** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
4254 +** [sqlite3_aggregate_context()], [sqlite3_user_data()],
4255 +** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
4256 +** and/or [sqlite3_set_auxdata()].
4257 +*/
4258 +typedef struct sqlite3_context sqlite3_context;
4259 +
4260 +/*
4261 +** CAPI3REF: Binding Values To Prepared Statements
4262 +** KEYWORDS: {host parameter} {host parameters} {host parameter name}
4263 +** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
4264 +** METHOD: sqlite3_stmt
4265 +**
4266 +** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
4267 +** literals may be replaced by a [parameter] that matches one of following
4268 +** templates:
4269 +**
4270 +** <ul>
4271 +** <li> ?
4272 +** <li> ?NNN
4273 +** <li> :VVV
4274 +** <li> @VVV
4275 +** <li> $VVV
4276 +** </ul>
4277 +**
4278 +** In the templates above, NNN represents an integer literal,
4279 +** and VVV represents an alphanumeric identifier.)^ ^The values of these
4280 +** parameters (also called "host parameter names" or "SQL parameters")
4281 +** can be set using the sqlite3_bind_*() routines defined here.
4282 +**
4283 +** ^The first argument to the sqlite3_bind_*() routines is always
4284 +** a pointer to the [sqlite3_stmt] object returned from
4285 +** [sqlite3_prepare_v2()] or its variants.
4286 +**
4287 +** ^The second argument is the index of the SQL parameter to be set.
4288 +** ^The leftmost SQL parameter has an index of 1. ^When the same named
4289 +** SQL parameter is used more than once, second and subsequent
4290 +** occurrences have the same index as the first occurrence.
4291 +** ^The index for named parameters can be looked up using the
4292 +** [sqlite3_bind_parameter_index()] API if desired. ^The index
4293 +** for "?NNN" parameters is the value of NNN.
4294 +** ^The NNN value must be between 1 and the [sqlite3_limit()]
4295 +** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 32766).
4296 +**
4297 +** ^The third argument is the value to bind to the parameter.
4298 +** ^If the third parameter to sqlite3_bind_text() or sqlite3_bind_text16()
4299 +** or sqlite3_bind_blob() is a NULL pointer then the fourth parameter
4300 +** is ignored and the end result is the same as sqlite3_bind_null().
4301 +** ^If the third parameter to sqlite3_bind_text() is not NULL, then
4302 +** it should be a pointer to well-formed UTF8 text.
4303 +** ^If the third parameter to sqlite3_bind_text16() is not NULL, then
4304 +** it should be a pointer to well-formed UTF16 text.
4305 +** ^If the third parameter to sqlite3_bind_text64() is not NULL, then
4306 +** it should be a pointer to a well-formed unicode string that is
4307 +** either UTF8 if the sixth parameter is SQLITE_UTF8, or UTF16
4308 +** otherwise.
4309 +**
4310 +** [[byte-order determination rules]] ^The byte-order of
4311 +** UTF16 input text is determined by the byte-order mark (BOM, U+FEFF)
4312 +** found in first character, which is removed, or in the absence of a BOM
4313 +** the byte order is the native byte order of the host
4314 +** machine for sqlite3_bind_text16() or the byte order specified in
4315 +** the 6th parameter for sqlite3_bind_text64().)^
4316 +** ^If UTF16 input text contains invalid unicode
4317 +** characters, then SQLite might change those invalid characters
4318 +** into the unicode replacement character: U+FFFD.
4319 +**
4320 +** ^(In those routines that have a fourth argument, its value is the
4321 +** number of bytes in the parameter. To be clear: the value is the
4322 +** number of <u>bytes</u> in the value, not the number of characters.)^
4323 +** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
4324 +** is negative, then the length of the string is
4325 +** the number of bytes up to the first zero terminator.
4326 +** If the fourth parameter to sqlite3_bind_blob() is negative, then
4327 +** the behavior is undefined.
4328 +** If a non-negative fourth parameter is provided to sqlite3_bind_text()
4329 +** or sqlite3_bind_text16() or sqlite3_bind_text64() then
4330 +** that parameter must be the byte offset
4331 +** where the NUL terminator would occur assuming the string were NUL
4332 +** terminated. If any NUL characters occurs at byte offsets less than
4333 +** the value of the fourth parameter then the resulting string value will
4334 +** contain embedded NULs. The result of expressions involving strings
4335 +** with embedded NULs is undefined.
4336 +**
4337 +** ^The fifth argument to the BLOB and string binding interfaces
4338 +** is a destructor used to dispose of the BLOB or
4339 +** string after SQLite has finished with it. ^The destructor is called
4340 +** to dispose of the BLOB or string even if the call to the bind API fails,
4341 +** except the destructor is not called if the third parameter is a NULL
4342 +** pointer or the fourth parameter is negative.
4343 +** ^If the fifth argument is
4344 +** the special value [SQLITE_STATIC], then SQLite assumes that the
4345 +** information is in static, unmanaged space and does not need to be freed.
4346 +** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
4347 +** SQLite makes its own private copy of the data immediately, before
4348 +** the sqlite3_bind_*() routine returns.
4349 +**
4350 +** ^The sixth argument to sqlite3_bind_text64() must be one of
4351 +** [SQLITE_UTF8], [SQLITE_UTF16], [SQLITE_UTF16BE], or [SQLITE_UTF16LE]
4352 +** to specify the encoding of the text in the third parameter. If
4353 +** the sixth argument to sqlite3_bind_text64() is not one of the
4354 +** allowed values shown above, or if the text encoding is different
4355 +** from the encoding specified by the sixth parameter, then the behavior
4356 +** is undefined.
4357 +**
4358 +** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
4359 +** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
4360 +** (just an integer to hold its size) while it is being processed.
4361 +** Zeroblobs are intended to serve as placeholders for BLOBs whose
4362 +** content is later written using
4363 +** [sqlite3_blob_open | incremental BLOB I/O] routines.
4364 +** ^A negative value for the zeroblob results in a zero-length BLOB.
4365 +**
4366 +** ^The sqlite3_bind_pointer(S,I,P,T,D) routine causes the I-th parameter in
4367 +** [prepared statement] S to have an SQL value of NULL, but to also be
4368 +** associated with the pointer P of type T. ^D is either a NULL pointer or
4369 +** a pointer to a destructor function for P. ^SQLite will invoke the
4370 +** destructor D with a single argument of P when it is finished using
4371 +** P. The T parameter should be a static string, preferably a string
4372 +** literal. The sqlite3_bind_pointer() routine is part of the
4373 +** [pointer passing interface] added for SQLite 3.20.0.
4374 +**
4375 +** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
4376 +** for the [prepared statement] or with a prepared statement for which
4377 +** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
4378 +** then the call will return [SQLITE_MISUSE]. If any sqlite3_bind_()
4379 +** routine is passed a [prepared statement] that has been finalized, the
4380 +** result is undefined and probably harmful.
4381 +**
4382 +** ^Bindings are not cleared by the [sqlite3_reset()] routine.
4383 +** ^Unbound parameters are interpreted as NULL.
4384 +**
4385 +** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
4386 +** [error code] if anything goes wrong.
4387 +** ^[SQLITE_TOOBIG] might be returned if the size of a string or BLOB
4388 +** exceeds limits imposed by [sqlite3_limit]([SQLITE_LIMIT_LENGTH]) or
4389 +** [SQLITE_MAX_LENGTH].
4390 +** ^[SQLITE_RANGE] is returned if the parameter
4391 +** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails.
4392 +**
4393 +** See also: [sqlite3_bind_parameter_count()],
4394 +** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
4395 +*/
4396 +SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
4397 +SQLITE_API int sqlite3_bind_blob64(sqlite3_stmt*, int, const void*, sqlite3_uint64,
4398 + void(*)(void*));
4399 +SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
4400 +SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
4401 +SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
4402 +SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
4403 +SQLITE_API int sqlite3_bind_text(sqlite3_stmt*,int,const char*,int,void(*)(void*));
4404 +SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
4405 +SQLITE_API int sqlite3_bind_text64(sqlite3_stmt*, int, const char*, sqlite3_uint64,
4406 + void(*)(void*), unsigned char encoding);
4407 +SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
4408 +SQLITE_API int sqlite3_bind_pointer(sqlite3_stmt*, int, void*, const char*,void(*)(void*));
4409 +SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
4410 +SQLITE_API int sqlite3_bind_zeroblob64(sqlite3_stmt*, int, sqlite3_uint64);
4411 +
4412 +/*
4413 +** CAPI3REF: Number Of SQL Parameters
4414 +** METHOD: sqlite3_stmt
4415 +**
4416 +** ^This routine can be used to find the number of [SQL parameters]
4417 +** in a [prepared statement]. SQL parameters are tokens of the
4418 +** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
4419 +** placeholders for values that are [sqlite3_bind_blob | bound]
4420 +** to the parameters at a later time.
4421 +**
4422 +** ^(This routine actually returns the index of the largest (rightmost)
4423 +** parameter. For all forms except ?NNN, this will correspond to the
4424 +** number of unique parameters. If parameters of the ?NNN form are used,
4425 +** there may be gaps in the list.)^
4426 +**
4427 +** See also: [sqlite3_bind_blob|sqlite3_bind()],
4428 +** [sqlite3_bind_parameter_name()], and
4429 +** [sqlite3_bind_parameter_index()].
4430 +*/
4431 +SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
4432 +
4433 +/*
4434 +** CAPI3REF: Name Of A Host Parameter
4435 +** METHOD: sqlite3_stmt
4436 +**
4437 +** ^The sqlite3_bind_parameter_name(P,N) interface returns
4438 +** the name of the N-th [SQL parameter] in the [prepared statement] P.
4439 +** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
4440 +** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
4441 +** respectively.
4442 +** In other words, the initial ":" or "$" or "@" or "?"
4443 +** is included as part of the name.)^
4444 +** ^Parameters of the form "?" without a following integer have no name
4445 +** and are referred to as "nameless" or "anonymous parameters".
4446 +**
4447 +** ^The first host parameter has an index of 1, not 0.
4448 +**
4449 +** ^If the value N is out of range or if the N-th parameter is
4450 +** nameless, then NULL is returned. ^The returned string is
4451 +** always in UTF-8 encoding even if the named parameter was
4452 +** originally specified as UTF-16 in [sqlite3_prepare16()],
4453 +** [sqlite3_prepare16_v2()], or [sqlite3_prepare16_v3()].
4454 +**
4455 +** See also: [sqlite3_bind_blob|sqlite3_bind()],
4456 +** [sqlite3_bind_parameter_count()], and
4457 +** [sqlite3_bind_parameter_index()].
4458 +*/
4459 +SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
4460 +
4461 +/*
4462 +** CAPI3REF: Index Of A Parameter With A Given Name
4463 +** METHOD: sqlite3_stmt
4464 +**
4465 +** ^Return the index of an SQL parameter given its name. ^The
4466 +** index value returned is suitable for use as the second
4467 +** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero
4468 +** is returned if no matching parameter is found. ^The parameter
4469 +** name must be given in UTF-8 even if the original statement
4470 +** was prepared from UTF-16 text using [sqlite3_prepare16_v2()] or
4471 +** [sqlite3_prepare16_v3()].
4472 +**
4473 +** See also: [sqlite3_bind_blob|sqlite3_bind()],
4474 +** [sqlite3_bind_parameter_count()], and
4475 +** [sqlite3_bind_parameter_name()].
4476 +*/
4477 +SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
4478 +
4479 +/*
4480 +** CAPI3REF: Reset All Bindings On A Prepared Statement
4481 +** METHOD: sqlite3_stmt
4482 +**
4483 +** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
4484 +** the [sqlite3_bind_blob | bindings] on a [prepared statement].
4485 +** ^Use this routine to reset all host parameters to NULL.
4486 +*/
4487 +SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
4488 +
4489 +/*
4490 +** CAPI3REF: Number Of Columns In A Result Set
4491 +** METHOD: sqlite3_stmt
4492 +**
4493 +** ^Return the number of columns in the result set returned by the
4494 +** [prepared statement]. ^If this routine returns 0, that means the
4495 +** [prepared statement] returns no data (for example an [UPDATE]).
4496 +** ^However, just because this routine returns a positive number does not
4497 +** mean that one or more rows of data will be returned. ^A SELECT statement
4498 +** will always have a positive sqlite3_column_count() but depending on the
4499 +** WHERE clause constraints and the table content, it might return no rows.
4500 +**
4501 +** See also: [sqlite3_data_count()]
4502 +*/
4503 +SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
4504 +
4505 +/*
4506 +** CAPI3REF: Column Names In A Result Set
4507 +** METHOD: sqlite3_stmt
4508 +**
4509 +** ^These routines return the name assigned to a particular column
4510 +** in the result set of a [SELECT] statement. ^The sqlite3_column_name()
4511 +** interface returns a pointer to a zero-terminated UTF-8 string
4512 +** and sqlite3_column_name16() returns a pointer to a zero-terminated
4513 +** UTF-16 string. ^The first parameter is the [prepared statement]
4514 +** that implements the [SELECT] statement. ^The second parameter is the
4515 +** column number. ^The leftmost column is number 0.
4516 +**
4517 +** ^The returned string pointer is valid until either the [prepared statement]
4518 +** is destroyed by [sqlite3_finalize()] or until the statement is automatically
4519 +** reprepared by the first call to [sqlite3_step()] for a particular run
4520 +** or until the next call to
4521 +** sqlite3_column_name() or sqlite3_column_name16() on the same column.
4522 +**
4523 +** ^If sqlite3_malloc() fails during the processing of either routine
4524 +** (for example during a conversion from UTF-8 to UTF-16) then a
4525 +** NULL pointer is returned.
4526 +**
4527 +** ^The name of a result column is the value of the "AS" clause for
4528 +** that column, if there is an AS clause. If there is no AS clause
4529 +** then the name of the column is unspecified and may change from
4530 +** one release of SQLite to the next.
4531 +*/
4532 +SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
4533 +SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
4534 +
4535 +/*
4536 +** CAPI3REF: Source Of Data In A Query Result
4537 +** METHOD: sqlite3_stmt
4538 +**
4539 +** ^These routines provide a means to determine the database, table, and
4540 +** table column that is the origin of a particular result column in
4541 +** [SELECT] statement.
4542 +** ^The name of the database or table or column can be returned as
4543 +** either a UTF-8 or UTF-16 string. ^The _database_ routines return
4544 +** the database name, the _table_ routines return the table name, and
4545 +** the origin_ routines return the column name.
4546 +** ^The returned string is valid until the [prepared statement] is destroyed
4547 +** using [sqlite3_finalize()] or until the statement is automatically
4548 +** reprepared by the first call to [sqlite3_step()] for a particular run
4549 +** or until the same information is requested
4550 +** again in a different encoding.
4551 +**
4552 +** ^The names returned are the original un-aliased names of the
4553 +** database, table, and column.
4554 +**
4555 +** ^The first argument to these interfaces is a [prepared statement].
4556 +** ^These functions return information about the Nth result column returned by
4557 +** the statement, where N is the second function argument.
4558 +** ^The left-most column is column 0 for these routines.
4559 +**
4560 +** ^If the Nth column returned by the statement is an expression or
4561 +** subquery and is not a column value, then all of these functions return
4562 +** NULL. ^These routines might also return NULL if a memory allocation error
4563 +** occurs. ^Otherwise, they return the name of the attached database, table,
4564 +** or column that query result column was extracted from.
4565 +**
4566 +** ^As with all other SQLite APIs, those whose names end with "16" return
4567 +** UTF-16 encoded strings and the other functions return UTF-8.
4568 +**
4569 +** ^These APIs are only available if the library was compiled with the
4570 +** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
4571 +**
4572 +** If two or more threads call one or more
4573 +** [sqlite3_column_database_name | column metadata interfaces]
4574 +** for the same [prepared statement] and result column
4575 +** at the same time then the results are undefined.
4576 +*/
4577 +SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
4578 +SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
4579 +SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
4580 +SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
4581 +SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
4582 +SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
4583 +
4584 +/*
4585 +** CAPI3REF: Declared Datatype Of A Query Result
4586 +** METHOD: sqlite3_stmt
4587 +**
4588 +** ^(The first parameter is a [prepared statement].
4589 +** If this statement is a [SELECT] statement and the Nth column of the
4590 +** returned result set of that [SELECT] is a table column (not an
4591 +** expression or subquery) then the declared type of the table
4592 +** column is returned.)^ ^If the Nth column of the result set is an
4593 +** expression or subquery, then a NULL pointer is returned.
4594 +** ^The returned string is always UTF-8 encoded.
4595 +**
4596 +** ^(For example, given the database schema:
4597 +**
4598 +** CREATE TABLE t1(c1 VARIANT);
4599 +**
4600 +** and the following statement to be compiled:
4601 +**
4602 +** SELECT c1 + 1, c1 FROM t1;
4603 +**
4604 +** this routine would return the string "VARIANT" for the second result
4605 +** column (i==1), and a NULL pointer for the first result column (i==0).)^
4606 +**
4607 +** ^SQLite uses dynamic run-time typing. ^So just because a column
4608 +** is declared to contain a particular type does not mean that the
4609 +** data stored in that column is of the declared type. SQLite is
4610 +** strongly typed, but the typing is dynamic not static. ^Type
4611 +** is associated with individual values, not with the containers
4612 +** used to hold those values.
4613 +*/
4614 +SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
4615 +SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
4616 +
4617 +/*
4618 +** CAPI3REF: Evaluate An SQL Statement
4619 +** METHOD: sqlite3_stmt
4620 +**
4621 +** After a [prepared statement] has been prepared using any of
4622 +** [sqlite3_prepare_v2()], [sqlite3_prepare_v3()], [sqlite3_prepare16_v2()],
4623 +** or [sqlite3_prepare16_v3()] or one of the legacy
4624 +** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
4625 +** must be called one or more times to evaluate the statement.
4626 +**
4627 +** The details of the behavior of the sqlite3_step() interface depend
4628 +** on whether the statement was prepared using the newer "vX" interfaces
4629 +** [sqlite3_prepare_v3()], [sqlite3_prepare_v2()], [sqlite3_prepare16_v3()],
4630 +** [sqlite3_prepare16_v2()] or the older legacy
4631 +** interfaces [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
4632 +** new "vX" interface is recommended for new applications but the legacy
4633 +** interface will continue to be supported.
4634 +**
4635 +** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
4636 +** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
4637 +** ^With the "v2" interface, any of the other [result codes] or
4638 +** [extended result codes] might be returned as well.
4639 +**
4640 +** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
4641 +** database locks it needs to do its job. ^If the statement is a [COMMIT]
4642 +** or occurs outside of an explicit transaction, then you can retry the
4643 +** statement. If the statement is not a [COMMIT] and occurs within an
4644 +** explicit transaction then you should rollback the transaction before
4645 +** continuing.
4646 +**
4647 +** ^[SQLITE_DONE] means that the statement has finished executing
4648 +** successfully. sqlite3_step() should not be called again on this virtual
4649 +** machine without first calling [sqlite3_reset()] to reset the virtual
4650 +** machine back to its initial state.
4651 +**
4652 +** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
4653 +** is returned each time a new row of data is ready for processing by the
4654 +** caller. The values may be accessed using the [column access functions].
4655 +** sqlite3_step() is called again to retrieve the next row of data.
4656 +**
4657 +** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
4658 +** violation) has occurred. sqlite3_step() should not be called again on
4659 +** the VM. More information may be found by calling [sqlite3_errmsg()].
4660 +** ^With the legacy interface, a more specific error code (for example,
4661 +** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
4662 +** can be obtained by calling [sqlite3_reset()] on the
4663 +** [prepared statement]. ^In the "v2" interface,
4664 +** the more specific error code is returned directly by sqlite3_step().
4665 +**
4666 +** [SQLITE_MISUSE] means that the this routine was called inappropriately.
4667 +** Perhaps it was called on a [prepared statement] that has
4668 +** already been [sqlite3_finalize | finalized] or on one that had
4669 +** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
4670 +** be the case that the same database connection is being used by two or
4671 +** more threads at the same moment in time.
4672 +**
4673 +** For all versions of SQLite up to and including 3.6.23.1, a call to
4674 +** [sqlite3_reset()] was required after sqlite3_step() returned anything
4675 +** other than [SQLITE_ROW] before any subsequent invocation of
4676 +** sqlite3_step(). Failure to reset the prepared statement using
4677 +** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
4678 +** sqlite3_step(). But after [version 3.6.23.1] ([dateof:3.6.23.1],
4679 +** sqlite3_step() began
4680 +** calling [sqlite3_reset()] automatically in this circumstance rather
4681 +** than returning [SQLITE_MISUSE]. This is not considered a compatibility
4682 +** break because any application that ever receives an SQLITE_MISUSE error
4683 +** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option
4684 +** can be used to restore the legacy behavior.
4685 +**
4686 +** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
4687 +** API always returns a generic error code, [SQLITE_ERROR], following any
4688 +** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call
4689 +** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
4690 +** specific [error codes] that better describes the error.
4691 +** We admit that this is a goofy design. The problem has been fixed
4692 +** with the "v2" interface. If you prepare all of your SQL statements
4693 +** using [sqlite3_prepare_v3()] or [sqlite3_prepare_v2()]
4694 +** or [sqlite3_prepare16_v2()] or [sqlite3_prepare16_v3()] instead
4695 +** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
4696 +** then the more specific [error codes] are returned directly
4697 +** by sqlite3_step(). The use of the "vX" interfaces is recommended.
4698 +*/
4699 +SQLITE_API int sqlite3_step(sqlite3_stmt*);
4700 +
4701 +/*
4702 +** CAPI3REF: Number of columns in a result set
4703 +** METHOD: sqlite3_stmt
4704 +**
4705 +** ^The sqlite3_data_count(P) interface returns the number of columns in the
4706 +** current row of the result set of [prepared statement] P.
4707 +** ^If prepared statement P does not have results ready to return
4708 +** (via calls to the [sqlite3_column_int | sqlite3_column()] family of
4709 +** interfaces) then sqlite3_data_count(P) returns 0.
4710 +** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
4711 +** ^The sqlite3_data_count(P) routine returns 0 if the previous call to
4712 +** [sqlite3_step](P) returned [SQLITE_DONE]. ^The sqlite3_data_count(P)
4713 +** will return non-zero if previous call to [sqlite3_step](P) returned
4714 +** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum]
4715 +** where it always returns zero since each step of that multi-step
4716 +** pragma returns 0 columns of data.
4717 +**
4718 +** See also: [sqlite3_column_count()]
4719 +*/
4720 +SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
4721 +
4722 +/*
4723 +** CAPI3REF: Fundamental Datatypes
4724 +** KEYWORDS: SQLITE_TEXT
4725 +**
4726 +** ^(Every value in SQLite has one of five fundamental datatypes:
4727 +**
4728 +** <ul>
4729 +** <li> 64-bit signed integer
4730 +** <li> 64-bit IEEE floating point number
4731 +** <li> string
4732 +** <li> BLOB
4733 +** <li> NULL
4734 +** </ul>)^
4735 +**
4736 +** These constants are codes for each of those types.
4737 +**
4738 +** Note that the SQLITE_TEXT constant was also used in SQLite version 2
4739 +** for a completely different meaning. Software that links against both
4740 +** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
4741 +** SQLITE_TEXT.
4742 +*/
4743 +#define SQLITE_INTEGER 1
4744 +#define SQLITE_FLOAT 2
4745 +#define SQLITE_BLOB 4
4746 +#define SQLITE_NULL 5
4747 +#ifdef SQLITE_TEXT
4748 +# undef SQLITE_TEXT
4749 +#else
4750 +# define SQLITE_TEXT 3
4751 +#endif
4752 +#define SQLITE3_TEXT 3
4753 +
4754 +/*
4755 +** CAPI3REF: Result Values From A Query
4756 +** KEYWORDS: {column access functions}
4757 +** METHOD: sqlite3_stmt
4758 +**
4759 +** <b>Summary:</b>
4760 +** <blockquote><table border=0 cellpadding=0 cellspacing=0>
4761 +** <tr><td><b>sqlite3_column_blob</b><td>&rarr;<td>BLOB result
4762 +** <tr><td><b>sqlite3_column_double</b><td>&rarr;<td>REAL result
4763 +** <tr><td><b>sqlite3_column_int</b><td>&rarr;<td>32-bit INTEGER result
4764 +** <tr><td><b>sqlite3_column_int64</b><td>&rarr;<td>64-bit INTEGER result
4765 +** <tr><td><b>sqlite3_column_text</b><td>&rarr;<td>UTF-8 TEXT result
4766 +** <tr><td><b>sqlite3_column_text16</b><td>&rarr;<td>UTF-16 TEXT result
4767 +** <tr><td><b>sqlite3_column_value</b><td>&rarr;<td>The result as an
4768 +** [sqlite3_value|unprotected sqlite3_value] object.
4769 +** <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
4770 +** <tr><td><b>sqlite3_column_bytes</b><td>&rarr;<td>Size of a BLOB
4771 +** or a UTF-8 TEXT result in bytes
4772 +** <tr><td><b>sqlite3_column_bytes16&nbsp;&nbsp;</b>
4773 +** <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
4774 +** TEXT in bytes
4775 +** <tr><td><b>sqlite3_column_type</b><td>&rarr;<td>Default
4776 +** datatype of the result
4777 +** </table></blockquote>
4778 +**
4779 +** <b>Details:</b>
4780 +**
4781 +** ^These routines return information about a single column of the current
4782 +** result row of a query. ^In every case the first argument is a pointer
4783 +** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
4784 +** that was returned from [sqlite3_prepare_v2()] or one of its variants)
4785 +** and the second argument is the index of the column for which information
4786 +** should be returned. ^The leftmost column of the result set has the index 0.
4787 +** ^The number of columns in the result can be determined using
4788 +** [sqlite3_column_count()].
4789 +**
4790 +** If the SQL statement does not currently point to a valid row, or if the
4791 +** column index is out of range, the result is undefined.
4792 +** These routines may only be called when the most recent call to
4793 +** [sqlite3_step()] has returned [SQLITE_ROW] and neither
4794 +** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
4795 +** If any of these routines are called after [sqlite3_reset()] or
4796 +** [sqlite3_finalize()] or after [sqlite3_step()] has returned
4797 +** something other than [SQLITE_ROW], the results are undefined.
4798 +** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
4799 +** are called from a different thread while any of these routines
4800 +** are pending, then the results are undefined.
4801 +**
4802 +** The first six interfaces (_blob, _double, _int, _int64, _text, and _text16)
4803 +** each return the value of a result column in a specific data format. If
4804 +** the result column is not initially in the requested format (for example,
4805 +** if the query returns an integer but the sqlite3_column_text() interface
4806 +** is used to extract the value) then an automatic type conversion is performed.
4807 +**
4808 +** ^The sqlite3_column_type() routine returns the
4809 +** [SQLITE_INTEGER | datatype code] for the initial data type
4810 +** of the result column. ^The returned value is one of [SQLITE_INTEGER],
4811 +** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].
4812 +** The return value of sqlite3_column_type() can be used to decide which
4813 +** of the first six interface should be used to extract the column value.
4814 +** The value returned by sqlite3_column_type() is only meaningful if no
4815 +** automatic type conversions have occurred for the value in question.
4816 +** After a type conversion, the result of calling sqlite3_column_type()
4817 +** is undefined, though harmless. Future
4818 +** versions of SQLite may change the behavior of sqlite3_column_type()
4819 +** following a type conversion.
4820 +**
4821 +** If the result is a BLOB or a TEXT string, then the sqlite3_column_bytes()
4822 +** or sqlite3_column_bytes16() interfaces can be used to determine the size
4823 +** of that BLOB or string.
4824 +**
4825 +** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
4826 +** routine returns the number of bytes in that BLOB or string.
4827 +** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
4828 +** the string to UTF-8 and then returns the number of bytes.
4829 +** ^If the result is a numeric value then sqlite3_column_bytes() uses
4830 +** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
4831 +** the number of bytes in that string.
4832 +** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
4833 +**
4834 +** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
4835 +** routine returns the number of bytes in that BLOB or string.
4836 +** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
4837 +** the string to UTF-16 and then returns the number of bytes.
4838 +** ^If the result is a numeric value then sqlite3_column_bytes16() uses
4839 +** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
4840 +** the number of bytes in that string.
4841 +** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
4842 +**
4843 +** ^The values returned by [sqlite3_column_bytes()] and
4844 +** [sqlite3_column_bytes16()] do not include the zero terminators at the end
4845 +** of the string. ^For clarity: the values returned by
4846 +** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
4847 +** bytes in the string, not the number of characters.
4848 +**
4849 +** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
4850 +** even empty strings, are always zero-terminated. ^The return
4851 +** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
4852 +**
4853 +** <b>Warning:</b> ^The object returned by [sqlite3_column_value()] is an
4854 +** [unprotected sqlite3_value] object. In a multithreaded environment,
4855 +** an unprotected sqlite3_value object may only be used safely with
4856 +** [sqlite3_bind_value()] and [sqlite3_result_value()].
4857 +** If the [unprotected sqlite3_value] object returned by
4858 +** [sqlite3_column_value()] is used in any other way, including calls
4859 +** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
4860 +** or [sqlite3_value_bytes()], the behavior is not threadsafe.
4861 +** Hence, the sqlite3_column_value() interface
4862 +** is normally only useful within the implementation of
4863 +** [application-defined SQL functions] or [virtual tables], not within
4864 +** top-level application code.
4865 +**
4866 +** The these routines may attempt to convert the datatype of the result.
4867 +** ^For example, if the internal representation is FLOAT and a text result
4868 +** is requested, [sqlite3_snprintf()] is used internally to perform the
4869 +** conversion automatically. ^(The following table details the conversions
4870 +** that are applied:
4871 +**
4872 +** <blockquote>
4873 +** <table border="1">
4874 +** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion
4875 +**
4876 +** <tr><td> NULL <td> INTEGER <td> Result is 0
4877 +** <tr><td> NULL <td> FLOAT <td> Result is 0.0
4878 +** <tr><td> NULL <td> TEXT <td> Result is a NULL pointer
4879 +** <tr><td> NULL <td> BLOB <td> Result is a NULL pointer
4880 +** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
4881 +** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
4882 +** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
4883 +** <tr><td> FLOAT <td> INTEGER <td> [CAST] to INTEGER
4884 +** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
4885 +** <tr><td> FLOAT <td> BLOB <td> [CAST] to BLOB
4886 +** <tr><td> TEXT <td> INTEGER <td> [CAST] to INTEGER
4887 +** <tr><td> TEXT <td> FLOAT <td> [CAST] to REAL
4888 +** <tr><td> TEXT <td> BLOB <td> No change
4889 +** <tr><td> BLOB <td> INTEGER <td> [CAST] to INTEGER
4890 +** <tr><td> BLOB <td> FLOAT <td> [CAST] to REAL
4891 +** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
4892 +** </table>
4893 +** </blockquote>)^
4894 +**
4895 +** Note that when type conversions occur, pointers returned by prior
4896 +** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
4897 +** sqlite3_column_text16() may be invalidated.
4898 +** Type conversions and pointer invalidations might occur
4899 +** in the following cases:
4900 +**
4901 +** <ul>
4902 +** <li> The initial content is a BLOB and sqlite3_column_text() or
4903 +** sqlite3_column_text16() is called. A zero-terminator might
4904 +** need to be added to the string.</li>
4905 +** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
4906 +** sqlite3_column_text16() is called. The content must be converted
4907 +** to UTF-16.</li>
4908 +** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
4909 +** sqlite3_column_text() is called. The content must be converted
4910 +** to UTF-8.</li>
4911 +** </ul>
4912 +**
4913 +** ^Conversions between UTF-16be and UTF-16le are always done in place and do
4914 +** not invalidate a prior pointer, though of course the content of the buffer
4915 +** that the prior pointer references will have been modified. Other kinds
4916 +** of conversion are done in place when it is possible, but sometimes they
4917 +** are not possible and in those cases prior pointers are invalidated.
4918 +**
4919 +** The safest policy is to invoke these routines
4920 +** in one of the following ways:
4921 +**
4922 +** <ul>
4923 +** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
4924 +** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
4925 +** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
4926 +** </ul>
4927 +**
4928 +** In other words, you should call sqlite3_column_text(),
4929 +** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
4930 +** into the desired format, then invoke sqlite3_column_bytes() or
4931 +** sqlite3_column_bytes16() to find the size of the result. Do not mix calls
4932 +** to sqlite3_column_text() or sqlite3_column_blob() with calls to
4933 +** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
4934 +** with calls to sqlite3_column_bytes().
4935 +**
4936 +** ^The pointers returned are valid until a type conversion occurs as
4937 +** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
4938 +** [sqlite3_finalize()] is called. ^The memory space used to hold strings
4939 +** and BLOBs is freed automatically. Do not pass the pointers returned
4940 +** from [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
4941 +** [sqlite3_free()].
4942 +**
4943 +** As long as the input parameters are correct, these routines will only
4944 +** fail if an out-of-memory error occurs during a format conversion.
4945 +** Only the following subset of interfaces are subject to out-of-memory
4946 +** errors:
4947 +**
4948 +** <ul>
4949 +** <li> sqlite3_column_blob()
4950 +** <li> sqlite3_column_text()
4951 +** <li> sqlite3_column_text16()
4952 +** <li> sqlite3_column_bytes()
4953 +** <li> sqlite3_column_bytes16()
4954 +** </ul>
4955 +**
4956 +** If an out-of-memory error occurs, then the return value from these
4957 +** routines is the same as if the column had contained an SQL NULL value.
4958 +** Valid SQL NULL returns can be distinguished from out-of-memory errors
4959 +** by invoking the [sqlite3_errcode()] immediately after the suspect
4960 +** return value is obtained and before any
4961 +** other SQLite interface is called on the same [database connection].
4962 +*/
4963 +SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
4964 +SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
4965 +SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
4966 +SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
4967 +SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
4968 +SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
4969 +SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
4970 +SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
4971 +SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
4972 +SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
4973 +
4974 +/*
4975 +** CAPI3REF: Destroy A Prepared Statement Object
4976 +** DESTRUCTOR: sqlite3_stmt
4977 +**
4978 +** ^The sqlite3_finalize() function is called to delete a [prepared statement].
4979 +** ^If the most recent evaluation of the statement encountered no errors
4980 +** or if the statement is never been evaluated, then sqlite3_finalize() returns
4981 +** SQLITE_OK. ^If the most recent evaluation of statement S failed, then
4982 +** sqlite3_finalize(S) returns the appropriate [error code] or
4983 +** [extended error code].
4984 +**
4985 +** ^The sqlite3_finalize(S) routine can be called at any point during
4986 +** the life cycle of [prepared statement] S:
4987 +** before statement S is ever evaluated, after
4988 +** one or more calls to [sqlite3_reset()], or after any call
4989 +** to [sqlite3_step()] regardless of whether or not the statement has
4990 +** completed execution.
4991 +**
4992 +** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
4993 +**
4994 +** The application must finalize every [prepared statement] in order to avoid
4995 +** resource leaks. It is a grievous error for the application to try to use
4996 +** a prepared statement after it has been finalized. Any use of a prepared
4997 +** statement after it has been finalized can result in undefined and
4998 +** undesirable behavior such as segfaults and heap corruption.
4999 +*/

This file is too large to show in full.

database/sqlite/sqlite_functions.c new
+1072
@@ -0,0 +1,1072 @@
1 +// SPDX-License-Identifier: GPL-3.0-or-later
2 +
3 +#include "sqlite_functions.h"
4 +
5 +const char *database_config[] = {
6 + "PRAGMA auto_vacuum=incremental; PRAGMA synchronous=1 ; PRAGMA journal_mode=WAL; PRAGMA temp_store=MEMORY;",
7 + "PRAGMA journal_size_limit=16777216;",
8 + "CREATE TABLE IF NOT EXISTS host(host_id blob PRIMARY KEY, hostname text, "
9 + "registry_hostname text, update_every int, os text, timezone text, tags text);",
10 + "CREATE TABLE IF NOT EXISTS chart(chart_id blob PRIMARY KEY, host_id blob, type text, id text, name text, "
11 + "family text, context text, title text, unit text, plugin text, module text, priority int, update_every int, "
12 + "chart_type int, memory_mode int, history_entries);",
13 + "CREATE TABLE IF NOT EXISTS dimension(dim_id blob PRIMARY KEY, chart_id blob, id text, name text, "
14 + "multiplier int, divisor int , algorithm int, options text);",
15 + "CREATE TABLE IF NOT EXISTS chart_active(chart_id blob PRIMARY KEY, date_created int);",
16 + "CREATE TABLE IF NOT EXISTS dimension_active(dim_id blob primary key, date_created int);",
17 + "CREATE TABLE IF NOT EXISTS metadata_migration(filename text, file_size, date_created int);",
18 + "CREATE INDEX IF NOT EXISTS ind_d1 on dimension (chart_id, id, name);",
19 + "CREATE INDEX IF NOT EXISTS ind_c1 on chart (host_id, id, type, name);",
20 +
21 + "delete from chart_active;",
22 + "delete from dimension_active;",
23 +
24 + "delete from chart where chart_id not in (select chart_id from dimension);",
25 + "delete from host where host_id not in (select host_id from chart);",
26 + NULL
27 +};
28 +
29 +sqlite3 *db_meta = NULL;
30 +
31 +static uv_mutex_t sqlite_transaction_lock;
32 +static uint32_t page_size;
33 +static uint32_t page_count;
34 +static uint32_t free_page_count;
35 +
36 +uint32_t sqlite_disk_quota_mb;
37 +uint32_t desired_pages = 0;
38 +
39 +static int execute_insert(sqlite3_stmt *res)
40 +{
41 + int rc;
42 +
43 + while ((rc = sqlite3_step(res)) != SQLITE_DONE && unlikely(netdata_exit)) {
44 + if (likely(rc == SQLITE_BUSY || rc == SQLITE_LOCKED))
45 + usleep(SQLITE_INSERT_DELAY * USEC_PER_MS);
46 + else {
47 + error_report("SQLite error %d", rc);
48 + break;
49 + }
50 + }
51 +
52 + return rc;
53 +}
54 +
55 +/*
56 + * Store a chart or dimension UUID in chart_active or dimension_active
57 + * The statement that will be prepared determines that
58 + */
59 +
60 +static int store_active_uuid_object(sqlite3_stmt **res, char *statement, uuid_t *uuid)
61 +{
62 + int rc;
63 +
64 + // Check if we should need to prepare the statement
65 + if (!*res) {
66 + rc = sqlite3_prepare_v2(db_meta, statement, -1, res, 0);
67 + if (unlikely(rc != SQLITE_OK)) {
68 + error_report("Failed to prepare statement to store active object, rc = %d", rc);
69 + return rc;
70 + }
71 + }
72 +
73 + rc = sqlite3_bind_blob(*res, 1, uuid, sizeof(*uuid), SQLITE_STATIC);
74 + if (unlikely(rc != SQLITE_OK))
75 + error_report("Failed to bind input parameter to store active object, rc = %d", rc);
76 + else
77 + rc = execute_insert(*res);
78 + return rc;
79 +}
80 +
81 +/*
82 + * Marks a chart with UUID as active
83 + * Input: UUID
84 + */
85 +void store_active_chart(uuid_t *chart_uuid)
86 +{
87 + sqlite3_stmt *res = NULL;
88 + int rc;
89 +
90 + if (unlikely(!db_meta)) {
91 + error_report("Database has not been initialized");
92 + return;
93 + }
94 +
95 + if (unlikely(!chart_uuid))
96 + return;
97 +
98 + rc = store_active_uuid_object(&res, SQL_STORE_ACTIVE_CHART, chart_uuid);
99 + if (rc != SQLITE_DONE)
100 + error_report("Failed to store active chart, rc = %d", rc);
101 +
102 + rc = sqlite3_finalize(res);
103 + if (unlikely(rc != SQLITE_OK))
104 + error_report("Failed to finalize statement in store active chart, rc = %d", rc);
105 + return;
106 +}
107 +
108 +/*
109 + * Marks a dimension with UUID as active
110 + * Input: UUID
111 + */
112 +void store_active_dimension(uuid_t *dimension_uuid)
113 +{
114 + sqlite3_stmt *res = NULL;
115 + int rc;
116 +
117 + if (unlikely(!db_meta)) {
118 + error_report("Database has not been initialized");
119 + return;
120 + }
121 +
122 + if (unlikely(!dimension_uuid))
123 + return;
124 +
125 + rc = store_active_uuid_object(&res, SQL_STORE_ACTIVE_DIMENSION, dimension_uuid);
126 + if (rc != SQLITE_DONE)
127 + error_report("Failed to store active dimension, rc = %d", rc);
128 +
129 + rc = sqlite3_finalize(res);
130 + if (unlikely(rc != SQLITE_OK))
131 + error_report("Failed to finalize statement in store active dimension, rc = %d", rc);
132 + return;
133 +}
134 +
135 +/*
136 + * Initialize the SQLite database
137 + * Return 0 on success
138 + */
139 +int sql_init_database(void)
140 +{
141 + char *err_msg = NULL;
142 + char sqlite_database[FILENAME_MAX + 1];
143 + int rc;
144 +
145 + fatal_assert(0 == uv_mutex_init(&sqlite_transaction_lock));
146 +
147 + snprintfz(sqlite_database, FILENAME_MAX, "%s/netdata-meta.db", netdata_configured_cache_dir);
148 + rc = sqlite3_open(sqlite_database, &db_meta);
149 + if (rc != SQLITE_OK) {
150 + error_report("Failed to initialize database at %s", sqlite_database);
151 + return 1;
152 + }
153 +
154 + info("SQLite database %s initialization", sqlite_database);
155 +
156 + for (int i = 0; database_config[i]; i++) {
157 + debug(D_METADATALOG, "Executing %s", database_config[i]);
158 + rc = sqlite3_exec(db_meta, database_config[i], 0, 0, &err_msg);
159 + if (rc != SQLITE_OK) {
160 + error_report("SQLite error during database setup, rc = %d (%s)", rc, err_msg);
161 + error_report("SQLite failed statement %s", database_config[i]);
162 + sqlite3_free(err_msg);
163 + return 1;
164 + }
165 + }
166 + info("SQLite database initialization completed");
167 + return 0;
168 +}
169 +
170 +/*
171 + * Close the sqlite database
172 + */
173 +
174 +void sql_close_database(void)
175 +{
176 + int rc;
177 + if (unlikely(!db_meta))
178 + return;
179 +
180 + info("Closing SQLite database");
181 + rc = sqlite3_close(db_meta);
182 + if (unlikely(rc != SQLITE_OK))
183 + error_report("Error %d while closing the SQLite database", rc);
184 + return;
185 +}
186 +
187 +/*
188 + * Return the database size in MiB
189 + */
190 +int sql_database_size(void)
191 +{
192 + sqlite3_stmt *chk_size;
193 + int rc;
194 +
195 + rc = sqlite3_prepare_v2(db_meta, "pragma page_count;", -1, &chk_size, 0);
196 + if (rc != SQLITE_OK)
197 + return 0;
198 +
199 + if (sqlite3_step(chk_size) == SQLITE_ROW)
200 + page_count = sqlite3_column_int(chk_size, 0);
201 +
202 + sqlite3_finalize(chk_size);
203 +
204 + rc = sqlite3_prepare_v2(db_meta, "pragma freelist_count;", -1, &chk_size, 0);
205 + if (rc != SQLITE_OK)
206 + return 0;
207 +
208 + if (sqlite3_step(chk_size) == SQLITE_ROW)
209 + free_page_count = sqlite3_column_int(chk_size, 0);
210 +
211 + sqlite3_finalize(chk_size);
212 +
213 + if (unlikely(!page_size)) {
214 + rc = sqlite3_prepare_v2(db_meta, "pragma page_size;", -1, &chk_size, 0);
215 + if (rc != SQLITE_OK)
216 + return 0;
217 +
218 + if (sqlite3_step(chk_size) == SQLITE_ROW)
219 + page_size = (uint32_t)sqlite3_column_int(chk_size, 0);
220 +
221 + sqlite3_finalize(chk_size);
222 + desired_pages = (sqlite_disk_quota_mb * 0.95) * (1024 * 1024 / page_size);
223 + info(
224 + "Database desired size is %u pages (page size is %u bytes). Current size is %u pages (includes %u free pages)",
225 + desired_pages, page_size, page_count, free_page_count);
226 + }
227 +
228 + return ((page_count - free_page_count) / 1024) * (page_size / 1024);
229 +}
230 +
231 +#define FIND_UUID_TYPE "select 1 from host where host_id = @uuid union select 2 from chart where chart_id = @uuid union select 3 from dimension where dim_id = @uuid;"
232 +
233 +int find_uuid_type(uuid_t *uuid)
234 +{
235 + static __thread sqlite3_stmt *res = NULL;
236 + int rc;
237 + int uuid_type = 3;
238 +
239 + if (unlikely(!res)) {
240 + rc = sqlite3_prepare_v2(db_meta, FIND_UUID_TYPE, -1, &res, 0);
241 + if (rc != SQLITE_OK) {
242 + error_report("Failed to bind prepare statement to find UUID type in the database");
243 + return 0;
244 + }
245 + }
246 +
247 + rc = sqlite3_bind_blob(res, 1, uuid, sizeof(*uuid), SQLITE_STATIC);
248 + if (unlikely(rc != SQLITE_OK))
249 + goto bind_fail;
250 +
251 + rc = sqlite3_step(res);
252 + if (likely(rc == SQLITE_ROW))
253 + uuid_type = sqlite3_column_int(res, 0);
254 +
255 + rc = sqlite3_reset(res);
256 + if (unlikely(rc != SQLITE_OK))
257 + error_report("Failed to reset statement during find uuid type, rc = %d", rc);
258 +
259 + return uuid_type;
260 +
261 +bind_fail:
262 + return 0;
263 +}
264 +
265 +uuid_t *find_dimension_uuid(RRDSET *st, RRDDIM *rd)
266 +{
267 + static __thread sqlite3_stmt *res = NULL;
268 + uuid_t *uuid = NULL;
269 + int rc;
270 +
271 + if (unlikely(!res)) {
272 + rc = sqlite3_prepare_v2(db_meta, SQL_FIND_DIMENSION_UUID, -1, &res, 0);
273 + if (rc != SQLITE_OK) {
274 + error_report("Failed to bind prepare statement to lookup dimension UUID in the database");
275 + return NULL;
276 + }
277 + }
278 +
279 + rc = sqlite3_bind_blob(res, 1, st->chart_uuid, sizeof(*st->chart_uuid), SQLITE_STATIC);
280 + if (unlikely(rc != SQLITE_OK))
281 + goto bind_fail;
282 +
283 + rc = sqlite3_bind_text(res, 2, rd->id, -1, SQLITE_STATIC);
284 + if (unlikely(rc != SQLITE_OK))
285 + goto bind_fail;
286 +
287 + rc = sqlite3_bind_text(res, 3, rd->name, -1, SQLITE_STATIC);
288 + if (unlikely(rc != SQLITE_OK))
289 + goto bind_fail;
290 +
291 + rc = sqlite3_step(res);
292 + if (likely(rc == SQLITE_ROW)) {
293 + uuid = mallocz(sizeof(uuid_t));
294 + uuid_copy(*uuid, sqlite3_column_blob(res, 0));
295 + }
296 +
297 + rc = sqlite3_reset(res);
298 + if (unlikely(rc != SQLITE_OK))
299 + error_report("Failed to reset statement find dimension uuid, rc = %d", rc);
300 +
301 +#ifdef NETDATA_INTERNAL_CHECKS
302 + char uuid_str[GUID_LEN + 1];
303 + if (likely(uuid)) {
304 + uuid_unparse_lower(*uuid, uuid_str);
305 + debug(D_METADATALOG, "Found UUID %s for dimension %s", uuid_str, rd->name);
306 + }
307 + else
308 + debug(D_METADATALOG, "UUID not found for dimension %s", rd->name);
309 +#endif
310 + return uuid;
311 +
312 +bind_fail:
313 + error_report("Failed to bind input parameter to perform dimension UUID database lookup, rc = %d", rc);
314 + return NULL;
315 +}
316 +
317 +uuid_t *create_dimension_uuid(RRDSET *st, RRDDIM *rd)
318 +{
319 + uuid_t *uuid = NULL;
320 + int rc;
321 +
322 + uuid = mallocz(sizeof(uuid_t));
323 + uuid_generate(*uuid);
324 +
325 +#ifdef NETDATA_INTERNAL_CHECKS
326 + char uuid_str[GUID_LEN + 1];
327 + uuid_unparse_lower(*uuid, uuid_str);
328 + debug(D_METADATALOG,"Generating uuid [%s] for dimension %s under chart %s", uuid_str, rd->name, st->id);
329 +#endif
330 +
331 + rc = sql_store_dimension(uuid, st->chart_uuid, rd->id, rd->name, rd->multiplier, rd->divisor, rd->algorithm);
332 + if (unlikely(rc))
333 + error_report("Failed to store dimension metadata in the database");
334 +
335 + return uuid;
336 +}
337 +
338 +#define DELETE_DIMENSION_UUID "delete from dimension where dim_id = @uuid;"
339 +
340 +void delete_dimension_uuid(uuid_t *dimension_uuid)
341 +{
342 + static __thread sqlite3_stmt *res = NULL;
343 + int rc;
344 +
345 +#ifdef NETDATA_INTERNAL_CHECKS
346 + char uuid_str[GUID_LEN + 1];
347 + uuid_unparse_lower(*dimension_uuid, uuid_str);
348 + debug(D_METADATALOG,"Deleting dimension uuid %s", uuid_str);
349 +#endif
350 +
351 + if (unlikely(!res)) {
352 + rc = sqlite3_prepare_v2(db_meta, DELETE_DIMENSION_UUID, -1, &res, 0);
353 + if (rc != SQLITE_OK) {
354 + error_report("Failed to prepare statement to delete a dimension uuid");
355 + return;
356 + }
357 + }
358 +
359 + rc = sqlite3_bind_blob(res, 1, dimension_uuid, sizeof(*dimension_uuid), SQLITE_STATIC);
360 + if (unlikely(rc != SQLITE_OK))
361 + goto bind_fail;
362 +
363 + rc = sqlite3_step(res);
364 + if (unlikely(rc != SQLITE_DONE))
365 + error_report("Failed to delete dimension uuid, rc = %d", rc);
366 +
367 +bind_fail:
368 + rc = sqlite3_reset(res);
369 + if (unlikely(rc != SQLITE_OK))
370 + error_report("Failed to reset statement when deleting dimension UUID, rc = %d", rc);
371 + return;
372 +}
373 +
374 +/*
375 + * Do a database lookup to find the UUID of a chart
376 + *
377 + */
378 +uuid_t *find_chart_uuid(RRDHOST *host, const char *type, const char *id, const char *name)
379 +{
380 + static __thread sqlite3_stmt *res = NULL;
381 + uuid_t *uuid = NULL;
382 + int rc;
383 +
384 + if (unlikely(!res)) {
385 + rc = sqlite3_prepare_v2(db_meta, SQL_FIND_CHART_UUID, -1, &res, 0);
386 + if (rc != SQLITE_OK) {
387 + error_report("Failed to prepare statement to lookup chart UUID in the database");
388 + return NULL;
389 + }
390 + }
391 +
392 + rc = sqlite3_bind_blob(res, 1, &host->host_uuid, sizeof(host->host_uuid), SQLITE_STATIC);
393 + if (unlikely(rc != SQLITE_OK))
394 + goto bind_fail;
395 +
396 + rc = sqlite3_bind_text(res, 2, type, -1, SQLITE_STATIC);
397 + if (unlikely(rc != SQLITE_OK))
398 + goto bind_fail;
399 +
400 + rc = sqlite3_bind_text(res, 3, id, -1, SQLITE_STATIC);
401 + if (unlikely(rc != SQLITE_OK))
402 + goto bind_fail;
403 +
404 + rc = sqlite3_bind_text(res, 4, name ? name : id, -1, SQLITE_STATIC);
405 + if (unlikely(rc != SQLITE_OK))
406 + goto bind_fail;
407 +
408 + rc = sqlite3_step(res);
409 + if (likely(rc == SQLITE_ROW)) {
410 + uuid = mallocz(sizeof(uuid_t));
411 + uuid_copy(*uuid, sqlite3_column_blob(res, 0));
412 + }
413 +
414 + rc = sqlite3_reset(res);
415 + if (unlikely(rc != SQLITE_OK))
416 + error_report("Failed to reset statement when searching for a chart UUID, rc = %d", rc);
417 +
418 +#ifdef NETDATA_INTERNAL_CHECKS
419 + char uuid_str[GUID_LEN + 1];
420 + if (likely(uuid)) {
421 + uuid_unparse_lower(*uuid, uuid_str);
422 + debug(D_METADATALOG, "Found UUID %s for chart %s.%s", uuid_str, type, name ? name : id);
423 + }
424 + else
425 + debug(D_METADATALOG, "UUID not found for chart %s.%s", type, name ? name : id);
426 +#endif
427 + return uuid;
428 +
429 +bind_fail:
430 + error_report("Failed to bind input parameter to perform chart UUID database lookup, rc = %d", rc);
431 + rc = sqlite3_reset(res);
432 + if (unlikely(rc != SQLITE_OK))
433 + error_report("Failed to reset statement when searching for a chart UUID, rc = %d", rc);
434 + return NULL;
435 +}
436 +
437 +int update_chart_metadata(uuid_t *chart_uuid, RRDSET *st, const char *id, const char *name)
438 +{
439 + int rc;
440 +
441 + rc = sql_store_chart(
442 + chart_uuid, &st->rrdhost->host_uuid, st->type, id, name, st->family, st->context, st->title, st->units, st->plugin_name,
443 + st->module_name, st->priority, st->update_every, st->chart_type, st->rrd_memory_mode, st->entries);
444 +
445 + return rc;
446 +}
447 +
448 +uuid_t *create_chart_uuid(RRDSET *st, const char *id, const char *name)
449 +{
450 + uuid_t *uuid = NULL;
451 + int rc;
452 +
453 + uuid = mallocz(sizeof(uuid_t));
454 + uuid_generate(*uuid);
455 +
456 +#ifdef NETDATA_INTERNAL_CHECKS
457 + char uuid_str[GUID_LEN + 1];
458 + uuid_unparse_lower(*uuid, uuid_str);
459 + debug(D_METADATALOG,"Generating uuid [%s] for chart %s under host %s", uuid_str, st->id, st->rrdhost->hostname);
460 +#endif
461 +
462 + rc = update_chart_metadata(uuid, st, id, name);
463 +
464 + if (unlikely(rc))
465 + error_report("Failed to store chart metadata in the database");
466 +
467 + return uuid;
468 +}
469 +
470 +// Functions to create host, chart, dimension in the database
471 +
472 +int sql_store_host(
473 + uuid_t *host_uuid, const char *hostname, const char *registry_hostname, int update_every, const char *os,
474 + const char *tzone, const char *tags)
475 +{
476 + static __thread sqlite3_stmt *res = NULL;
477 + int rc;
478 +
479 + if (unlikely(!db_meta)) {
480 + error_report("Database has not been initialized");
481 + return 1;
482 + }
483 +
484 + if (unlikely((!res))) {
485 + rc = sqlite3_prepare_v2(db_meta, SQL_STORE_HOST, -1, &res, 0);
486 + if (unlikely(rc != SQLITE_OK)) {
487 + error_report("Failed to prepare statement to store host, rc = %d", rc);
488 + return 1;
489 + }
490 + }
491 +
492 + rc = sqlite3_bind_blob(res, 1, host_uuid, sizeof(*host_uuid), SQLITE_STATIC);
493 + if (unlikely(rc != SQLITE_OK))
494 + goto bind_fail;
495 +
496 + rc = sqlite3_bind_text(res, 2, hostname, -1, SQLITE_STATIC);
497 + if (unlikely(rc != SQLITE_OK))
498 + goto bind_fail;
499 +
500 + rc = sqlite3_bind_text(res, 3, registry_hostname, -1, SQLITE_STATIC);
501 + if (unlikely(rc != SQLITE_OK))
502 + goto bind_fail;
503 +
504 + rc = sqlite3_bind_int(res, 4, update_every);
505 + if (unlikely(rc != SQLITE_OK))
506 + goto bind_fail;
507 +
508 + rc = sqlite3_bind_text(res, 5, os, -1, SQLITE_STATIC);
509 + if (unlikely(rc != SQLITE_OK))
510 + goto bind_fail;
511 +
512 + rc = sqlite3_bind_text(res, 6, tzone, -1, SQLITE_STATIC);
513 + if (unlikely(rc != SQLITE_OK))
514 + goto bind_fail;
515 +
516 + rc = sqlite3_bind_text(res, 7, tags, -1, SQLITE_STATIC);
517 + if (unlikely(rc != SQLITE_OK))
518 + goto bind_fail;
519 +
520 + int store_rc = sqlite3_step(res);
521 + if (unlikely(store_rc != SQLITE_DONE))
522 + error_report("Failed to store host %s, rc = %d", hostname, rc);
523 +
524 + rc = sqlite3_reset(res);
525 + if (unlikely(rc != SQLITE_OK))
526 + error_report("Failed to reset statement to store host %s, rc = %d", hostname, rc);
527 +
528 + return !(store_rc == SQLITE_DONE);
529 +bind_fail:
530 + error_report("Failed to bind parameter to store host %s, rc = %d", hostname, rc);
531 + rc = sqlite3_reset(res);
532 + if (unlikely(rc != SQLITE_OK))
533 + error_report("Failed to reset statement to store host %s, rc = %d", hostname, rc);
534 + return 1;
535 +}
536 +
537 +/*
538 + * Store a chart in the database
539 + */
540 +
541 +int sql_store_chart(
542 + uuid_t *chart_uuid, uuid_t *host_uuid, const char *type, const char *id, const char *name, const char *family,
543 + const char *context, const char *title, const char *units, const char *plugin, const char *module, long priority,
544 + int update_every, int chart_type, int memory_mode, long history_entries)
545 +{
546 + static __thread sqlite3_stmt *res;
547 + int rc, param = 0;
548 +
549 + if (unlikely(!db_meta)) {
550 + error_report("Database has not been initialized");
551 + return 1;
552 + }
553 +
554 + if (unlikely(!res)) {
555 + rc = sqlite3_prepare_v2(db_meta, SQL_STORE_CHART, -1, &res, 0);
556 + if (unlikely(rc != SQLITE_OK)) {
557 + error_report("Failed to prepare statement to store chart, rc = %d", rc);
558 + return 1;
559 + }
560 + }
561 +
562 + param++;
563 + rc = sqlite3_bind_blob(res, 1, chart_uuid, sizeof(*chart_uuid), SQLITE_STATIC);
564 + if (unlikely(rc != SQLITE_OK))
565 + goto bind_fail;
566 +
567 + param++;
568 + rc = sqlite3_bind_blob(res, 2, host_uuid, sizeof(*host_uuid), SQLITE_STATIC);
569 + if (unlikely(rc != SQLITE_OK))
570 + goto bind_fail;
571 +
572 + param++;
573 + rc = sqlite3_bind_text(res, 3, type, -1, SQLITE_STATIC);
574 + if (unlikely(rc != SQLITE_OK))
575 + goto bind_fail;
576 +
577 + param++;
578 + rc = sqlite3_bind_text(res, 4, id, -1, SQLITE_STATIC);
579 + if (unlikely(rc != SQLITE_OK))
580 + goto bind_fail;
581 +
582 + param++;
583 + if (name) {
584 + rc = sqlite3_bind_text(res, 5, name, -1, SQLITE_STATIC);
585 + if (unlikely(rc != SQLITE_OK))
586 + goto bind_fail;
587 + }
588 +
589 + param++;
590 + rc = sqlite3_bind_text(res, 6, family, -1, SQLITE_STATIC);
591 + if (unlikely(rc != SQLITE_OK))
592 + goto bind_fail;
593 +
594 + param++;
595 + rc = sqlite3_bind_text(res, 7, context, -1, SQLITE_STATIC);
596 + if (unlikely(rc != SQLITE_OK))
597 + goto bind_fail;
598 +
599 + param++;
600 + rc = sqlite3_bind_text(res, 8, title, -1, SQLITE_STATIC);
601 + if (unlikely(rc != SQLITE_OK))
602 + goto bind_fail;
603 +
604 + param++;
605 + rc = sqlite3_bind_text(res, 9, units, -1, SQLITE_STATIC);
606 + if (unlikely(rc != SQLITE_OK))
607 + goto bind_fail;
608 +
609 + param++;
610 + rc = sqlite3_bind_text(res, 10, plugin, -1, SQLITE_STATIC);
611 + if (unlikely(rc != SQLITE_OK))
612 + goto bind_fail;
613 +
614 + param++;
615 + rc = sqlite3_bind_text(res, 11, module, -1, SQLITE_STATIC);
616 + if (unlikely(rc != SQLITE_OK))
617 + goto bind_fail;
618 +
619 + param++;
620 + rc = sqlite3_bind_int(res, 12, priority);
621 + if (unlikely(rc != SQLITE_OK))
622 + goto bind_fail;
623 +
624 + param++;
625 + rc = sqlite3_bind_int(res, 13, update_every);
626 + if (unlikely(rc != SQLITE_OK))
627 + goto bind_fail;
628 +
629 + param++;
630 + rc = sqlite3_bind_int(res, 14, chart_type);
631 + if (unlikely(rc != SQLITE_OK))
632 + goto bind_fail;
633 +
634 + param++;
635 + rc = sqlite3_bind_int(res, 15, memory_mode);
636 + if (unlikely(rc != SQLITE_OK))
637 + goto bind_fail;
638 +
639 + param++;
640 + rc = sqlite3_bind_int(res, 16, history_entries);
641 + if (unlikely(rc != SQLITE_OK))
642 + goto bind_fail;
643 +
644 + rc = execute_insert(res);
645 + if (unlikely(rc != SQLITE_DONE))
646 + error_report("Failed to store chart, rc = %d", rc);
647 +
648 + rc = sqlite3_reset(res);
649 + if (unlikely(rc != SQLITE_OK))
650 + error_report("Failed to reset statement in chart store function, rc = %d", rc);
651 +
652 + return 0;
653 +
654 +bind_fail:
655 + error_report("Failed to bind parameter %d to store chart, rc = %d", param, rc);
656 + rc = sqlite3_reset(res);
657 + if (unlikely(rc != SQLITE_OK))
658 + error_report("Failed to reset statement in chart store function, rc = %d", rc);
659 + return 1;
660 +}
661 +
662 +/*
663 + * Store a dimension
664 + */
665 +int sql_store_dimension(
666 + uuid_t *dim_uuid, uuid_t *chart_uuid, const char *id, const char *name, collected_number multiplier,
667 + collected_number divisor, int algorithm)
668 +{
669 + static __thread sqlite3_stmt *res = NULL;
670 + int rc;
671 +
672 + if (unlikely(!db_meta)) {
673 + error_report("Database has not been initialized");
674 + return 1;
675 + }
676 +
677 + if (unlikely(!res)) {
678 + rc = sqlite3_prepare_v2(db_meta, SQL_STORE_DIMENSION, -1, &res, 0);
679 + if (unlikely(rc != SQLITE_OK)) {
680 + error_report("Failed to prepare statement to store dimension, rc = %d", rc);
681 + return 1;
682 + }
683 + }
684 +
685 + rc = sqlite3_bind_blob(res, 1, dim_uuid, sizeof(*dim_uuid), SQLITE_STATIC);
686 + if (unlikely(rc != SQLITE_OK))
687 + goto bind_fail;
688 +
689 + rc = sqlite3_bind_blob(res, 2, chart_uuid, sizeof(*chart_uuid), SQLITE_STATIC);
690 + if (unlikely(rc != SQLITE_OK))
691 + goto bind_fail;
692 +
693 + rc = sqlite3_bind_text(res, 3, id, -1, SQLITE_STATIC);
694 + if (unlikely(rc != SQLITE_OK))
695 + goto bind_fail;
696 +
697 + rc = sqlite3_bind_text(res, 4, name, -1, SQLITE_STATIC);
698 + if (unlikely(rc != SQLITE_OK))
699 + goto bind_fail;
700 +
701 + rc = sqlite3_bind_int(res, 5, multiplier);
702 + if (unlikely(rc != SQLITE_OK))
703 + goto bind_fail;
704 +
705 + rc = sqlite3_bind_int(res, 6, divisor);
706 + if (unlikely(rc != SQLITE_OK))
707 + goto bind_fail;
708 +
709 + rc = sqlite3_bind_int(res, 7, algorithm);
710 + if (unlikely(rc != SQLITE_OK))
711 + goto bind_fail;
712 +
713 + rc = execute_insert(res);
714 + if (unlikely(rc != SQLITE_DONE))
715 + error_report("Failed to store dimension, rc = %d", rc);
716 +
717 + rc = sqlite3_reset(res);
718 + if (unlikely(rc != SQLITE_OK))
719 + error_report("Failed to reset statement in store dimension, rc = %d", rc);
720 + return 0;
721 +
722 +bind_fail:
723 + error_report("Failed to bind parameter to store dimension, rc = %d", rc);
724 + rc = sqlite3_reset(res);
725 + if (unlikely(rc != SQLITE_OK))
726 + error_report("Failed to reset statement in store dimension, rc = %d", rc);
727 + return 1;
728 +}
729 +
730 +
731 +//
732 +// Support for archived charts
733 +//
734 +#define SELECT_DIMENSION "select d.id, d.name from dimension d where d.chart_id = @chart_uuid;"
735 +
736 +void sql_rrdim2json(sqlite3_stmt *res_dim, uuid_t *chart_uuid, BUFFER *wb, size_t *dimensions_count)
737 +{
738 + int rc;
739 +
740 + rc = sqlite3_bind_blob(res_dim, 1, chart_uuid, sizeof(*chart_uuid), SQLITE_STATIC);
741 + if (rc != SQLITE_OK)
742 + return;
743 +
744 + int dimensions = 0;
745 + buffer_sprintf(wb, "\t\t\t\"dimensions\": {\n");
746 +
747 + while (sqlite3_step(res_dim) == SQLITE_ROW) {
748 + if (dimensions)
749 + buffer_strcat(wb, ",\n\t\t\t\t\"");
750 + else
751 + buffer_strcat(wb, "\t\t\t\t\"");
752 + buffer_strcat_jsonescape(wb, (const char *) sqlite3_column_text(res_dim, 0));
753 + buffer_strcat(wb, "\": { \"name\": \"");
754 + buffer_strcat_jsonescape(wb, (const char *) sqlite3_column_text(res_dim, 1));
755 + buffer_strcat(wb, "\" }");
756 + dimensions++;
757 + }
758 + *dimensions_count += dimensions;
759 + buffer_sprintf(wb, "\n\t\t\t}");
760 +}
761 +
762 +#define SELECT_CHART "select chart_id, id, name, type, family, context, title, priority, plugin, " \
763 + "module, unit, chart_type, update_every from chart " \
764 + "where host_id = @host_uuid and chart_id not in (select chart_id from chart_active) order by chart_id asc;"
765 +
766 +void sql_rrdset2json(RRDHOST *host, BUFFER *wb)
767 +{
768 + // time_t first_entry_t = 0; //= rrdset_first_entry_t(st);
769 + // time_t last_entry_t = 0; //rrdset_last_entry_t(st);
770 + static char *custom_dashboard_info_js_filename = NULL;
771 + int rc;
772 +
773 + sqlite3_stmt *res_chart = NULL;
774 + sqlite3_stmt *res_dim = NULL;
775 + time_t now = now_realtime_sec();
776 +
777 + rc = sqlite3_prepare_v2(db_meta, SELECT_CHART, -1, &res_chart, 0);
778 + if (unlikely(rc != SQLITE_OK)) {
779 + error_report("Failed to prepare statement to fetch host archived charts");
780 + return;
781 + }
782 +
783 + rc = sqlite3_bind_blob(res_chart, 1, &host->host_uuid, sizeof(host->host_uuid), SQLITE_STATIC);
784 + if (unlikely(rc != SQLITE_OK)) {
785 + error_report("Failed to bind host parameter to fetch archived charts");
786 + return;
787 + }
788 +
789 + rc = sqlite3_prepare_v2(db_meta, SELECT_DIMENSION, -1, &res_dim, 0);
790 + if (unlikely(rc != SQLITE_OK)) {
791 + error_report("Failed to prepare statement to fetch chart archived dimensions");
792 + goto failed;
793 + };
794 +
795 + if(unlikely(!custom_dashboard_info_js_filename))
796 + custom_dashboard_info_js_filename = config_get(CONFIG_SECTION_WEB, "custom dashboard_info.js", "");
797 +
798 + buffer_sprintf(wb, "{\n"
799 + "\t\"hostname\": \"%s\""
800 + ",\n\t\"version\": \"%s\""
801 + ",\n\t\"release_channel\": \"%s\""
802 + ",\n\t\"os\": \"%s\""
803 + ",\n\t\"timezone\": \"%s\""
804 + ",\n\t\"update_every\": %d"
805 + ",\n\t\"history\": %ld"
806 + ",\n\t\"memory_mode\": \"%s\""
807 + ",\n\t\"custom_info\": \"%s\""
808 + ",\n\t\"charts\": {"
809 + , host->hostname
810 + , host->program_version
811 + , get_release_channel()
812 + , host->os
813 + , host->timezone
814 + , host->rrd_update_every
815 + , host->rrd_history_entries
816 + , rrd_memory_mode_name(host->rrd_memory_mode)
817 + , custom_dashboard_info_js_filename
818 + );
819 +
820 + size_t c = 0;
821 + size_t dimensions = 0;
822 +
823 + while (sqlite3_step(res_chart) == SQLITE_ROW) {
824 + char id[512];
825 + sprintf(id, "%s.%s", sqlite3_column_text(res_chart, 3), sqlite3_column_text(res_chart, 1));
826 + RRDSET *st = rrdset_find(host, id);
827 + if (st && !rrdset_flag_check(st, RRDSET_FLAG_ARCHIVED))
828 + continue;
829 +
830 + if (c)
831 + buffer_strcat(wb, ",\n\t\t\"");
832 + else
833 + buffer_strcat(wb, "\n\t\t\"");
834 + c++;
835 +
836 + buffer_strcat(wb, id);
837 + buffer_strcat(wb, "\": ");
838 +
839 + buffer_sprintf(
840 + wb,
841 + "\t\t{\n"
842 + "\t\t\t\"id\": \"%s\",\n"
843 + "\t\t\t\"name\": \"%s\",\n"
844 + "\t\t\t\"type\": \"%s\",\n"
845 + "\t\t\t\"family\": \"%s\",\n"
846 + "\t\t\t\"context\": \"%s\",\n"
847 + "\t\t\t\"title\": \"%s (%s)\",\n"
848 + "\t\t\t\"priority\": %ld,\n"
849 + "\t\t\t\"plugin\": \"%s\",\n"
850 + "\t\t\t\"module\": \"%s\",\n"
851 + "\t\t\t\"enabled\": %s,\n"
852 + "\t\t\t\"units\": \"%s\",\n"
853 + "\t\t\t\"data_url\": \"/api/v1/data?chart=%s\",\n"
854 + "\t\t\t\"chart_type\": \"%s\",\n",
855 + id //sqlite3_column_text(res_chart, 1)
856 + ,
857 + id // sqlite3_column_text(res_chart, 2)
858 + ,
859 + sqlite3_column_text(res_chart, 3), sqlite3_column_text(res_chart, 4), sqlite3_column_text(res_chart, 5),
860 + sqlite3_column_text(res_chart, 6), id //sqlite3_column_text(res_chart, 2)
861 + ,
862 + (long ) sqlite3_column_int(res_chart, 7),
863 + (const char *) sqlite3_column_text(res_chart, 8) ? (const char *) sqlite3_column_text(res_chart, 8) : (char *) "",
864 + (const char *) sqlite3_column_text(res_chart, 9) ? (const char *) sqlite3_column_text(res_chart, 9) : (char *) "", (char *) "false",
865 + (const char *) sqlite3_column_text(res_chart, 10), id //sqlite3_column_text(res_chart, 2)
866 + ,
867 + rrdset_type_name(sqlite3_column_int(res_chart, 11)));
868 +
869 + sql_rrdim2json(res_dim, (uuid_t *) sqlite3_column_blob(res_chart, 0), wb, &dimensions);
870 +
871 + rc = sqlite3_reset(res_dim);
872 + if (unlikely(rc != SQLITE_OK))
873 + error_report("Failed to reset the prepared statement when reading archived chart dimensions");
874 + buffer_strcat(wb, "\n\t\t}");
875 + }
876 +
877 + buffer_sprintf(wb
878 + , "\n\t}"
879 + ",\n\t\"charts_count\": %zu"
880 + ",\n\t\"dimensions_count\": %zu"
881 + ",\n\t\"alarms_count\": %zu"
882 + ",\n\t\"rrd_memory_bytes\": %zu"
883 + ",\n\t\"hosts_count\": %zu"
884 + ",\n\t\"hosts\": ["
885 + , c
886 + , dimensions
887 + , (size_t) 0
888 + , (size_t) 0
889 + , rrd_hosts_available
890 + );
891 +
892 + if(unlikely(rrd_hosts_available > 1)) {
893 + rrd_rdlock();
894 +
895 + size_t found = 0;
896 + RRDHOST *h;
897 + rrdhost_foreach_read(h) {
898 + if(!rrdhost_should_be_removed(h, host, now) && !rrdhost_flag_check(h, RRDHOST_FLAG_ARCHIVED)) {
899 + buffer_sprintf(wb
900 + , "%s\n\t\t{"
901 + "\n\t\t\t\"hostname\": \"%s\""
902 + "\n\t\t}"
903 + , (found > 0) ? "," : ""
904 + , h->hostname
905 + );
906 +
907 + found++;
908 + }
909 + }
910 +
911 + rrd_unlock();
912 + }
913 + else {
914 + buffer_sprintf(wb
915 + , "\n\t\t{"
916 + "\n\t\t\t\"hostname\": \"%s\""
917 + "\n\t\t}"
918 + , host->hostname
919 + );
920 + }
921 +
922 + buffer_sprintf(wb, "\n\t]\n}\n");
923 +
924 + rc = sqlite3_finalize(res_dim);
925 + if (unlikely(rc != SQLITE_OK))
926 + error_report("Failed to finalize the prepared statement when reading archived chart dimensions");
927 +
928 +failed:
929 + rc = sqlite3_finalize(res_chart);
930 + if (unlikely(rc != SQLITE_OK))
931 + error_report("Failed to finalize the prepared statement when reading archived charts");
932 +
933 + return;
934 +}
935 +
936 +#define SELECT_HOST "select host_id, registry_hostname, update_every, os, timezone, tags from host where hostname = @hostname;"
937 +
938 +RRDHOST *sql_create_host_by_uuid(char *hostname)
939 +{
940 + int rc;
941 + RRDHOST *host = NULL;
942 +
943 + sqlite3_stmt *res = NULL;
944 +
945 + rc = sqlite3_prepare_v2(db_meta, SELECT_HOST, -1, &res, 0);
946 + if (unlikely(rc != SQLITE_OK)) {
947 + error_report("Failed to prepare statement to fetch host");
948 + return NULL;
949 + }
950 +
951 + rc = sqlite3_bind_text(res, 1, hostname, -1, SQLITE_STATIC);
952 + if (unlikely(rc != SQLITE_OK)) {
953 + error_report("Failed to bind hostname parameter to fetch host information");
954 + return NULL;
955 + }
956 +
957 + rc = sqlite3_step(res);
958 + if (unlikely(rc != SQLITE_ROW)) {
959 + error_report("Failed to find hostname %s", hostname);
960 + goto failed;
961 + }
962 +
963 + char uuid_str[GUID_LEN + 1];
964 + uuid_unparse_lower(*((uuid_t *) sqlite3_column_blob(res, 0)), uuid_str);
965 +
966 + host = callocz(1, sizeof(RRDHOST));
967 +
968 + set_host_properties(host, sqlite3_column_int(res, 2), RRD_MEMORY_MODE_DBENGINE, hostname,
969 + (char *) sqlite3_column_text(res, 1), (const char *) uuid_str,
970 + (char *) sqlite3_column_text(res, 3), (char *) sqlite3_column_text(res, 5),
971 + (char *) sqlite3_column_text(res, 4), NULL, NULL);
972 +
973 + uuid_copy(host->host_uuid, *((uuid_t *) sqlite3_column_blob(res, 0)));
974 +
975 + host->system_info = NULL;
976 +
977 +failed:
978 + rc = sqlite3_finalize(res);
979 + if (unlikely(rc != SQLITE_OK))
980 + error_report("Failed to finalize the prepared statement when reading host information");
981 +
982 + return host;
983 +}
984 +
985 +void db_execute(char *cmd)
986 +{
987 + int rc;
988 + char *err_msg;
989 + rc = sqlite3_exec(db_meta, cmd, 0, 0, &err_msg);
990 + if (rc != SQLITE_OK) {
991 + error_report("Failed to execute '%s', rc = %d (%s)", cmd, rc, err_msg);
992 + sqlite3_free(err_msg);
993 + }
994 +
995 + return;
996 +}
997 +
998 +void db_lock(void)
999 +{
1000 + uv_mutex_lock(&sqlite_transaction_lock);
1001 + return;
1002 +}
1003 +
1004 +void db_unlock(void)
1005 +{
1006 + uv_mutex_unlock(&sqlite_transaction_lock);
1007 + return;
1008 +}
1009 +
1010 +
1011 +#define SELECT_MIGRATED_FILE "select 1 from metadata_migration where filename = @path;"
1012 +
1013 +int file_is_migrated(char *path)
1014 +{
1015 + sqlite3_stmt *res = NULL;
1016 + int rc;
1017 +
1018 + rc = sqlite3_prepare_v2(db_meta, SELECT_MIGRATED_FILE, -1, &res, 0);
1019 + if (unlikely(rc != SQLITE_OK)) {
1020 + error_report("Failed to prepare statement to fetch host");
1021 + return 0;
1022 + }
1023 +
1024 + rc = sqlite3_bind_text(res, 1, path, -1, SQLITE_STATIC);
1025 + if (unlikely(rc != SQLITE_OK)) {
1026 + error_report("Failed to bind filename parameter to check migration");
1027 + return 0;
1028 + }
1029 +
1030 + rc = sqlite3_step(res);
1031 +
1032 + if (unlikely(sqlite3_finalize(res) != SQLITE_OK))
1033 + error_report("Failed to finalize the prepared statement when checking if metadata file is migrated");
1034 +
1035 + return (rc == SQLITE_ROW);
1036 +}
1037 +
1038 +#define STORE_MIGRATED_FILE "insert or replace into metadata_migration (filename, file_size, date_created) " \
1039 + "values (@file, @size, strftime('%s'));"
1040 +
1041 +void add_migrated_file(char *path, uint64_t file_size)
1042 +{
1043 + sqlite3_stmt *res = NULL;
1044 + int rc;
1045 +
1046 + rc = sqlite3_prepare_v2(db_meta, STORE_MIGRATED_FILE, -1, &res, 0);
1047 + if (unlikely(rc != SQLITE_OK)) {
1048 + error_report("Failed to prepare statement to fetch host");
1049 + return;
1050 + }
1051 +
1052 + rc = sqlite3_bind_text(res, 1, path, -1, SQLITE_STATIC);
1053 + if (unlikely(rc != SQLITE_OK)) {
1054 + error_report("Failed to bind filename parameter to store migration information");
1055 + return;
1056 + }
1057 +
1058 + rc = sqlite3_bind_int64(res, 2, file_size);
1059 + if (unlikely(rc != SQLITE_OK)) {
1060 + error_report("Failed to bind size parameter to store migration information");
1061 + return;
1062 + }
1063 +
1064 + rc = execute_insert(res);
1065 + if (unlikely(rc != SQLITE_DONE))
1066 + error_report("Failed to store migrated file, rc = %d", rc);
1067 +
1068 + if (unlikely(sqlite3_finalize(res) != SQLITE_OK))
1069 + error_report("Failed to finalize the prepared statement when checking if metadata file is migrated");
1070 +
1071 + return;
1072 +}
database/sqlite/sqlite_functions.h new
+62
@@ -0,0 +1,62 @@
1 +// SPDX-License-Identifier: GPL-3.0-or-later
2 +
3 +#ifndef NETDATA_SQLITE_FUNCTIONS_H
4 +#define NETDATA_SQLITE_FUNCTIONS_H
5 +
6 +#include "../../daemon/common.h"
7 +#include "sqlite3.h"
8 +
9 +#define SQLITE_INSERT_DELAY (50) // Insert delay in case of lock
10 +
11 +#define SQL_STORE_HOST "insert or replace into host (host_id,hostname,registry_hostname,update_every,os,timezone,tags) values (?1,?2,?3,?4,?5,?6,?7);"
12 +
13 +#define SQL_STORE_CHART "insert or replace into chart (chart_id, host_id, type, id, " \
14 + "name, family, context, title, unit, plugin, module, priority, update_every , chart_type , memory_mode , " \
15 + "history_entries) values (?1,?2,?3,?4,?5,?6,?7,?8,?9,?10,?11,?12,?13,?14,?15,?16);"
16 +
17 +#define SQL_FIND_CHART_UUID \
18 + "select chart_id from chart where host_id = @host and type=@type and id=@id and (name is null or name=@name);"
19 +
20 +#define SQL_STORE_ACTIVE_CHART \
21 + "insert or replace into chart_active (chart_id, date_created) values (@id, strftime('%s'));"
22 +
23 +#define SQL_STORE_DIMENSION \
24 + "INSERT OR REPLACE into dimension (dim_id, chart_id, id, name, multiplier, divisor , algorithm) values (?0001,?0002,?0003,?0004,?0005,?0006,?0007);"
25 +
26 +#define SQL_FIND_DIMENSION_UUID "select dim_id from dimension where chart_id=@chart and id=@id and name=@name;"
27 +
28 +#define SQL_STORE_ACTIVE_DIMENSION \
29 + "insert or replace into dimension_active (dim_id, date_created) values (@id, strftime('%s'));"
30 +extern int sql_init_database(void);
31 +extern void sql_close_database(void);
32 +
33 +extern int sql_store_host(uuid_t *guid, const char *hostname, const char *registry_hostname, int update_every, const char *os, const char *timezone, const char *tags);
34 +extern int sql_store_chart(
35 + uuid_t *chart_uuid, uuid_t *host_uuid, const char *type, const char *id, const char *name, const char *family,
36 + const char *context, const char *title, const char *units, const char *plugin, const char *module, long priority,
37 + int update_every, int chart_type, int memory_mode, long history_entries);
38 +extern int sql_store_dimension(uuid_t *dim_uuid, uuid_t *chart_uuid, const char *id, const char *name, collected_number multiplier,
39 + collected_number divisor, int algorithm);
40 +
41 +extern uuid_t *find_dimension_uuid(RRDSET *st, RRDDIM *rd);
42 +extern uuid_t *create_dimension_uuid(RRDSET *st, RRDDIM *rd);
43 +extern void store_active_dimension(uuid_t *dimension_uuid);
44 +
45 +extern uuid_t *find_chart_uuid(RRDHOST *host, const char *type, const char *id, const char *name);
46 +extern uuid_t *create_chart_uuid(RRDSET *st, const char *id, const char *name);
47 +extern int update_chart_metadata(uuid_t *chart_uuid, RRDSET *st, const char *id, const char *name);
48 +extern void store_active_chart(uuid_t *dimension_uuid);
49 +
50 +extern int find_uuid_type(uuid_t *uuid);
51 +
52 +extern void sql_rrdset2json(RRDHOST *host, BUFFER *wb);
53 +
54 +extern RRDHOST *sql_create_host_by_uuid(char *guid);
55 +extern void db_execute(char *cmd);
56 +extern int file_is_migrated(char *path);
57 +extern void add_migrated_file(char *path, uint64_t file_size);
58 +extern void db_unlock(void);
59 +extern void db_lock(void);
60 +extern void delete_dimension_uuid(uuid_t *dimension_uuid);
61 +
62 +#endif //NETDATA_SQLITE_FUNCTIONS_H
exporting/tests/netdata_doubles.c
+2 -10
@@ -100,9 +100,7 @@ RRDSET *rrdset_create_custom(
100 int update_every,
101 RRDSET_TYPE chart_type,
102 RRD_MEMORY_MODE memory_mode,
103 - long history_entries,
104 - int is_archived,
105 - uuid_t *chart_uuid)
103 + long history_entries)
104 {
105 check_expected_ptr(host);
106 check_expected_ptr(type);
@@ -119,8 +117,6 @@ RRDSET *rrdset_create_custom(
117 check_expected(chart_type);
118 UNUSED(memory_mode);
119 UNUSED(history_entries);
122 - UNUSED(is_archived);
123 - UNUSED(chart_uuid);
120
121 function_called();
122
@@ -149,9 +145,7 @@ RRDDIM *rrddim_add_custom(
145 collected_number multiplier,
146 collected_number divisor,
147 RRD_ALGORITHM algorithm,
152 - RRD_MEMORY_MODE memory_mode,
153 - int is_archived,
154 - uuid_t *dim_uuid)
148 + RRD_MEMORY_MODE memory_mode)
149 {
150 check_expected_ptr(st);
151 UNUSED(id);
@@ -160,8 +154,6 @@ RRDDIM *rrddim_add_custom(
154 check_expected(divisor);
155 check_expected(algorithm);
156 UNUSED(memory_mode);
163 - UNUSED(is_archived);
164 - UNUSED(dim_uuid);
157
158 function_called();
159
libnetdata/libnetdata.h
+1
@@ -295,6 +295,7 @@ extern char *read_by_filename(char *filename, long *file_size);
295
296 /* misc. */
297 #define UNUSED(x) (void)(x)
298 +#define error_report(x, args...) do { errno = 0; error(x, ##args); } while(0)
299
300 extern void netdata_cleanup_and_exit(int ret) NORETURN;
301 extern void send_statistics(const char *action, const char *action_result, const char *action_data);
web/api/formatters/charts2json.c
+1 -1
@@ -4,7 +4,7 @@
4
5 // generate JSON for the /api/v1/charts API call
6
7 -static inline const char* get_release_channel() {
7 +const char* get_release_channel() {
8 static int use_stable = -1;
9
10 if (use_stable == -1) {
web/api/formatters/charts2json.h
+1
@@ -7,5 +7,6 @@
7
8 extern void charts2json(RRDHOST *host, BUFFER *wb, int skip_volatile, int show_archived);
9 extern void chartcollectors2json(RRDHOST *host, BUFFER *wb);
10 +extern const char* get_release_channel();
11
12 #endif //NETDATA_API_FORMATTER_CHARTS2JSON_H
web/api/tests/valid_urls.c
+5
@@ -7,6 +7,11 @@
7 #include <setjmp.h>
8 #include <cmocka.h>
9 #include <stdbool.h>
10 +RRDHOST *__wrap_sql_create_host_by_uuid(char *hostname)
11 +{
12 + (void) hostname;
13 + return NULL;
14 +}
15
16 void repr(char *result, int result_size, char const *buf, int size)
17 {
web/api/tests/web_api.c
+6
@@ -8,6 +8,12 @@
8 #include <cmocka.h>
9 #include <stdbool.h>
10
11 +RRDHOST *__wrap_sql_create_host_by_uuid(char *hostname)
12 +{
13 + (void) hostname;
14 + return NULL;
15 +}
16 +
17 void repr(char *result, int result_size, char const *buf, int size)
18 {
19 int n;
web/api/web_api_v1.c
+5 -2
@@ -354,12 +354,15 @@ inline int web_client_api_request_v1_charts(RRDHOST *host, struct web_client *w,
354 return HTTP_RESP_OK;
355 }
356
357 -inline int web_client_api_request_v1_archivedcharts(RRDHOST *host, struct web_client *w, char *url) {
357 +inline int web_client_api_request_v1_archivedcharts(RRDHOST *host __maybe_unused, struct web_client *w, char *url) {
358 (void)url;
359
360 buffer_flush(w->response.data);
361 w->response.data->contenttype = CT_APPLICATION_JSON;
362 - charts2json(host, w->response.data, 0, 1);
362 +#ifdef ENABLE_DBENGINE
363 + if (host->rrd_memory_mode == RRD_MEMORY_MODE_DBENGINE)
364 + sql_rrdset2json(host, w->response.data);
365 +#endif
366 return HTTP_RESP_OK;
367 }
368
web/server/web_client.c
+26 -1
@@ -1376,7 +1376,32 @@ static inline int web_client_switch_host(RRDHOST *host, struct web_client *w, ch
1376 host = rrdhost_find_by_hostname(tok, hash);
1377 if(!host) host = rrdhost_find_by_guid(tok, hash);
1378
1379 - if(host) return web_client_process_url(host, w, url);
1379 +#ifdef ENABLE_DBENGINE
1380 + int release_host = 0;
1381 + if (!host) {
1382 + host = sql_create_host_by_uuid(tok);
1383 + if (likely(host)) {
1384 + rrdhost_flag_set(host, RRDHOST_FLAG_ARCHIVED);
1385 + release_host = 1;
1386 + }
1387 + }
1388 + if(host) {
1389 + int rc = web_client_process_url(host, w, url);
1390 + if (release_host) {
1391 + freez(host->hostname);
1392 + freez((char *) host->os);
1393 + freez((char *) host->tags);
1394 + freez((char *) host->timezone);
1395 + freez(host->program_name);
1396 + freez(host->program_version);
1397 + freez(host->registry_hostname);
1398 + freez(host);
1399 + }
1400 + return rc;
1401 + }
1402 +#else
1403 + if (host) return web_client_process_url(host, w, url);
1404 +#endif
1405 }
1406
1407 buffer_flush(w->response.data);