• R/O
  • HTTP
  • SSH
  • HTTPS

提交

标签
No Tags

Frequently used words (click to add to your profile)

javac++androidlinuxc#windowsobjective-ccocoa誰得qtpythonphprubygameguibathyscaphec計画中(planning stage)翻訳omegatframeworktwitterdomtestvb.netdirectxゲームエンジンbtronarduinopreviewer

external/koush/Superuser


Commit MetaInfo

修订版1f0bc59a34d0faf0435b0640706ddfa0e37ee868 (tree)
时间2018-02-02 11:16:18
作者Chih-Wei Huang <cwhuang@linu...>
CommiterChih-Wei Huang

Log Message

Remove unused code

更改概述

  • delete: Superuser/jni/Android.mk
  • delete: Superuser/jni/reboot/reboot.c
  • delete: Superuser/jni/sqlite3/shell.c
  • delete: Superuser/jni/sqlite3/sqlite3.c
  • delete: Superuser/jni/sqlite3/sqlite3.h
  • delete: Superuser/jni/sqlite3/sqlite3ext.h

差异

--- a/Superuser/jni/Android.mk
+++ /dev/null
@@ -1,28 +0,0 @@
1-LOCAL_PATH := $(call my-dir)
2-
3-include $(CLEAR_VARS)
4-
5-LOCAL_MODULE := su
6-LOCAL_FORCE_STATIC_EXECUTABLE := true
7-LOCAL_STATIC_LIBRARIES := sqlite3 libcutils libc
8-LOCAL_C_INCLUDES := $(LOCAL_PATH)/sqlite3
9-LOCAL_SRC_FILES := su/su.c su/activity.c su/db.c su/utils.c su/daemon.c su/pts.c
10-include $(BUILD_EXECUTABLE)
11-
12-
13-include $(CLEAR_VARS)
14-
15-LOCAL_MODULE := reboot
16-LOCAL_LDFLAGS := -llog
17-LOCAL_STATIC_LIBRARIES := sqlite3
18-LOCAL_C_INCLUDES := $(LOCAL_PATH)/sqlite3
19-LOCAL_SRC_FILES := reboot/reboot.c
20-include $(BUILD_EXECUTABLE)
21-
22-
23-include $(CLEAR_VARS)
24-
25-LOCAL_MODULE := sqlite3
26-LOCAL_SRC_FILES := sqlite3/sqlite3.c
27-LOCAL_CFLAGS := -DSQLITE_OMIT_LOAD_EXTENSION
28-include $(BUILD_STATIC_LIBRARY)
--- a/Superuser/jni/reboot/reboot.c
+++ /dev/null
@@ -1,145 +0,0 @@
1-/*
2-** Copyright 2013, Kevin Cernekee <cernekee@gmail.com>
3-**
4-** This was reverse engineered from an HTC "reboot" binary and is an attempt
5-** to remain bug-compatible with the original.
6-**
7-** Licensed under the Apache License, Version 2.0 (the "License");
8-** you may not use this file except in compliance with the License.
9-** You may obtain a copy of the License at
10-**
11-** http://www.apache.org/licenses/LICENSE-2.0
12-**
13-** Unless required by applicable law or agreed to in writing, software
14-** distributed under the License is distributed on an "AS IS" BASIS,
15-** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16-** See the License for the specific language governing permissions and
17-** limitations under the License.
18-*/
19-
20-#include <stdio.h>
21-#include <stdlib.h>
22-#include <unistd.h>
23-
24-#include <sqlite3.h>
25-#include <sys/reboot.h>
26-#include <android/log.h>
27-
28-#define SETTINGS_DB "/data/data/com.android.providers.settings/databases/settings.db"
29-#define SCREEN_LOCK_STATUS "/data/misc/screen_lock_status"
30-
31-int pattern_lock;
32-
33-int sqlcallback(void *private, int n_columns, char **col_values, char **col_names)
34-{
35- pattern_lock = 0;
36-
37- if (n_columns == 0 || !col_values[0])
38- return 0;
39-
40- if (!strcmp(col_values[0], "1"))
41- pattern_lock = 1;
42-
43- __android_log_print(ANDROID_LOG_INFO, NULL,
44- "sqlcallback %s = %s, pattern_locks= %d\n",
45- col_names[0], col_values[0], pattern_lock);
46- return 0;
47-}
48-
49-int checkPatternLock(void)
50-{
51- sqlite3 *pDb = NULL;
52- char *errmsg = NULL;
53-
54- if (sqlite3_open(SETTINGS_DB, &pDb) != 0) {
55- __android_log_print(ANDROID_LOG_ERROR, NULL,
56- "sqlite3_open error");
57- /* BUG? probably shouldn't call sqlite3_close() if open failed */
58- goto out;
59- }
60-
61- if (sqlite3_exec(pDb,
62- "select value from system where name= \"lock_pattern_autolock\"",
63- sqlcallback, "checkPatternLock", &errmsg) != 0) {
64- __android_log_print(ANDROID_LOG_ERROR, NULL,
65- "SQL error: %s\n", errmsg);
66- sqlite3_free(errmsg);
67- goto out;
68- }
69-
70-out:
71- sqlite3_close(pDb);
72- return 0;
73-}
74-
75-int main(int argc, char **argv)
76-{
77- int no_sync = 0, power_off = 0;
78- int ret;
79-
80- opterr = 0;
81- while ((ret = getopt(argc, argv, "np")) != -1) {
82- switch (ret) {
83- case 'n':
84- no_sync = 1;
85- break;
86- case 'p':
87- power_off = 1;
88- break;
89- case '?':
90- fprintf(stderr, "usage: %s [-n] [-p] [rebootcommand]\n",
91- argv[0]);
92- exit(1);
93- break;
94- }
95- }
96-
97- if (argc > (optind + 1)) {
98- fprintf(stderr, "%s: too many arguments\n", argv[0]);
99- exit(1);
100- }
101-
102- /* BUG: this should use optind */
103- if (argc > 1 && !strcmp(argv[1], "oem-78")) {
104- /* HTC RUU mode: "reboot oem-78" */
105-
106- FILE *f;
107- char buf[5];
108-
109- checkPatternLock();
110- f = fopen(SCREEN_LOCK_STATUS, "r");
111- if (!f) {
112- fputs("5\n", stderr);
113- exit(0);
114- }
115- fgets(buf, 5, f);
116- if (atoi(buf) == 1) {
117- if (pattern_lock != 0) {
118- fputs("1\n", stderr);
119- exit(0);
120- }
121- }
122- fputs("0\n", stderr);
123- }
124-
125- if (!no_sync)
126- sync();
127-
128- if (power_off) {
129- ret = __reboot(LINUX_REBOOT_MAGIC1, LINUX_REBOOT_MAGIC2,
130- LINUX_REBOOT_CMD_POWER_OFF, 0);
131- } else if (optind >= argc) {
132- ret = reboot(LINUX_REBOOT_CMD_RESTART);
133- } else {
134- ret = __reboot(LINUX_REBOOT_MAGIC1, LINUX_REBOOT_MAGIC2,
135- LINUX_REBOOT_CMD_RESTART2, argv[optind]);
136- }
137-
138- if (ret < 0) {
139- perror("reboot");
140- exit(1);
141- } else {
142- fputs("reboot returned\n", stderr);
143- exit(0);
144- }
145-}
--- a/Superuser/jni/sqlite3/shell.c
+++ /dev/null
@@ -1,3163 +0,0 @@
1-/*
2-** 2001 September 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 file contains code to implement the "sqlite" command line
13-** utility for accessing SQLite databases.
14-*/
15-#if (defined(_WIN32) || defined(WIN32)) && !defined(_CRT_SECURE_NO_WARNINGS)
16-/* This needs to come before any includes for MSVC compiler */
17-#define _CRT_SECURE_NO_WARNINGS
18-#endif
19-
20-/*
21-** Enable large-file support for fopen() and friends on unix.
22-*/
23-#ifndef SQLITE_DISABLE_LFS
24-# define _LARGE_FILE 1
25-# ifndef _FILE_OFFSET_BITS
26-# define _FILE_OFFSET_BITS 64
27-# endif
28-# define _LARGEFILE_SOURCE 1
29-#endif
30-
31-#include <stdlib.h>
32-#include <string.h>
33-#include <stdio.h>
34-#include <assert.h>
35-#include "sqlite3.h"
36-#include <ctype.h>
37-#include <stdarg.h>
38-
39-#if !defined(_WIN32) && !defined(WIN32)
40-# include <signal.h>
41-# if !defined(__RTP__) && !defined(_WRS_KERNEL)
42-# include <pwd.h>
43-# endif
44-# include <unistd.h>
45-# include <sys/types.h>
46-#endif
47-
48-#ifdef HAVE_EDITLINE
49-# include <editline/editline.h>
50-#endif
51-#if defined(HAVE_READLINE) && HAVE_READLINE==1
52-# include <readline/readline.h>
53-# include <readline/history.h>
54-#endif
55-#if !defined(HAVE_EDITLINE) && (!defined(HAVE_READLINE) || HAVE_READLINE!=1)
56-# define readline(p) local_getline(p,stdin,0)
57-# define add_history(X)
58-# define read_history(X)
59-# define write_history(X)
60-# define stifle_history(X)
61-#endif
62-
63-#if defined(_WIN32) || defined(WIN32)
64-# include <io.h>
65-#define isatty(h) _isatty(h)
66-#define access(f,m) _access((f),(m))
67-#undef popen
68-#define popen(a,b) _popen((a),(b))
69-#undef pclose
70-#define pclose(x) _pclose(x)
71-#else
72-/* Make sure isatty() has a prototype.
73-*/
74-extern int isatty(int);
75-#endif
76-
77-#if defined(_WIN32_WCE)
78-/* Windows CE (arm-wince-mingw32ce-gcc) does not provide isatty()
79- * thus we always assume that we have a console. That can be
80- * overridden with the -batch command line option.
81- */
82-#define isatty(x) 1
83-#endif
84-
85-/* True if the timer is enabled */
86-static int enableTimer = 0;
87-
88-/* ctype macros that work with signed characters */
89-#define IsSpace(X) isspace((unsigned char)X)
90-#define IsDigit(X) isdigit((unsigned char)X)
91-#define ToLower(X) (char)tolower((unsigned char)X)
92-
93-#if !defined(_WIN32) && !defined(WIN32) && !defined(_WRS_KERNEL)
94-#include <sys/time.h>
95-#include <sys/resource.h>
96-
97-/* Saved resource information for the beginning of an operation */
98-static struct rusage sBegin;
99-
100-/*
101-** Begin timing an operation
102-*/
103-static void beginTimer(void){
104- if( enableTimer ){
105- getrusage(RUSAGE_SELF, &sBegin);
106- }
107-}
108-
109-/* Return the difference of two time_structs in seconds */
110-static double timeDiff(struct timeval *pStart, struct timeval *pEnd){
111- return (pEnd->tv_usec - pStart->tv_usec)*0.000001 +
112- (double)(pEnd->tv_sec - pStart->tv_sec);
113-}
114-
115-/*
116-** Print the timing results.
117-*/
118-static void endTimer(void){
119- if( enableTimer ){
120- struct rusage sEnd;
121- getrusage(RUSAGE_SELF, &sEnd);
122- printf("CPU Time: user %f sys %f\n",
123- timeDiff(&sBegin.ru_utime, &sEnd.ru_utime),
124- timeDiff(&sBegin.ru_stime, &sEnd.ru_stime));
125- }
126-}
127-
128-#define BEGIN_TIMER beginTimer()
129-#define END_TIMER endTimer()
130-#define HAS_TIMER 1
131-
132-#elif (defined(_WIN32) || defined(WIN32))
133-
134-#include <windows.h>
135-
136-/* Saved resource information for the beginning of an operation */
137-static HANDLE hProcess;
138-static FILETIME ftKernelBegin;
139-static FILETIME ftUserBegin;
140-typedef BOOL (WINAPI *GETPROCTIMES)(HANDLE, LPFILETIME, LPFILETIME, LPFILETIME, LPFILETIME);
141-static GETPROCTIMES getProcessTimesAddr = NULL;
142-
143-/*
144-** Check to see if we have timer support. Return 1 if necessary
145-** support found (or found previously).
146-*/
147-static int hasTimer(void){
148- if( getProcessTimesAddr ){
149- return 1;
150- } else {
151- /* GetProcessTimes() isn't supported in WIN95 and some other Windows versions.
152- ** See if the version we are running on has it, and if it does, save off
153- ** a pointer to it and the current process handle.
154- */
155- hProcess = GetCurrentProcess();
156- if( hProcess ){
157- HINSTANCE hinstLib = LoadLibrary(TEXT("Kernel32.dll"));
158- if( NULL != hinstLib ){
159- getProcessTimesAddr = (GETPROCTIMES) GetProcAddress(hinstLib, "GetProcessTimes");
160- if( NULL != getProcessTimesAddr ){
161- return 1;
162- }
163- FreeLibrary(hinstLib);
164- }
165- }
166- }
167- return 0;
168-}
169-
170-/*
171-** Begin timing an operation
172-*/
173-static void beginTimer(void){
174- if( enableTimer && getProcessTimesAddr ){
175- FILETIME ftCreation, ftExit;
176- getProcessTimesAddr(hProcess, &ftCreation, &ftExit, &ftKernelBegin, &ftUserBegin);
177- }
178-}
179-
180-/* Return the difference of two FILETIME structs in seconds */
181-static double timeDiff(FILETIME *pStart, FILETIME *pEnd){
182- sqlite_int64 i64Start = *((sqlite_int64 *) pStart);
183- sqlite_int64 i64End = *((sqlite_int64 *) pEnd);
184- return (double) ((i64End - i64Start) / 10000000.0);
185-}
186-
187-/*
188-** Print the timing results.
189-*/
190-static void endTimer(void){
191- if( enableTimer && getProcessTimesAddr){
192- FILETIME ftCreation, ftExit, ftKernelEnd, ftUserEnd;
193- getProcessTimesAddr(hProcess, &ftCreation, &ftExit, &ftKernelEnd, &ftUserEnd);
194- printf("CPU Time: user %f sys %f\n",
195- timeDiff(&ftUserBegin, &ftUserEnd),
196- timeDiff(&ftKernelBegin, &ftKernelEnd));
197- }
198-}
199-
200-#define BEGIN_TIMER beginTimer()
201-#define END_TIMER endTimer()
202-#define HAS_TIMER hasTimer()
203-
204-#else
205-#define BEGIN_TIMER
206-#define END_TIMER
207-#define HAS_TIMER 0
208-#endif
209-
210-/*
211-** Used to prevent warnings about unused parameters
212-*/
213-#define UNUSED_PARAMETER(x) (void)(x)
214-
215-/*
216-** If the following flag is set, then command execution stops
217-** at an error if we are not interactive.
218-*/
219-static int bail_on_error = 0;
220-
221-/*
222-** Threat stdin as an interactive input if the following variable
223-** is true. Otherwise, assume stdin is connected to a file or pipe.
224-*/
225-static int stdin_is_interactive = 1;
226-
227-/*
228-** The following is the open SQLite database. We make a pointer
229-** to this database a static variable so that it can be accessed
230-** by the SIGINT handler to interrupt database processing.
231-*/
232-static sqlite3 *db = 0;
233-
234-/*
235-** True if an interrupt (Control-C) has been received.
236-*/
237-static volatile int seenInterrupt = 0;
238-
239-/*
240-** This is the name of our program. It is set in main(), used
241-** in a number of other places, mostly for error messages.
242-*/
243-static char *Argv0;
244-
245-/*
246-** Prompt strings. Initialized in main. Settable with
247-** .prompt main continue
248-*/
249-static char mainPrompt[20]; /* First line prompt. default: "sqlite> "*/
250-static char continuePrompt[20]; /* Continuation prompt. default: " ...> " */
251-
252-/*
253-** Write I/O traces to the following stream.
254-*/
255-#ifdef SQLITE_ENABLE_IOTRACE
256-static FILE *iotrace = 0;
257-#endif
258-
259-/*
260-** This routine works like printf in that its first argument is a
261-** format string and subsequent arguments are values to be substituted
262-** in place of % fields. The result of formatting this string
263-** is written to iotrace.
264-*/
265-#ifdef SQLITE_ENABLE_IOTRACE
266-static void iotracePrintf(const char *zFormat, ...){
267- va_list ap;
268- char *z;
269- if( iotrace==0 ) return;
270- va_start(ap, zFormat);
271- z = sqlite3_vmprintf(zFormat, ap);
272- va_end(ap);
273- fprintf(iotrace, "%s", z);
274- sqlite3_free(z);
275-}
276-#endif
277-
278-
279-/*
280-** Determines if a string is a number of not.
281-*/
282-static int isNumber(const char *z, int *realnum){
283- if( *z=='-' || *z=='+' ) z++;
284- if( !IsDigit(*z) ){
285- return 0;
286- }
287- z++;
288- if( realnum ) *realnum = 0;
289- while( IsDigit(*z) ){ z++; }
290- if( *z=='.' ){
291- z++;
292- if( !IsDigit(*z) ) return 0;
293- while( IsDigit(*z) ){ z++; }
294- if( realnum ) *realnum = 1;
295- }
296- if( *z=='e' || *z=='E' ){
297- z++;
298- if( *z=='+' || *z=='-' ) z++;
299- if( !IsDigit(*z) ) return 0;
300- while( IsDigit(*z) ){ z++; }
301- if( realnum ) *realnum = 1;
302- }
303- return *z==0;
304-}
305-
306-/*
307-** A global char* and an SQL function to access its current value
308-** from within an SQL statement. This program used to use the
309-** sqlite_exec_printf() API to substitue a string into an SQL statement.
310-** The correct way to do this with sqlite3 is to use the bind API, but
311-** since the shell is built around the callback paradigm it would be a lot
312-** of work. Instead just use this hack, which is quite harmless.
313-*/
314-static const char *zShellStatic = 0;
315-static void shellstaticFunc(
316- sqlite3_context *context,
317- int argc,
318- sqlite3_value **argv
319-){
320- assert( 0==argc );
321- assert( zShellStatic );
322- UNUSED_PARAMETER(argc);
323- UNUSED_PARAMETER(argv);
324- sqlite3_result_text(context, zShellStatic, -1, SQLITE_STATIC);
325-}
326-
327-
328-/*
329-** This routine reads a line of text from FILE in, stores
330-** the text in memory obtained from malloc() and returns a pointer
331-** to the text. NULL is returned at end of file, or if malloc()
332-** fails.
333-**
334-** The interface is like "readline" but no command-line editing
335-** is done.
336-*/
337-static char *local_getline(char *zPrompt, FILE *in, int csvFlag){
338- char *zLine;
339- int nLine;
340- int n;
341- int inQuote = 0;
342-
343- if( zPrompt && *zPrompt ){
344- printf("%s",zPrompt);
345- fflush(stdout);
346- }
347- nLine = 100;
348- zLine = malloc( nLine );
349- if( zLine==0 ) return 0;
350- n = 0;
351- while( 1 ){
352- if( n+100>nLine ){
353- nLine = nLine*2 + 100;
354- zLine = realloc(zLine, nLine);
355- if( zLine==0 ) return 0;
356- }
357- if( fgets(&zLine[n], nLine - n, in)==0 ){
358- if( n==0 ){
359- free(zLine);
360- return 0;
361- }
362- zLine[n] = 0;
363- break;
364- }
365- while( zLine[n] ){
366- if( zLine[n]=='"' ) inQuote = !inQuote;
367- n++;
368- }
369- if( n>0 && zLine[n-1]=='\n' && (!inQuote || !csvFlag) ){
370- n--;
371- if( n>0 && zLine[n-1]=='\r' ) n--;
372- zLine[n] = 0;
373- break;
374- }
375- }
376- zLine = realloc( zLine, n+1 );
377- return zLine;
378-}
379-
380-/*
381-** Retrieve a single line of input text.
382-**
383-** zPrior is a string of prior text retrieved. If not the empty
384-** string, then issue a continuation prompt.
385-*/
386-static char *one_input_line(const char *zPrior, FILE *in){
387- char *zPrompt;
388- char *zResult;
389- if( in!=0 ){
390- return local_getline(0, in, 0);
391- }
392- if( zPrior && zPrior[0] ){
393- zPrompt = continuePrompt;
394- }else{
395- zPrompt = mainPrompt;
396- }
397- zResult = readline(zPrompt);
398-#if defined(HAVE_READLINE) && HAVE_READLINE==1
399- if( zResult && *zResult ) add_history(zResult);
400-#endif
401- return zResult;
402-}
403-
404-struct previous_mode_data {
405- int valid; /* Is there legit data in here? */
406- int mode;
407- int showHeader;
408- int colWidth[100];
409-};
410-
411-/*
412-** An pointer to an instance of this structure is passed from
413-** the main program to the callback. This is used to communicate
414-** state and mode information.
415-*/
416-struct callback_data {
417- sqlite3 *db; /* The database */
418- int echoOn; /* True to echo input commands */
419- int statsOn; /* True to display memory stats before each finalize */
420- int cnt; /* Number of records displayed so far */
421- FILE *out; /* Write results here */
422- FILE *traceOut; /* Output for sqlite3_trace() */
423- int nErr; /* Number of errors seen */
424- int mode; /* An output mode setting */
425- int writableSchema; /* True if PRAGMA writable_schema=ON */
426- int showHeader; /* True to show column names in List or Column mode */
427- char *zDestTable; /* Name of destination table when MODE_Insert */
428- char separator[20]; /* Separator character for MODE_List */
429- int colWidth[100]; /* Requested width of each column when in column mode*/
430- int actualWidth[100]; /* Actual width of each column */
431- char nullvalue[20]; /* The text to print when a NULL comes back from
432- ** the database */
433- struct previous_mode_data explainPrev;
434- /* Holds the mode information just before
435- ** .explain ON */
436- char outfile[FILENAME_MAX]; /* Filename for *out */
437- const char *zDbFilename; /* name of the database file */
438- const char *zVfs; /* Name of VFS to use */
439- sqlite3_stmt *pStmt; /* Current statement if any. */
440- FILE *pLog; /* Write log output here */
441-};
442-
443-/*
444-** These are the allowed modes.
445-*/
446-#define MODE_Line 0 /* One column per line. Blank line between records */
447-#define MODE_Column 1 /* One record per line in neat columns */
448-#define MODE_List 2 /* One record per line with a separator */
449-#define MODE_Semi 3 /* Same as MODE_List but append ";" to each line */
450-#define MODE_Html 4 /* Generate an XHTML table */
451-#define MODE_Insert 5 /* Generate SQL "insert" statements */
452-#define MODE_Tcl 6 /* Generate ANSI-C or TCL quoted elements */
453-#define MODE_Csv 7 /* Quote strings, numbers are plain */
454-#define MODE_Explain 8 /* Like MODE_Column, but do not truncate data */
455-
456-static const char *modeDescr[] = {
457- "line",
458- "column",
459- "list",
460- "semi",
461- "html",
462- "insert",
463- "tcl",
464- "csv",
465- "explain",
466-};
467-
468-/*
469-** Number of elements in an array
470-*/
471-#define ArraySize(X) (int)(sizeof(X)/sizeof(X[0]))
472-
473-/*
474-** Compute a string length that is limited to what can be stored in
475-** lower 30 bits of a 32-bit signed integer.
476-*/
477-static int strlen30(const char *z){
478- const char *z2 = z;
479- while( *z2 ){ z2++; }
480- return 0x3fffffff & (int)(z2 - z);
481-}
482-
483-/*
484-** A callback for the sqlite3_log() interface.
485-*/
486-static void shellLog(void *pArg, int iErrCode, const char *zMsg){
487- struct callback_data *p = (struct callback_data*)pArg;
488- if( p->pLog==0 ) return;
489- fprintf(p->pLog, "(%d) %s\n", iErrCode, zMsg);
490- fflush(p->pLog);
491-}
492-
493-/*
494-** Output the given string as a hex-encoded blob (eg. X'1234' )
495-*/
496-static void output_hex_blob(FILE *out, const void *pBlob, int nBlob){
497- int i;
498- char *zBlob = (char *)pBlob;
499- fprintf(out,"X'");
500- for(i=0; i<nBlob; i++){ fprintf(out,"%02x",zBlob[i]&0xff); }
501- fprintf(out,"'");
502-}
503-
504-/*
505-** Output the given string as a quoted string using SQL quoting conventions.
506-*/
507-static void output_quoted_string(FILE *out, const char *z){
508- int i;
509- int nSingle = 0;
510- for(i=0; z[i]; i++){
511- if( z[i]=='\'' ) nSingle++;
512- }
513- if( nSingle==0 ){
514- fprintf(out,"'%s'",z);
515- }else{
516- fprintf(out,"'");
517- while( *z ){
518- for(i=0; z[i] && z[i]!='\''; i++){}
519- if( i==0 ){
520- fprintf(out,"''");
521- z++;
522- }else if( z[i]=='\'' ){
523- fprintf(out,"%.*s''",i,z);
524- z += i+1;
525- }else{
526- fprintf(out,"%s",z);
527- break;
528- }
529- }
530- fprintf(out,"'");
531- }
532-}
533-
534-/*
535-** Output the given string as a quoted according to C or TCL quoting rules.
536-*/
537-static void output_c_string(FILE *out, const char *z){
538- unsigned int c;
539- fputc('"', out);
540- while( (c = *(z++))!=0 ){
541- if( c=='\\' ){
542- fputc(c, out);
543- fputc(c, out);
544- }else if( c=='"' ){
545- fputc('\\', out);
546- fputc('"', out);
547- }else if( c=='\t' ){
548- fputc('\\', out);
549- fputc('t', out);
550- }else if( c=='\n' ){
551- fputc('\\', out);
552- fputc('n', out);
553- }else if( c=='\r' ){
554- fputc('\\', out);
555- fputc('r', out);
556- }else if( !isprint(c) ){
557- fprintf(out, "\\%03o", c&0xff);
558- }else{
559- fputc(c, out);
560- }
561- }
562- fputc('"', out);
563-}
564-
565-/*
566-** Output the given string with characters that are special to
567-** HTML escaped.
568-*/
569-static void output_html_string(FILE *out, const char *z){
570- int i;
571- while( *z ){
572- for(i=0; z[i]
573- && z[i]!='<'
574- && z[i]!='&'
575- && z[i]!='>'
576- && z[i]!='\"'
577- && z[i]!='\'';
578- i++){}
579- if( i>0 ){
580- fprintf(out,"%.*s",i,z);
581- }
582- if( z[i]=='<' ){
583- fprintf(out,"&lt;");
584- }else if( z[i]=='&' ){
585- fprintf(out,"&amp;");
586- }else if( z[i]=='>' ){
587- fprintf(out,"&gt;");
588- }else if( z[i]=='\"' ){
589- fprintf(out,"&quot;");
590- }else if( z[i]=='\'' ){
591- fprintf(out,"&#39;");
592- }else{
593- break;
594- }
595- z += i + 1;
596- }
597-}
598-
599-/*
600-** If a field contains any character identified by a 1 in the following
601-** array, then the string must be quoted for CSV.
602-*/
603-static const char needCsvQuote[] = {
604- 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
605- 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
606- 1, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0,
607- 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
608- 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
609- 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
610- 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
611- 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1,
612- 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
613- 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
614- 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
615- 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
616- 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
617- 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
618- 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
619- 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
620-};
621-
622-/*
623-** Output a single term of CSV. Actually, p->separator is used for
624-** the separator, which may or may not be a comma. p->nullvalue is
625-** the null value. Strings are quoted if necessary.
626-*/
627-static void output_csv(struct callback_data *p, const char *z, int bSep){
628- FILE *out = p->out;
629- if( z==0 ){
630- fprintf(out,"%s",p->nullvalue);
631- }else{
632- int i;
633- int nSep = strlen30(p->separator);
634- for(i=0; z[i]; i++){
635- if( needCsvQuote[((unsigned char*)z)[i]]
636- || (z[i]==p->separator[0] &&
637- (nSep==1 || memcmp(z, p->separator, nSep)==0)) ){
638- i = 0;
639- break;
640- }
641- }
642- if( i==0 ){
643- putc('"', out);
644- for(i=0; z[i]; i++){
645- if( z[i]=='"' ) putc('"', out);
646- putc(z[i], out);
647- }
648- putc('"', out);
649- }else{
650- fprintf(out, "%s", z);
651- }
652- }
653- if( bSep ){
654- fprintf(p->out, "%s", p->separator);
655- }
656-}
657-
658-#ifdef SIGINT
659-/*
660-** This routine runs when the user presses Ctrl-C
661-*/
662-static void interrupt_handler(int NotUsed){
663- UNUSED_PARAMETER(NotUsed);
664- seenInterrupt = 1;
665- if( db ) sqlite3_interrupt(db);
666-}
667-#endif
668-
669-/*
670-** This is the callback routine that the shell
671-** invokes for each row of a query result.
672-*/
673-static int shell_callback(void *pArg, int nArg, char **azArg, char **azCol, int *aiType){
674- int i;
675- struct callback_data *p = (struct callback_data*)pArg;
676-
677- switch( p->mode ){
678- case MODE_Line: {
679- int w = 5;
680- if( azArg==0 ) break;
681- for(i=0; i<nArg; i++){
682- int len = strlen30(azCol[i] ? azCol[i] : "");
683- if( len>w ) w = len;
684- }
685- if( p->cnt++>0 ) fprintf(p->out,"\n");
686- for(i=0; i<nArg; i++){
687- fprintf(p->out,"%*s = %s\n", w, azCol[i],
688- azArg[i] ? azArg[i] : p->nullvalue);
689- }
690- break;
691- }
692- case MODE_Explain:
693- case MODE_Column: {
694- if( p->cnt++==0 ){
695- for(i=0; i<nArg; i++){
696- int w, n;
697- if( i<ArraySize(p->colWidth) ){
698- w = p->colWidth[i];
699- }else{
700- w = 0;
701- }
702- if( w==0 ){
703- w = strlen30(azCol[i] ? azCol[i] : "");
704- if( w<10 ) w = 10;
705- n = strlen30(azArg && azArg[i] ? azArg[i] : p->nullvalue);
706- if( w<n ) w = n;
707- }
708- if( i<ArraySize(p->actualWidth) ){
709- p->actualWidth[i] = w;
710- }
711- if( p->showHeader ){
712- if( w<0 ){
713- fprintf(p->out,"%*.*s%s",-w,-w,azCol[i], i==nArg-1 ? "\n": " ");
714- }else{
715- fprintf(p->out,"%-*.*s%s",w,w,azCol[i], i==nArg-1 ? "\n": " ");
716- }
717- }
718- }
719- if( p->showHeader ){
720- for(i=0; i<nArg; i++){
721- int w;
722- if( i<ArraySize(p->actualWidth) ){
723- w = p->actualWidth[i];
724- if( w<0 ) w = -w;
725- }else{
726- w = 10;
727- }
728- fprintf(p->out,"%-*.*s%s",w,w,"-----------------------------------"
729- "----------------------------------------------------------",
730- i==nArg-1 ? "\n": " ");
731- }
732- }
733- }
734- if( azArg==0 ) break;
735- for(i=0; i<nArg; i++){
736- int w;
737- if( i<ArraySize(p->actualWidth) ){
738- w = p->actualWidth[i];
739- }else{
740- w = 10;
741- }
742- if( p->mode==MODE_Explain && azArg[i] &&
743- strlen30(azArg[i])>w ){
744- w = strlen30(azArg[i]);
745- }
746- if( w<0 ){
747- fprintf(p->out,"%*.*s%s",-w,-w,
748- azArg[i] ? azArg[i] : p->nullvalue, i==nArg-1 ? "\n": " ");
749- }else{
750- fprintf(p->out,"%-*.*s%s",w,w,
751- azArg[i] ? azArg[i] : p->nullvalue, i==nArg-1 ? "\n": " ");
752- }
753- }
754- break;
755- }
756- case MODE_Semi:
757- case MODE_List: {
758- if( p->cnt++==0 && p->showHeader ){
759- for(i=0; i<nArg; i++){
760- fprintf(p->out,"%s%s",azCol[i], i==nArg-1 ? "\n" : p->separator);
761- }
762- }
763- if( azArg==0 ) break;
764- for(i=0; i<nArg; i++){
765- char *z = azArg[i];
766- if( z==0 ) z = p->nullvalue;
767- fprintf(p->out, "%s", z);
768- if( i<nArg-1 ){
769- fprintf(p->out, "%s", p->separator);
770- }else if( p->mode==MODE_Semi ){
771- fprintf(p->out, ";\n");
772- }else{
773- fprintf(p->out, "\n");
774- }
775- }
776- break;
777- }
778- case MODE_Html: {
779- if( p->cnt++==0 && p->showHeader ){
780- fprintf(p->out,"<TR>");
781- for(i=0; i<nArg; i++){
782- fprintf(p->out,"<TH>");
783- output_html_string(p->out, azCol[i]);
784- fprintf(p->out,"</TH>\n");
785- }
786- fprintf(p->out,"</TR>\n");
787- }
788- if( azArg==0 ) break;
789- fprintf(p->out,"<TR>");
790- for(i=0; i<nArg; i++){
791- fprintf(p->out,"<TD>");
792- output_html_string(p->out, azArg[i] ? azArg[i] : p->nullvalue);
793- fprintf(p->out,"</TD>\n");
794- }
795- fprintf(p->out,"</TR>\n");
796- break;
797- }
798- case MODE_Tcl: {
799- if( p->cnt++==0 && p->showHeader ){
800- for(i=0; i<nArg; i++){
801- output_c_string(p->out,azCol[i] ? azCol[i] : "");
802- if(i<nArg-1) fprintf(p->out, "%s", p->separator);
803- }
804- fprintf(p->out,"\n");
805- }
806- if( azArg==0 ) break;
807- for(i=0; i<nArg; i++){
808- output_c_string(p->out, azArg[i] ? azArg[i] : p->nullvalue);
809- if(i<nArg-1) fprintf(p->out, "%s", p->separator);
810- }
811- fprintf(p->out,"\n");
812- break;
813- }
814- case MODE_Csv: {
815- if( p->cnt++==0 && p->showHeader ){
816- for(i=0; i<nArg; i++){
817- output_csv(p, azCol[i] ? azCol[i] : "", i<nArg-1);
818- }
819- fprintf(p->out,"\n");
820- }
821- if( azArg==0 ) break;
822- for(i=0; i<nArg; i++){
823- output_csv(p, azArg[i], i<nArg-1);
824- }
825- fprintf(p->out,"\n");
826- break;
827- }
828- case MODE_Insert: {
829- p->cnt++;
830- if( azArg==0 ) break;
831- fprintf(p->out,"INSERT INTO %s VALUES(",p->zDestTable);
832- for(i=0; i<nArg; i++){
833- char *zSep = i>0 ? ",": "";
834- if( (azArg[i]==0) || (aiType && aiType[i]==SQLITE_NULL) ){
835- fprintf(p->out,"%sNULL",zSep);
836- }else if( aiType && aiType[i]==SQLITE_TEXT ){
837- if( zSep[0] ) fprintf(p->out,"%s",zSep);
838- output_quoted_string(p->out, azArg[i]);
839- }else if( aiType && (aiType[i]==SQLITE_INTEGER || aiType[i]==SQLITE_FLOAT) ){
840- fprintf(p->out,"%s%s",zSep, azArg[i]);
841- }else if( aiType && aiType[i]==SQLITE_BLOB && p->pStmt ){
842- const void *pBlob = sqlite3_column_blob(p->pStmt, i);
843- int nBlob = sqlite3_column_bytes(p->pStmt, i);
844- if( zSep[0] ) fprintf(p->out,"%s",zSep);
845- output_hex_blob(p->out, pBlob, nBlob);
846- }else if( isNumber(azArg[i], 0) ){
847- fprintf(p->out,"%s%s",zSep, azArg[i]);
848- }else{
849- if( zSep[0] ) fprintf(p->out,"%s",zSep);
850- output_quoted_string(p->out, azArg[i]);
851- }
852- }
853- fprintf(p->out,");\n");
854- break;
855- }
856- }
857- return 0;
858-}
859-
860-/*
861-** This is the callback routine that the SQLite library
862-** invokes for each row of a query result.
863-*/
864-static int callback(void *pArg, int nArg, char **azArg, char **azCol){
865- /* since we don't have type info, call the shell_callback with a NULL value */
866- return shell_callback(pArg, nArg, azArg, azCol, NULL);
867-}
868-
869-/*
870-** Set the destination table field of the callback_data structure to
871-** the name of the table given. Escape any quote characters in the
872-** table name.
873-*/
874-static void set_table_name(struct callback_data *p, const char *zName){
875- int i, n;
876- int needQuote;
877- char *z;
878-
879- if( p->zDestTable ){
880- free(p->zDestTable);
881- p->zDestTable = 0;
882- }
883- if( zName==0 ) return;
884- needQuote = !isalpha((unsigned char)*zName) && *zName!='_';
885- for(i=n=0; zName[i]; i++, n++){
886- if( !isalnum((unsigned char)zName[i]) && zName[i]!='_' ){
887- needQuote = 1;
888- if( zName[i]=='\'' ) n++;
889- }
890- }
891- if( needQuote ) n += 2;
892- z = p->zDestTable = malloc( n+1 );
893- if( z==0 ){
894- fprintf(stderr,"Error: out of memory\n");
895- exit(1);
896- }
897- n = 0;
898- if( needQuote ) z[n++] = '\'';
899- for(i=0; zName[i]; i++){
900- z[n++] = zName[i];
901- if( zName[i]=='\'' ) z[n++] = '\'';
902- }
903- if( needQuote ) z[n++] = '\'';
904- z[n] = 0;
905-}
906-
907-/* zIn is either a pointer to a NULL-terminated string in memory obtained
908-** from malloc(), or a NULL pointer. The string pointed to by zAppend is
909-** added to zIn, and the result returned in memory obtained from malloc().
910-** zIn, if it was not NULL, is freed.
911-**
912-** If the third argument, quote, is not '\0', then it is used as a
913-** quote character for zAppend.
914-*/
915-static char *appendText(char *zIn, char const *zAppend, char quote){
916- int len;
917- int i;
918- int nAppend = strlen30(zAppend);
919- int nIn = (zIn?strlen30(zIn):0);
920-
921- len = nAppend+nIn+1;
922- if( quote ){
923- len += 2;
924- for(i=0; i<nAppend; i++){
925- if( zAppend[i]==quote ) len++;
926- }
927- }
928-
929- zIn = (char *)realloc(zIn, len);
930- if( !zIn ){
931- return 0;
932- }
933-
934- if( quote ){
935- char *zCsr = &zIn[nIn];
936- *zCsr++ = quote;
937- for(i=0; i<nAppend; i++){
938- *zCsr++ = zAppend[i];
939- if( zAppend[i]==quote ) *zCsr++ = quote;
940- }
941- *zCsr++ = quote;
942- *zCsr++ = '\0';
943- assert( (zCsr-zIn)==len );
944- }else{
945- memcpy(&zIn[nIn], zAppend, nAppend);
946- zIn[len-1] = '\0';
947- }
948-
949- return zIn;
950-}
951-
952-
953-/*
954-** Execute a query statement that will generate SQL output. Print
955-** the result columns, comma-separated, on a line and then add a
956-** semicolon terminator to the end of that line.
957-**
958-** If the number of columns is 1 and that column contains text "--"
959-** then write the semicolon on a separate line. That way, if a
960-** "--" comment occurs at the end of the statement, the comment
961-** won't consume the semicolon terminator.
962-*/
963-static int run_table_dump_query(
964- struct callback_data *p, /* Query context */
965- const char *zSelect, /* SELECT statement to extract content */
966- const char *zFirstRow /* Print before first row, if not NULL */
967-){
968- sqlite3_stmt *pSelect;
969- int rc;
970- int nResult;
971- int i;
972- const char *z;
973- rc = sqlite3_prepare(p->db, zSelect, -1, &pSelect, 0);
974- if( rc!=SQLITE_OK || !pSelect ){
975- fprintf(p->out, "/**** ERROR: (%d) %s *****/\n", rc, sqlite3_errmsg(p->db));
976- p->nErr++;
977- return rc;
978- }
979- rc = sqlite3_step(pSelect);
980- nResult = sqlite3_column_count(pSelect);
981- while( rc==SQLITE_ROW ){
982- if( zFirstRow ){
983- fprintf(p->out, "%s", zFirstRow);
984- zFirstRow = 0;
985- }
986- z = (const char*)sqlite3_column_text(pSelect, 0);
987- fprintf(p->out, "%s", z);
988- for(i=1; i<nResult; i++){
989- fprintf(p->out, ",%s", sqlite3_column_text(pSelect, i));
990- }
991- if( z==0 ) z = "";
992- while( z[0] && (z[0]!='-' || z[1]!='-') ) z++;
993- if( z[0] ){
994- fprintf(p->out, "\n;\n");
995- }else{
996- fprintf(p->out, ";\n");
997- }
998- rc = sqlite3_step(pSelect);
999- }
1000- rc = sqlite3_finalize(pSelect);
1001- if( rc!=SQLITE_OK ){
1002- fprintf(p->out, "/**** ERROR: (%d) %s *****/\n", rc, sqlite3_errmsg(p->db));
1003- p->nErr++;
1004- }
1005- return rc;
1006-}
1007-
1008-/*
1009-** Allocate space and save off current error string.
1010-*/
1011-static char *save_err_msg(
1012- sqlite3 *db /* Database to query */
1013-){
1014- int nErrMsg = 1+strlen30(sqlite3_errmsg(db));
1015- char *zErrMsg = sqlite3_malloc(nErrMsg);
1016- if( zErrMsg ){
1017- memcpy(zErrMsg, sqlite3_errmsg(db), nErrMsg);
1018- }
1019- return zErrMsg;
1020-}
1021-
1022-/*
1023-** Display memory stats.
1024-*/
1025-static int display_stats(
1026- sqlite3 *db, /* Database to query */
1027- struct callback_data *pArg, /* Pointer to struct callback_data */
1028- int bReset /* True to reset the stats */
1029-){
1030- int iCur;
1031- int iHiwtr;
1032-
1033- if( pArg && pArg->out ){
1034-
1035- iHiwtr = iCur = -1;
1036- sqlite3_status(SQLITE_STATUS_MEMORY_USED, &iCur, &iHiwtr, bReset);
1037- fprintf(pArg->out, "Memory Used: %d (max %d) bytes\n", iCur, iHiwtr);
1038- iHiwtr = iCur = -1;
1039- sqlite3_status(SQLITE_STATUS_MALLOC_COUNT, &iCur, &iHiwtr, bReset);
1040- fprintf(pArg->out, "Number of Outstanding Allocations: %d (max %d)\n", iCur, iHiwtr);
1041-/*
1042-** Not currently used by the CLI.
1043-** iHiwtr = iCur = -1;
1044-** sqlite3_status(SQLITE_STATUS_PAGECACHE_USED, &iCur, &iHiwtr, bReset);
1045-** fprintf(pArg->out, "Number of Pcache Pages Used: %d (max %d) pages\n", iCur, iHiwtr);
1046-*/
1047- iHiwtr = iCur = -1;
1048- sqlite3_status(SQLITE_STATUS_PAGECACHE_OVERFLOW, &iCur, &iHiwtr, bReset);
1049- fprintf(pArg->out, "Number of Pcache Overflow Bytes: %d (max %d) bytes\n", iCur, iHiwtr);
1050-/*
1051-** Not currently used by the CLI.
1052-** iHiwtr = iCur = -1;
1053-** sqlite3_status(SQLITE_STATUS_SCRATCH_USED, &iCur, &iHiwtr, bReset);
1054-** fprintf(pArg->out, "Number of Scratch Allocations Used: %d (max %d)\n", iCur, iHiwtr);
1055-*/
1056- iHiwtr = iCur = -1;
1057- sqlite3_status(SQLITE_STATUS_SCRATCH_OVERFLOW, &iCur, &iHiwtr, bReset);
1058- fprintf(pArg->out, "Number of Scratch Overflow Bytes: %d (max %d) bytes\n", iCur, iHiwtr);
1059- iHiwtr = iCur = -1;
1060- sqlite3_status(SQLITE_STATUS_MALLOC_SIZE, &iCur, &iHiwtr, bReset);
1061- fprintf(pArg->out, "Largest Allocation: %d bytes\n", iHiwtr);
1062- iHiwtr = iCur = -1;
1063- sqlite3_status(SQLITE_STATUS_PAGECACHE_SIZE, &iCur, &iHiwtr, bReset);
1064- fprintf(pArg->out, "Largest Pcache Allocation: %d bytes\n", iHiwtr);
1065- iHiwtr = iCur = -1;
1066- sqlite3_status(SQLITE_STATUS_SCRATCH_SIZE, &iCur, &iHiwtr, bReset);
1067- fprintf(pArg->out, "Largest Scratch Allocation: %d bytes\n", iHiwtr);
1068-#ifdef YYTRACKMAXSTACKDEPTH
1069- iHiwtr = iCur = -1;
1070- sqlite3_status(SQLITE_STATUS_PARSER_STACK, &iCur, &iHiwtr, bReset);
1071- fprintf(pArg->out, "Deepest Parser Stack: %d (max %d)\n", iCur, iHiwtr);
1072-#endif
1073- }
1074-
1075- if( pArg && pArg->out && db ){
1076- iHiwtr = iCur = -1;
1077- sqlite3_db_status(db, SQLITE_DBSTATUS_LOOKASIDE_USED, &iCur, &iHiwtr, bReset);
1078- fprintf(pArg->out, "Lookaside Slots Used: %d (max %d)\n", iCur, iHiwtr);
1079- sqlite3_db_status(db, SQLITE_DBSTATUS_LOOKASIDE_HIT, &iCur, &iHiwtr, bReset);
1080- fprintf(pArg->out, "Successful lookaside attempts: %d\n", iHiwtr);
1081- sqlite3_db_status(db, SQLITE_DBSTATUS_LOOKASIDE_MISS_SIZE, &iCur, &iHiwtr, bReset);
1082- fprintf(pArg->out, "Lookaside failures due to size: %d\n", iHiwtr);
1083- sqlite3_db_status(db, SQLITE_DBSTATUS_LOOKASIDE_MISS_FULL, &iCur, &iHiwtr, bReset);
1084- fprintf(pArg->out, "Lookaside failures due to OOM: %d\n", iHiwtr);
1085- iHiwtr = iCur = -1;
1086- sqlite3_db_status(db, SQLITE_DBSTATUS_CACHE_USED, &iCur, &iHiwtr, bReset);
1087- fprintf(pArg->out, "Pager Heap Usage: %d bytes\n", iCur); iHiwtr = iCur = -1;
1088- sqlite3_db_status(db, SQLITE_DBSTATUS_CACHE_HIT, &iCur, &iHiwtr, 1);
1089- fprintf(pArg->out, "Page cache hits: %d\n", iCur);
1090- iHiwtr = iCur = -1;
1091- sqlite3_db_status(db, SQLITE_DBSTATUS_CACHE_MISS, &iCur, &iHiwtr, 1);
1092- fprintf(pArg->out, "Page cache misses: %d\n", iCur);
1093- iHiwtr = iCur = -1;
1094- sqlite3_db_status(db, SQLITE_DBSTATUS_CACHE_WRITE, &iCur, &iHiwtr, 1);
1095- fprintf(pArg->out, "Page cache writes: %d\n", iCur);
1096- iHiwtr = iCur = -1;
1097- sqlite3_db_status(db, SQLITE_DBSTATUS_SCHEMA_USED, &iCur, &iHiwtr, bReset);
1098- fprintf(pArg->out, "Schema Heap Usage: %d bytes\n", iCur);
1099- iHiwtr = iCur = -1;
1100- sqlite3_db_status(db, SQLITE_DBSTATUS_STMT_USED, &iCur, &iHiwtr, bReset);
1101- fprintf(pArg->out, "Statement Heap/Lookaside Usage: %d bytes\n", iCur);
1102- }
1103-
1104- if( pArg && pArg->out && db && pArg->pStmt ){
1105- iCur = sqlite3_stmt_status(pArg->pStmt, SQLITE_STMTSTATUS_FULLSCAN_STEP, bReset);
1106- fprintf(pArg->out, "Fullscan Steps: %d\n", iCur);
1107- iCur = sqlite3_stmt_status(pArg->pStmt, SQLITE_STMTSTATUS_SORT, bReset);
1108- fprintf(pArg->out, "Sort Operations: %d\n", iCur);
1109- iCur = sqlite3_stmt_status(pArg->pStmt, SQLITE_STMTSTATUS_AUTOINDEX, bReset);
1110- fprintf(pArg->out, "Autoindex Inserts: %d\n", iCur);
1111- }
1112-
1113- return 0;
1114-}
1115-
1116-/*
1117-** Execute a statement or set of statements. Print
1118-** any result rows/columns depending on the current mode
1119-** set via the supplied callback.
1120-**
1121-** This is very similar to SQLite's built-in sqlite3_exec()
1122-** function except it takes a slightly different callback
1123-** and callback data argument.
1124-*/
1125-static int shell_exec(
1126- sqlite3 *db, /* An open database */
1127- const char *zSql, /* SQL to be evaluated */
1128- int (*xCallback)(void*,int,char**,char**,int*), /* Callback function */
1129- /* (not the same as sqlite3_exec) */
1130- struct callback_data *pArg, /* Pointer to struct callback_data */
1131- char **pzErrMsg /* Error msg written here */
1132-){
1133- sqlite3_stmt *pStmt = NULL; /* Statement to execute. */
1134- int rc = SQLITE_OK; /* Return Code */
1135- int rc2;
1136- const char *zLeftover; /* Tail of unprocessed SQL */
1137-
1138- if( pzErrMsg ){
1139- *pzErrMsg = NULL;
1140- }
1141-
1142- while( zSql[0] && (SQLITE_OK == rc) ){
1143- rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, &zLeftover);
1144- if( SQLITE_OK != rc ){
1145- if( pzErrMsg ){
1146- *pzErrMsg = save_err_msg(db);
1147- }
1148- }else{
1149- if( !pStmt ){
1150- /* this happens for a comment or white-space */
1151- zSql = zLeftover;
1152- while( IsSpace(zSql[0]) ) zSql++;
1153- continue;
1154- }
1155-
1156- /* save off the prepared statment handle and reset row count */
1157- if( pArg ){
1158- pArg->pStmt = pStmt;
1159- pArg->cnt = 0;
1160- }
1161-
1162- /* echo the sql statement if echo on */
1163- if( pArg && pArg->echoOn ){
1164- const char *zStmtSql = sqlite3_sql(pStmt);
1165- fprintf(pArg->out, "%s\n", zStmtSql ? zStmtSql : zSql);
1166- }
1167-
1168- /* Output TESTCTRL_EXPLAIN text of requested */
1169- if( pArg && pArg->mode==MODE_Explain ){
1170- const char *zExplain = 0;
1171- sqlite3_test_control(SQLITE_TESTCTRL_EXPLAIN_STMT, pStmt, &zExplain);
1172- if( zExplain && zExplain[0] ){
1173- fprintf(pArg->out, "%s", zExplain);
1174- }
1175- }
1176-
1177- /* perform the first step. this will tell us if we
1178- ** have a result set or not and how wide it is.
1179- */
1180- rc = sqlite3_step(pStmt);
1181- /* if we have a result set... */
1182- if( SQLITE_ROW == rc ){
1183- /* if we have a callback... */
1184- if( xCallback ){
1185- /* allocate space for col name ptr, value ptr, and type */
1186- int nCol = sqlite3_column_count(pStmt);
1187- void *pData = sqlite3_malloc(3*nCol*sizeof(const char*) + 1);
1188- if( !pData ){
1189- rc = SQLITE_NOMEM;
1190- }else{
1191- char **azCols = (char **)pData; /* Names of result columns */
1192- char **azVals = &azCols[nCol]; /* Results */
1193- int *aiTypes = (int *)&azVals[nCol]; /* Result types */
1194- int i;
1195- assert(sizeof(int) <= sizeof(char *));
1196- /* save off ptrs to column names */
1197- for(i=0; i<nCol; i++){
1198- azCols[i] = (char *)sqlite3_column_name(pStmt, i);
1199- }
1200- do{
1201- /* extract the data and data types */
1202- for(i=0; i<nCol; i++){
1203- azVals[i] = (char *)sqlite3_column_text(pStmt, i);
1204- aiTypes[i] = sqlite3_column_type(pStmt, i);
1205- if( !azVals[i] && (aiTypes[i]!=SQLITE_NULL) ){
1206- rc = SQLITE_NOMEM;
1207- break; /* from for */
1208- }
1209- } /* end for */
1210-
1211- /* if data and types extracted successfully... */
1212- if( SQLITE_ROW == rc ){
1213- /* call the supplied callback with the result row data */
1214- if( xCallback(pArg, nCol, azVals, azCols, aiTypes) ){
1215- rc = SQLITE_ABORT;
1216- }else{
1217- rc = sqlite3_step(pStmt);
1218- }
1219- }
1220- } while( SQLITE_ROW == rc );
1221- sqlite3_free(pData);
1222- }
1223- }else{
1224- do{
1225- rc = sqlite3_step(pStmt);
1226- } while( rc == SQLITE_ROW );
1227- }
1228- }
1229-
1230- /* print usage stats if stats on */
1231- if( pArg && pArg->statsOn ){
1232- display_stats(db, pArg, 0);
1233- }
1234-
1235- /* Finalize the statement just executed. If this fails, save a
1236- ** copy of the error message. Otherwise, set zSql to point to the
1237- ** next statement to execute. */
1238- rc2 = sqlite3_finalize(pStmt);
1239- if( rc!=SQLITE_NOMEM ) rc = rc2;
1240- if( rc==SQLITE_OK ){
1241- zSql = zLeftover;
1242- while( IsSpace(zSql[0]) ) zSql++;
1243- }else if( pzErrMsg ){
1244- *pzErrMsg = save_err_msg(db);
1245- }
1246-
1247- /* clear saved stmt handle */
1248- if( pArg ){
1249- pArg->pStmt = NULL;
1250- }
1251- }
1252- } /* end while */
1253-
1254- return rc;
1255-}
1256-
1257-
1258-/*
1259-** This is a different callback routine used for dumping the database.
1260-** Each row received by this callback consists of a table name,
1261-** the table type ("index" or "table") and SQL to create the table.
1262-** This routine should print text sufficient to recreate the table.
1263-*/
1264-static int dump_callback(void *pArg, int nArg, char **azArg, char **azCol){
1265- int rc;
1266- const char *zTable;
1267- const char *zType;
1268- const char *zSql;
1269- const char *zPrepStmt = 0;
1270- struct callback_data *p = (struct callback_data *)pArg;
1271-
1272- UNUSED_PARAMETER(azCol);
1273- if( nArg!=3 ) return 1;
1274- zTable = azArg[0];
1275- zType = azArg[1];
1276- zSql = azArg[2];
1277-
1278- if( strcmp(zTable, "sqlite_sequence")==0 ){
1279- zPrepStmt = "DELETE FROM sqlite_sequence;\n";
1280- }else if( strcmp(zTable, "sqlite_stat1")==0 ){
1281- fprintf(p->out, "ANALYZE sqlite_master;\n");
1282- }else if( strncmp(zTable, "sqlite_", 7)==0 ){
1283- return 0;
1284- }else if( strncmp(zSql, "CREATE VIRTUAL TABLE", 20)==0 ){
1285- char *zIns;
1286- if( !p->writableSchema ){
1287- fprintf(p->out, "PRAGMA writable_schema=ON;\n");
1288- p->writableSchema = 1;
1289- }
1290- zIns = sqlite3_mprintf(
1291- "INSERT INTO sqlite_master(type,name,tbl_name,rootpage,sql)"
1292- "VALUES('table','%q','%q',0,'%q');",
1293- zTable, zTable, zSql);
1294- fprintf(p->out, "%s\n", zIns);
1295- sqlite3_free(zIns);
1296- return 0;
1297- }else{
1298- fprintf(p->out, "%s;\n", zSql);
1299- }
1300-
1301- if( strcmp(zType, "table")==0 ){
1302- sqlite3_stmt *pTableInfo = 0;
1303- char *zSelect = 0;
1304- char *zTableInfo = 0;
1305- char *zTmp = 0;
1306- int nRow = 0;
1307-
1308- zTableInfo = appendText(zTableInfo, "PRAGMA table_info(", 0);
1309- zTableInfo = appendText(zTableInfo, zTable, '"');
1310- zTableInfo = appendText(zTableInfo, ");", 0);
1311-
1312- rc = sqlite3_prepare(p->db, zTableInfo, -1, &pTableInfo, 0);
1313- free(zTableInfo);
1314- if( rc!=SQLITE_OK || !pTableInfo ){
1315- return 1;
1316- }
1317-
1318- zSelect = appendText(zSelect, "SELECT 'INSERT INTO ' || ", 0);
1319- /* Always quote the table name, even if it appears to be pure ascii,
1320- ** in case it is a keyword. Ex: INSERT INTO "table" ... */
1321- zTmp = appendText(zTmp, zTable, '"');
1322- if( zTmp ){
1323- zSelect = appendText(zSelect, zTmp, '\'');
1324- free(zTmp);
1325- }
1326- zSelect = appendText(zSelect, " || ' VALUES(' || ", 0);
1327- rc = sqlite3_step(pTableInfo);
1328- while( rc==SQLITE_ROW ){
1329- const char *zText = (const char *)sqlite3_column_text(pTableInfo, 1);
1330- zSelect = appendText(zSelect, "quote(", 0);
1331- zSelect = appendText(zSelect, zText, '"');
1332- rc = sqlite3_step(pTableInfo);
1333- if( rc==SQLITE_ROW ){
1334- zSelect = appendText(zSelect, "), ", 0);
1335- }else{
1336- zSelect = appendText(zSelect, ") ", 0);
1337- }
1338- nRow++;
1339- }
1340- rc = sqlite3_finalize(pTableInfo);
1341- if( rc!=SQLITE_OK || nRow==0 ){
1342- free(zSelect);
1343- return 1;
1344- }
1345- zSelect = appendText(zSelect, "|| ')' FROM ", 0);
1346- zSelect = appendText(zSelect, zTable, '"');
1347-
1348- rc = run_table_dump_query(p, zSelect, zPrepStmt);
1349- if( rc==SQLITE_CORRUPT ){
1350- zSelect = appendText(zSelect, " ORDER BY rowid DESC", 0);
1351- run_table_dump_query(p, zSelect, 0);
1352- }
1353- free(zSelect);
1354- }
1355- return 0;
1356-}
1357-
1358-/*
1359-** Run zQuery. Use dump_callback() as the callback routine so that
1360-** the contents of the query are output as SQL statements.
1361-**
1362-** If we get a SQLITE_CORRUPT error, rerun the query after appending
1363-** "ORDER BY rowid DESC" to the end.
1364-*/
1365-static int run_schema_dump_query(
1366- struct callback_data *p,
1367- const char *zQuery
1368-){
1369- int rc;
1370- char *zErr = 0;
1371- rc = sqlite3_exec(p->db, zQuery, dump_callback, p, &zErr);
1372- if( rc==SQLITE_CORRUPT ){
1373- char *zQ2;
1374- int len = strlen30(zQuery);
1375- fprintf(p->out, "/****** CORRUPTION ERROR *******/\n");
1376- if( zErr ){
1377- fprintf(p->out, "/****** %s ******/\n", zErr);
1378- sqlite3_free(zErr);
1379- zErr = 0;
1380- }
1381- zQ2 = malloc( len+100 );
1382- if( zQ2==0 ) return rc;
1383- sqlite3_snprintf(len+100, zQ2, "%s ORDER BY rowid DESC", zQuery);
1384- rc = sqlite3_exec(p->db, zQ2, dump_callback, p, &zErr);
1385- if( rc ){
1386- fprintf(p->out, "/****** ERROR: %s ******/\n", zErr);
1387- }else{
1388- rc = SQLITE_CORRUPT;
1389- }
1390- sqlite3_free(zErr);
1391- free(zQ2);
1392- }
1393- return rc;
1394-}
1395-
1396-/*
1397-** Text of a help message
1398-*/
1399-static char zHelp[] =
1400- ".backup ?DB? FILE Backup DB (default \"main\") to FILE\n"
1401- ".bail ON|OFF Stop after hitting an error. Default OFF\n"
1402- ".databases List names and files of attached databases\n"
1403- ".dump ?TABLE? ... Dump the database in an SQL text format\n"
1404- " If TABLE specified, only dump tables matching\n"
1405- " LIKE pattern TABLE.\n"
1406- ".echo ON|OFF Turn command echo on or off\n"
1407- ".exit Exit this program\n"
1408- ".explain ?ON|OFF? Turn output mode suitable for EXPLAIN on or off.\n"
1409- " With no args, it turns EXPLAIN on.\n"
1410- ".header(s) ON|OFF Turn display of headers on or off\n"
1411- ".help Show this message\n"
1412- ".import FILE TABLE Import data from FILE into TABLE\n"
1413- ".indices ?TABLE? Show names of all indices\n"
1414- " If TABLE specified, only show indices for tables\n"
1415- " matching LIKE pattern TABLE.\n"
1416-#ifdef SQLITE_ENABLE_IOTRACE
1417- ".iotrace FILE Enable I/O diagnostic logging to FILE\n"
1418-#endif
1419-#ifndef SQLITE_OMIT_LOAD_EXTENSION
1420- ".load FILE ?ENTRY? Load an extension library\n"
1421-#endif
1422- ".log FILE|off Turn logging on or off. FILE can be stderr/stdout\n"
1423- ".mode MODE ?TABLE? Set output mode where MODE is one of:\n"
1424- " csv Comma-separated values\n"
1425- " column Left-aligned columns. (See .width)\n"
1426- " html HTML <table> code\n"
1427- " insert SQL insert statements for TABLE\n"
1428- " line One value per line\n"
1429- " list Values delimited by .separator string\n"
1430- " tabs Tab-separated values\n"
1431- " tcl TCL list elements\n"
1432- ".nullvalue STRING Use STRING in place of NULL values\n"
1433- ".output FILENAME Send output to FILENAME\n"
1434- ".output stdout Send output to the screen\n"
1435- ".print STRING... Print literal STRING\n"
1436- ".prompt MAIN CONTINUE Replace the standard prompts\n"
1437- ".quit Exit this program\n"
1438- ".read FILENAME Execute SQL in FILENAME\n"
1439- ".restore ?DB? FILE Restore content of DB (default \"main\") from FILE\n"
1440- ".schema ?TABLE? Show the CREATE statements\n"
1441- " If TABLE specified, only show tables matching\n"
1442- " LIKE pattern TABLE.\n"
1443- ".separator STRING Change separator used by output mode and .import\n"
1444- ".show Show the current values for various settings\n"
1445- ".stats ON|OFF Turn stats on or off\n"
1446- ".tables ?TABLE? List names of tables\n"
1447- " If TABLE specified, only list tables matching\n"
1448- " LIKE pattern TABLE.\n"
1449- ".timeout MS Try opening locked tables for MS milliseconds\n"
1450- ".trace FILE|off Output each SQL statement as it is run\n"
1451- ".vfsname ?AUX? Print the name of the VFS stack\n"
1452- ".width NUM1 NUM2 ... Set column widths for \"column\" mode\n"
1453-;
1454-
1455-static char zTimerHelp[] =
1456- ".timer ON|OFF Turn the CPU timer measurement on or off\n"
1457-;
1458-
1459-/* Forward reference */
1460-static int process_input(struct callback_data *p, FILE *in);
1461-
1462-/*
1463-** Make sure the database is open. If it is not, then open it. If
1464-** the database fails to open, print an error message and exit.
1465-*/
1466-static void open_db(struct callback_data *p){
1467- if( p->db==0 ){
1468- sqlite3_initialize();
1469- sqlite3_open(p->zDbFilename, &p->db);
1470- db = p->db;
1471- if( db && sqlite3_errcode(db)==SQLITE_OK ){
1472- sqlite3_create_function(db, "shellstatic", 0, SQLITE_UTF8, 0,
1473- shellstaticFunc, 0, 0);
1474- }
1475- if( db==0 || SQLITE_OK!=sqlite3_errcode(db) ){
1476- fprintf(stderr,"Error: unable to open database \"%s\": %s\n",
1477- p->zDbFilename, sqlite3_errmsg(db));
1478- exit(1);
1479- }
1480-#ifndef SQLITE_OMIT_LOAD_EXTENSION
1481- sqlite3_enable_load_extension(p->db, 1);
1482-#endif
1483- }
1484-}
1485-
1486-/*
1487-** Do C-language style dequoting.
1488-**
1489-** \t -> tab
1490-** \n -> newline
1491-** \r -> carriage return
1492-** \NNN -> ascii character NNN in octal
1493-** \\ -> backslash
1494-*/
1495-static void resolve_backslashes(char *z){
1496- int i, j;
1497- char c;
1498- for(i=j=0; (c = z[i])!=0; i++, j++){
1499- if( c=='\\' ){
1500- c = z[++i];
1501- if( c=='n' ){
1502- c = '\n';
1503- }else if( c=='t' ){
1504- c = '\t';
1505- }else if( c=='r' ){
1506- c = '\r';
1507- }else if( c>='0' && c<='7' ){
1508- c -= '0';
1509- if( z[i+1]>='0' && z[i+1]<='7' ){
1510- i++;
1511- c = (c<<3) + z[i] - '0';
1512- if( z[i+1]>='0' && z[i+1]<='7' ){
1513- i++;
1514- c = (c<<3) + z[i] - '0';
1515- }
1516- }
1517- }
1518- }
1519- z[j] = c;
1520- }
1521- z[j] = 0;
1522-}
1523-
1524-/*
1525-** Interpret zArg as a boolean value. Return either 0 or 1.
1526-*/
1527-static int booleanValue(char *zArg){
1528- int val = atoi(zArg);
1529- int j;
1530- for(j=0; zArg[j]; j++){
1531- zArg[j] = ToLower(zArg[j]);
1532- }
1533- if( strcmp(zArg,"on")==0 ){
1534- val = 1;
1535- }else if( strcmp(zArg,"yes")==0 ){
1536- val = 1;
1537- }
1538- return val;
1539-}
1540-
1541-/*
1542-** Close an output file, assuming it is not stderr or stdout
1543-*/
1544-static void output_file_close(FILE *f){
1545- if( f && f!=stdout && f!=stderr ) fclose(f);
1546-}
1547-
1548-/*
1549-** Try to open an output file. The names "stdout" and "stderr" are
1550-** recognized and do the right thing. NULL is returned if the output
1551-** filename is "off".
1552-*/
1553-static FILE *output_file_open(const char *zFile){
1554- FILE *f;
1555- if( strcmp(zFile,"stdout")==0 ){
1556- f = stdout;
1557- }else if( strcmp(zFile, "stderr")==0 ){
1558- f = stderr;
1559- }else if( strcmp(zFile, "off")==0 ){
1560- f = 0;
1561- }else{
1562- f = fopen(zFile, "wb");
1563- if( f==0 ){
1564- fprintf(stderr, "Error: cannot open \"%s\"\n", zFile);
1565- }
1566- }
1567- return f;
1568-}
1569-
1570-/*
1571-** A routine for handling output from sqlite3_trace().
1572-*/
1573-static void sql_trace_callback(void *pArg, const char *z){
1574- FILE *f = (FILE*)pArg;
1575- if( f ) fprintf(f, "%s\n", z);
1576-}
1577-
1578-/*
1579-** A no-op routine that runs with the ".breakpoint" doc-command. This is
1580-** a useful spot to set a debugger breakpoint.
1581-*/
1582-static void test_breakpoint(void){
1583- static int nCall = 0;
1584- nCall++;
1585-}
1586-
1587-/*
1588-** If an input line begins with "." then invoke this routine to
1589-** process that line.
1590-**
1591-** Return 1 on error, 2 to exit, and 0 otherwise.
1592-*/
1593-static int do_meta_command(char *zLine, struct callback_data *p){
1594- int i = 1;
1595- int nArg = 0;
1596- int n, c;
1597- int rc = 0;
1598- char *azArg[50];
1599-
1600- /* Parse the input line into tokens.
1601- */
1602- while( zLine[i] && nArg<ArraySize(azArg) ){
1603- while( IsSpace(zLine[i]) ){ i++; }
1604- if( zLine[i]==0 ) break;
1605- if( zLine[i]=='\'' || zLine[i]=='"' ){
1606- int delim = zLine[i++];
1607- azArg[nArg++] = &zLine[i];
1608- while( zLine[i] && zLine[i]!=delim ){ i++; }
1609- if( zLine[i]==delim ){
1610- zLine[i++] = 0;
1611- }
1612- if( delim=='"' ) resolve_backslashes(azArg[nArg-1]);
1613- }else{
1614- azArg[nArg++] = &zLine[i];
1615- while( zLine[i] && !IsSpace(zLine[i]) ){ i++; }
1616- if( zLine[i] ) zLine[i++] = 0;
1617- resolve_backslashes(azArg[nArg-1]);
1618- }
1619- }
1620-
1621- /* Process the input line.
1622- */
1623- if( nArg==0 ) return 0; /* no tokens, no error */
1624- n = strlen30(azArg[0]);
1625- c = azArg[0][0];
1626- if( c=='b' && n>=3 && strncmp(azArg[0], "backup", n)==0 && nArg>1 && nArg<4){
1627- const char *zDestFile;
1628- const char *zDb;
1629- sqlite3 *pDest;
1630- sqlite3_backup *pBackup;
1631- if( nArg==2 ){
1632- zDestFile = azArg[1];
1633- zDb = "main";
1634- }else{
1635- zDestFile = azArg[2];
1636- zDb = azArg[1];
1637- }
1638- rc = sqlite3_open(zDestFile, &pDest);
1639- if( rc!=SQLITE_OK ){
1640- fprintf(stderr, "Error: cannot open \"%s\"\n", zDestFile);
1641- sqlite3_close(pDest);
1642- return 1;
1643- }
1644- open_db(p);
1645- pBackup = sqlite3_backup_init(pDest, "main", p->db, zDb);
1646- if( pBackup==0 ){
1647- fprintf(stderr, "Error: %s\n", sqlite3_errmsg(pDest));
1648- sqlite3_close(pDest);
1649- return 1;
1650- }
1651- while( (rc = sqlite3_backup_step(pBackup,100))==SQLITE_OK ){}
1652- sqlite3_backup_finish(pBackup);
1653- if( rc==SQLITE_DONE ){
1654- rc = 0;
1655- }else{
1656- fprintf(stderr, "Error: %s\n", sqlite3_errmsg(pDest));
1657- rc = 1;
1658- }
1659- sqlite3_close(pDest);
1660- }else
1661-
1662- if( c=='b' && n>=3 && strncmp(azArg[0], "bail", n)==0 && nArg>1 && nArg<3 ){
1663- bail_on_error = booleanValue(azArg[1]);
1664- }else
1665-
1666- /* The undocumented ".breakpoint" command causes a call to the no-op
1667- ** routine named test_breakpoint().
1668- */
1669- if( c=='b' && n>=3 && strncmp(azArg[0], "breakpoint", n)==0 ){
1670- test_breakpoint();
1671- }else
1672-
1673- if( c=='d' && n>1 && strncmp(azArg[0], "databases", n)==0 && nArg==1 ){
1674- struct callback_data data;
1675- char *zErrMsg = 0;
1676- open_db(p);
1677- memcpy(&data, p, sizeof(data));
1678- data.showHeader = 1;
1679- data.mode = MODE_Column;
1680- data.colWidth[0] = 3;
1681- data.colWidth[1] = 15;
1682- data.colWidth[2] = 58;
1683- data.cnt = 0;
1684- sqlite3_exec(p->db, "PRAGMA database_list; ", callback, &data, &zErrMsg);
1685- if( zErrMsg ){
1686- fprintf(stderr,"Error: %s\n", zErrMsg);
1687- sqlite3_free(zErrMsg);
1688- rc = 1;
1689- }
1690- }else
1691-
1692- if( c=='d' && strncmp(azArg[0], "dump", n)==0 && nArg<3 ){
1693- open_db(p);
1694- /* When playing back a "dump", the content might appear in an order
1695- ** which causes immediate foreign key constraints to be violated.
1696- ** So disable foreign-key constraint enforcement to prevent problems. */
1697- fprintf(p->out, "PRAGMA foreign_keys=OFF;\n");
1698- fprintf(p->out, "BEGIN TRANSACTION;\n");
1699- p->writableSchema = 0;
1700- sqlite3_exec(p->db, "SAVEPOINT dump; PRAGMA writable_schema=ON", 0, 0, 0);
1701- p->nErr = 0;
1702- if( nArg==1 ){
1703- run_schema_dump_query(p,
1704- "SELECT name, type, sql FROM sqlite_master "
1705- "WHERE sql NOT NULL AND type=='table' AND name!='sqlite_sequence'"
1706- );
1707- run_schema_dump_query(p,
1708- "SELECT name, type, sql FROM sqlite_master "
1709- "WHERE name=='sqlite_sequence'"
1710- );
1711- run_table_dump_query(p,
1712- "SELECT sql FROM sqlite_master "
1713- "WHERE sql NOT NULL AND type IN ('index','trigger','view')", 0
1714- );
1715- }else{
1716- int i;
1717- for(i=1; i<nArg; i++){
1718- zShellStatic = azArg[i];
1719- run_schema_dump_query(p,
1720- "SELECT name, type, sql FROM sqlite_master "
1721- "WHERE tbl_name LIKE shellstatic() AND type=='table'"
1722- " AND sql NOT NULL");
1723- run_table_dump_query(p,
1724- "SELECT sql FROM sqlite_master "
1725- "WHERE sql NOT NULL"
1726- " AND type IN ('index','trigger','view')"
1727- " AND tbl_name LIKE shellstatic()", 0
1728- );
1729- zShellStatic = 0;
1730- }
1731- }
1732- if( p->writableSchema ){
1733- fprintf(p->out, "PRAGMA writable_schema=OFF;\n");
1734- p->writableSchema = 0;
1735- }
1736- sqlite3_exec(p->db, "PRAGMA writable_schema=OFF;", 0, 0, 0);
1737- sqlite3_exec(p->db, "RELEASE dump;", 0, 0, 0);
1738- fprintf(p->out, p->nErr ? "ROLLBACK; -- due to errors\n" : "COMMIT;\n");
1739- }else
1740-
1741- if( c=='e' && strncmp(azArg[0], "echo", n)==0 && nArg>1 && nArg<3 ){
1742- p->echoOn = booleanValue(azArg[1]);
1743- }else
1744-
1745- if( c=='e' && strncmp(azArg[0], "exit", n)==0 && nArg==1 ){
1746- rc = 2;
1747- }else
1748-
1749- if( c=='e' && strncmp(azArg[0], "explain", n)==0 && nArg<3 ){
1750- int val = nArg>=2 ? booleanValue(azArg[1]) : 1;
1751- if(val == 1) {
1752- if(!p->explainPrev.valid) {
1753- p->explainPrev.valid = 1;
1754- p->explainPrev.mode = p->mode;
1755- p->explainPrev.showHeader = p->showHeader;
1756- memcpy(p->explainPrev.colWidth,p->colWidth,sizeof(p->colWidth));
1757- }
1758- /* We could put this code under the !p->explainValid
1759- ** condition so that it does not execute if we are already in
1760- ** explain mode. However, always executing it allows us an easy
1761- ** was to reset to explain mode in case the user previously
1762- ** did an .explain followed by a .width, .mode or .header
1763- ** command.
1764- */
1765- p->mode = MODE_Explain;
1766- p->showHeader = 1;
1767- memset(p->colWidth,0,ArraySize(p->colWidth));
1768- p->colWidth[0] = 4; /* addr */
1769- p->colWidth[1] = 13; /* opcode */
1770- p->colWidth[2] = 4; /* P1 */
1771- p->colWidth[3] = 4; /* P2 */
1772- p->colWidth[4] = 4; /* P3 */
1773- p->colWidth[5] = 13; /* P4 */
1774- p->colWidth[6] = 2; /* P5 */
1775- p->colWidth[7] = 13; /* Comment */
1776- }else if (p->explainPrev.valid) {
1777- p->explainPrev.valid = 0;
1778- p->mode = p->explainPrev.mode;
1779- p->showHeader = p->explainPrev.showHeader;
1780- memcpy(p->colWidth,p->explainPrev.colWidth,sizeof(p->colWidth));
1781- }
1782- }else
1783-
1784- if( c=='h' && (strncmp(azArg[0], "header", n)==0 ||
1785- strncmp(azArg[0], "headers", n)==0) && nArg>1 && nArg<3 ){
1786- p->showHeader = booleanValue(azArg[1]);
1787- }else
1788-
1789- if( c=='h' && strncmp(azArg[0], "help", n)==0 ){
1790- fprintf(stderr,"%s",zHelp);
1791- if( HAS_TIMER ){
1792- fprintf(stderr,"%s",zTimerHelp);
1793- }
1794- }else
1795-
1796- if( c=='i' && strncmp(azArg[0], "import", n)==0 && nArg==3 ){
1797- char *zTable = azArg[2]; /* Insert data into this table */
1798- char *zFile = azArg[1]; /* The file from which to extract data */
1799- sqlite3_stmt *pStmt = NULL; /* A statement */
1800- int nCol; /* Number of columns in the table */
1801- int nByte; /* Number of bytes in an SQL string */
1802- int i, j; /* Loop counters */
1803- int nSep; /* Number of bytes in p->separator[] */
1804- char *zSql; /* An SQL statement */
1805- char *zLine; /* A single line of input from the file */
1806- char **azCol; /* zLine[] broken up into columns */
1807- char *zCommit; /* How to commit changes */
1808- FILE *in; /* The input file */
1809- int lineno = 0; /* Line number of input file */
1810-
1811- open_db(p);
1812- nSep = strlen30(p->separator);
1813- if( nSep==0 ){
1814- fprintf(stderr, "Error: non-null separator required for import\n");
1815- return 1;
1816- }
1817- zSql = sqlite3_mprintf("SELECT * FROM %s", zTable);
1818- if( zSql==0 ){
1819- fprintf(stderr, "Error: out of memory\n");
1820- return 1;
1821- }
1822- nByte = strlen30(zSql);
1823- rc = sqlite3_prepare(p->db, zSql, -1, &pStmt, 0);
1824- sqlite3_free(zSql);
1825- if( rc ){
1826- if (pStmt) sqlite3_finalize(pStmt);
1827- fprintf(stderr,"Error: %s\n", sqlite3_errmsg(db));
1828- return 1;
1829- }
1830- nCol = sqlite3_column_count(pStmt);
1831- sqlite3_finalize(pStmt);
1832- pStmt = 0;
1833- if( nCol==0 ) return 0; /* no columns, no error */
1834- zSql = malloc( nByte + 20 + nCol*2 );
1835- if( zSql==0 ){
1836- fprintf(stderr, "Error: out of memory\n");
1837- return 1;
1838- }
1839- sqlite3_snprintf(nByte+20, zSql, "INSERT INTO %s VALUES(?", zTable);
1840- j = strlen30(zSql);
1841- for(i=1; i<nCol; i++){
1842- zSql[j++] = ',';
1843- zSql[j++] = '?';
1844- }
1845- zSql[j++] = ')';
1846- zSql[j] = 0;
1847- rc = sqlite3_prepare(p->db, zSql, -1, &pStmt, 0);
1848- free(zSql);
1849- if( rc ){
1850- fprintf(stderr, "Error: %s\n", sqlite3_errmsg(db));
1851- if (pStmt) sqlite3_finalize(pStmt);
1852- return 1;
1853- }
1854- in = fopen(zFile, "rb");
1855- if( in==0 ){
1856- fprintf(stderr, "Error: cannot open \"%s\"\n", zFile);
1857- sqlite3_finalize(pStmt);
1858- return 1;
1859- }
1860- azCol = malloc( sizeof(azCol[0])*(nCol+1) );
1861- if( azCol==0 ){
1862- fprintf(stderr, "Error: out of memory\n");
1863- fclose(in);
1864- sqlite3_finalize(pStmt);
1865- return 1;
1866- }
1867- sqlite3_exec(p->db, "BEGIN", 0, 0, 0);
1868- zCommit = "COMMIT";
1869- while( (zLine = local_getline(0, in, 1))!=0 ){
1870- char *z, c;
1871- int inQuote = 0;
1872- lineno++;
1873- azCol[0] = zLine;
1874- for(i=0, z=zLine; (c = *z)!=0; z++){
1875- if( c=='"' ) inQuote = !inQuote;
1876- if( c=='\n' ) lineno++;
1877- if( !inQuote && c==p->separator[0] && strncmp(z,p->separator,nSep)==0 ){
1878- *z = 0;
1879- i++;
1880- if( i<nCol ){
1881- azCol[i] = &z[nSep];
1882- z += nSep-1;
1883- }
1884- }
1885- } /* end for */
1886- *z = 0;
1887- if( i+1!=nCol ){
1888- fprintf(stderr,
1889- "Error: %s line %d: expected %d columns of data but found %d\n",
1890- zFile, lineno, nCol, i+1);
1891- zCommit = "ROLLBACK";
1892- free(zLine);
1893- rc = 1;
1894- break; /* from while */
1895- }
1896- for(i=0; i<nCol; i++){
1897- if( azCol[i][0]=='"' ){
1898- int k;
1899- for(z=azCol[i], j=1, k=0; z[j]; j++){
1900- if( z[j]=='"' ){ j++; if( z[j]==0 ) break; }
1901- z[k++] = z[j];
1902- }
1903- z[k] = 0;
1904- }
1905- sqlite3_bind_text(pStmt, i+1, azCol[i], -1, SQLITE_STATIC);
1906- }
1907- sqlite3_step(pStmt);
1908- rc = sqlite3_reset(pStmt);
1909- free(zLine);
1910- if( rc!=SQLITE_OK ){
1911- fprintf(stderr,"Error: %s\n", sqlite3_errmsg(db));
1912- zCommit = "ROLLBACK";
1913- rc = 1;
1914- break; /* from while */
1915- }
1916- } /* end while */
1917- free(azCol);
1918- fclose(in);
1919- sqlite3_finalize(pStmt);
1920- sqlite3_exec(p->db, zCommit, 0, 0, 0);
1921- }else
1922-
1923- if( c=='i' && strncmp(azArg[0], "indices", n)==0 && nArg<3 ){
1924- struct callback_data data;
1925- char *zErrMsg = 0;
1926- open_db(p);
1927- memcpy(&data, p, sizeof(data));
1928- data.showHeader = 0;
1929- data.mode = MODE_List;
1930- if( nArg==1 ){
1931- rc = sqlite3_exec(p->db,
1932- "SELECT name FROM sqlite_master "
1933- "WHERE type='index' AND name NOT LIKE 'sqlite_%' "
1934- "UNION ALL "
1935- "SELECT name FROM sqlite_temp_master "
1936- "WHERE type='index' "
1937- "ORDER BY 1",
1938- callback, &data, &zErrMsg
1939- );
1940- }else{
1941- zShellStatic = azArg[1];
1942- rc = sqlite3_exec(p->db,
1943- "SELECT name FROM sqlite_master "
1944- "WHERE type='index' AND tbl_name LIKE shellstatic() "
1945- "UNION ALL "
1946- "SELECT name FROM sqlite_temp_master "
1947- "WHERE type='index' AND tbl_name LIKE shellstatic() "
1948- "ORDER BY 1",
1949- callback, &data, &zErrMsg
1950- );
1951- zShellStatic = 0;
1952- }
1953- if( zErrMsg ){
1954- fprintf(stderr,"Error: %s\n", zErrMsg);
1955- sqlite3_free(zErrMsg);
1956- rc = 1;
1957- }else if( rc != SQLITE_OK ){
1958- fprintf(stderr,"Error: querying sqlite_master and sqlite_temp_master\n");
1959- rc = 1;
1960- }
1961- }else
1962-
1963-#ifdef SQLITE_ENABLE_IOTRACE
1964- if( c=='i' && strncmp(azArg[0], "iotrace", n)==0 ){
1965- extern void (*sqlite3IoTrace)(const char*, ...);
1966- if( iotrace && iotrace!=stdout ) fclose(iotrace);
1967- iotrace = 0;
1968- if( nArg<2 ){
1969- sqlite3IoTrace = 0;
1970- }else if( strcmp(azArg[1], "-")==0 ){
1971- sqlite3IoTrace = iotracePrintf;
1972- iotrace = stdout;
1973- }else{
1974- iotrace = fopen(azArg[1], "w");
1975- if( iotrace==0 ){
1976- fprintf(stderr, "Error: cannot open \"%s\"\n", azArg[1]);
1977- sqlite3IoTrace = 0;
1978- rc = 1;
1979- }else{
1980- sqlite3IoTrace = iotracePrintf;
1981- }
1982- }
1983- }else
1984-#endif
1985-
1986-#ifndef SQLITE_OMIT_LOAD_EXTENSION
1987- if( c=='l' && strncmp(azArg[0], "load", n)==0 && nArg>=2 ){
1988- const char *zFile, *zProc;
1989- char *zErrMsg = 0;
1990- zFile = azArg[1];
1991- zProc = nArg>=3 ? azArg[2] : 0;
1992- open_db(p);
1993- rc = sqlite3_load_extension(p->db, zFile, zProc, &zErrMsg);
1994- if( rc!=SQLITE_OK ){
1995- fprintf(stderr, "Error: %s\n", zErrMsg);
1996- sqlite3_free(zErrMsg);
1997- rc = 1;
1998- }
1999- }else
2000-#endif
2001-
2002- if( c=='l' && strncmp(azArg[0], "log", n)==0 && nArg>=2 ){
2003- const char *zFile = azArg[1];
2004- output_file_close(p->pLog);
2005- p->pLog = output_file_open(zFile);
2006- }else
2007-
2008- if( c=='m' && strncmp(azArg[0], "mode", n)==0 && nArg==2 ){
2009- int n2 = strlen30(azArg[1]);
2010- if( (n2==4 && strncmp(azArg[1],"line",n2)==0)
2011- ||
2012- (n2==5 && strncmp(azArg[1],"lines",n2)==0) ){
2013- p->mode = MODE_Line;
2014- }else if( (n2==6 && strncmp(azArg[1],"column",n2)==0)
2015- ||
2016- (n2==7 && strncmp(azArg[1],"columns",n2)==0) ){
2017- p->mode = MODE_Column;
2018- }else if( n2==4 && strncmp(azArg[1],"list",n2)==0 ){
2019- p->mode = MODE_List;
2020- }else if( n2==4 && strncmp(azArg[1],"html",n2)==0 ){
2021- p->mode = MODE_Html;
2022- }else if( n2==3 && strncmp(azArg[1],"tcl",n2)==0 ){
2023- p->mode = MODE_Tcl;
2024- sqlite3_snprintf(sizeof(p->separator), p->separator, " ");
2025- }else if( n2==3 && strncmp(azArg[1],"csv",n2)==0 ){
2026- p->mode = MODE_Csv;
2027- sqlite3_snprintf(sizeof(p->separator), p->separator, ",");
2028- }else if( n2==4 && strncmp(azArg[1],"tabs",n2)==0 ){
2029- p->mode = MODE_List;
2030- sqlite3_snprintf(sizeof(p->separator), p->separator, "\t");
2031- }else if( n2==6 && strncmp(azArg[1],"insert",n2)==0 ){
2032- p->mode = MODE_Insert;
2033- set_table_name(p, "table");
2034- }else {
2035- fprintf(stderr,"Error: mode should be one of: "
2036- "column csv html insert line list tabs tcl\n");
2037- rc = 1;
2038- }
2039- }else
2040-
2041- if( c=='m' && strncmp(azArg[0], "mode", n)==0 && nArg==3 ){
2042- int n2 = strlen30(azArg[1]);
2043- if( n2==6 && strncmp(azArg[1],"insert",n2)==0 ){
2044- p->mode = MODE_Insert;
2045- set_table_name(p, azArg[2]);
2046- }else {
2047- fprintf(stderr, "Error: invalid arguments: "
2048- " \"%s\". Enter \".help\" for help\n", azArg[2]);
2049- rc = 1;
2050- }
2051- }else
2052-
2053- if( c=='n' && strncmp(azArg[0], "nullvalue", n)==0 && nArg==2 ) {
2054- sqlite3_snprintf(sizeof(p->nullvalue), p->nullvalue,
2055- "%.*s", (int)ArraySize(p->nullvalue)-1, azArg[1]);
2056- }else
2057-
2058- if( c=='o' && strncmp(azArg[0], "output", n)==0 && nArg==2 ){
2059- if( p->outfile[0]=='|' ){
2060- pclose(p->out);
2061- }else{
2062- output_file_close(p->out);
2063- }
2064- p->outfile[0] = 0;
2065- if( azArg[1][0]=='|' ){
2066- p->out = popen(&azArg[1][1], "w");
2067- if( p->out==0 ){
2068- fprintf(stderr,"Error: cannot open pipe \"%s\"\n", &azArg[1][1]);
2069- p->out = stdout;
2070- rc = 1;
2071- }else{
2072- sqlite3_snprintf(sizeof(p->outfile), p->outfile, "%s", azArg[1]);
2073- }
2074- }else{
2075- p->out = output_file_open(azArg[1]);
2076- if( p->out==0 ){
2077- if( strcmp(azArg[1],"off")!=0 ){
2078- fprintf(stderr,"Error: cannot write to \"%s\"\n", azArg[1]);
2079- }
2080- p->out = stdout;
2081- rc = 1;
2082- } else {
2083- sqlite3_snprintf(sizeof(p->outfile), p->outfile, "%s", azArg[1]);
2084- }
2085- }
2086- }else
2087-
2088- if( c=='p' && n>=3 && strncmp(azArg[0], "print", n)==0 ){
2089- int i;
2090- for(i=1; i<nArg; i++){
2091- if( i>1 ) fprintf(p->out, " ");
2092- fprintf(p->out, "%s", azArg[i]);
2093- }
2094- fprintf(p->out, "\n");
2095- }else
2096-
2097- if( c=='p' && strncmp(azArg[0], "prompt", n)==0 && (nArg==2 || nArg==3)){
2098- if( nArg >= 2) {
2099- strncpy(mainPrompt,azArg[1],(int)ArraySize(mainPrompt)-1);
2100- }
2101- if( nArg >= 3) {
2102- strncpy(continuePrompt,azArg[2],(int)ArraySize(continuePrompt)-1);
2103- }
2104- }else
2105-
2106- if( c=='q' && strncmp(azArg[0], "quit", n)==0 && nArg==1 ){
2107- rc = 2;
2108- }else
2109-
2110- if( c=='r' && n>=3 && strncmp(azArg[0], "read", n)==0 && nArg==2 ){
2111- FILE *alt = fopen(azArg[1], "rb");
2112- if( alt==0 ){
2113- fprintf(stderr,"Error: cannot open \"%s\"\n", azArg[1]);
2114- rc = 1;
2115- }else{
2116- rc = process_input(p, alt);
2117- fclose(alt);
2118- }
2119- }else
2120-
2121- if( c=='r' && n>=3 && strncmp(azArg[0], "restore", n)==0 && nArg>1 && nArg<4){
2122- const char *zSrcFile;
2123- const char *zDb;
2124- sqlite3 *pSrc;
2125- sqlite3_backup *pBackup;
2126- int nTimeout = 0;
2127-
2128- if( nArg==2 ){
2129- zSrcFile = azArg[1];
2130- zDb = "main";
2131- }else{
2132- zSrcFile = azArg[2];
2133- zDb = azArg[1];
2134- }
2135- rc = sqlite3_open(zSrcFile, &pSrc);
2136- if( rc!=SQLITE_OK ){
2137- fprintf(stderr, "Error: cannot open \"%s\"\n", zSrcFile);
2138- sqlite3_close(pSrc);
2139- return 1;
2140- }
2141- open_db(p);
2142- pBackup = sqlite3_backup_init(p->db, zDb, pSrc, "main");
2143- if( pBackup==0 ){
2144- fprintf(stderr, "Error: %s\n", sqlite3_errmsg(p->db));
2145- sqlite3_close(pSrc);
2146- return 1;
2147- }
2148- while( (rc = sqlite3_backup_step(pBackup,100))==SQLITE_OK
2149- || rc==SQLITE_BUSY ){
2150- if( rc==SQLITE_BUSY ){
2151- if( nTimeout++ >= 3 ) break;
2152- sqlite3_sleep(100);
2153- }
2154- }
2155- sqlite3_backup_finish(pBackup);
2156- if( rc==SQLITE_DONE ){
2157- rc = 0;
2158- }else if( rc==SQLITE_BUSY || rc==SQLITE_LOCKED ){
2159- fprintf(stderr, "Error: source database is busy\n");
2160- rc = 1;
2161- }else{
2162- fprintf(stderr, "Error: %s\n", sqlite3_errmsg(p->db));
2163- rc = 1;
2164- }
2165- sqlite3_close(pSrc);
2166- }else
2167-
2168- if( c=='s' && strncmp(azArg[0], "schema", n)==0 && nArg<3 ){
2169- struct callback_data data;
2170- char *zErrMsg = 0;
2171- open_db(p);
2172- memcpy(&data, p, sizeof(data));
2173- data.showHeader = 0;
2174- data.mode = MODE_Semi;
2175- if( nArg>1 ){
2176- int i;
2177- for(i=0; azArg[1][i]; i++) azArg[1][i] = ToLower(azArg[1][i]);
2178- if( strcmp(azArg[1],"sqlite_master")==0 ){
2179- char *new_argv[2], *new_colv[2];
2180- new_argv[0] = "CREATE TABLE sqlite_master (\n"
2181- " type text,\n"
2182- " name text,\n"
2183- " tbl_name text,\n"
2184- " rootpage integer,\n"
2185- " sql text\n"
2186- ")";
2187- new_argv[1] = 0;
2188- new_colv[0] = "sql";
2189- new_colv[1] = 0;
2190- callback(&data, 1, new_argv, new_colv);
2191- rc = SQLITE_OK;
2192- }else if( strcmp(azArg[1],"sqlite_temp_master")==0 ){
2193- char *new_argv[2], *new_colv[2];
2194- new_argv[0] = "CREATE TEMP TABLE sqlite_temp_master (\n"
2195- " type text,\n"
2196- " name text,\n"
2197- " tbl_name text,\n"
2198- " rootpage integer,\n"
2199- " sql text\n"
2200- ")";
2201- new_argv[1] = 0;
2202- new_colv[0] = "sql";
2203- new_colv[1] = 0;
2204- callback(&data, 1, new_argv, new_colv);
2205- rc = SQLITE_OK;
2206- }else{
2207- zShellStatic = azArg[1];
2208- rc = sqlite3_exec(p->db,
2209- "SELECT sql FROM "
2210- " (SELECT sql sql, type type, tbl_name tbl_name, name name, rowid x"
2211- " FROM sqlite_master UNION ALL"
2212- " SELECT sql, type, tbl_name, name, rowid FROM sqlite_temp_master) "
2213- "WHERE lower(tbl_name) LIKE shellstatic()"
2214- " AND type!='meta' AND sql NOTNULL "
2215- "ORDER BY substr(type,2,1), "
2216- " CASE type WHEN 'view' THEN rowid ELSE name END",
2217- callback, &data, &zErrMsg);
2218- zShellStatic = 0;
2219- }
2220- }else{
2221- rc = sqlite3_exec(p->db,
2222- "SELECT sql FROM "
2223- " (SELECT sql sql, type type, tbl_name tbl_name, name name, rowid x"
2224- " FROM sqlite_master UNION ALL"
2225- " SELECT sql, type, tbl_name, name, rowid FROM sqlite_temp_master) "
2226- "WHERE type!='meta' AND sql NOTNULL AND name NOT LIKE 'sqlite_%'"
2227- "ORDER BY substr(type,2,1),"
2228- " CASE type WHEN 'view' THEN rowid ELSE name END",
2229- callback, &data, &zErrMsg
2230- );
2231- }
2232- if( zErrMsg ){
2233- fprintf(stderr,"Error: %s\n", zErrMsg);
2234- sqlite3_free(zErrMsg);
2235- rc = 1;
2236- }else if( rc != SQLITE_OK ){
2237- fprintf(stderr,"Error: querying schema information\n");
2238- rc = 1;
2239- }else{
2240- rc = 0;
2241- }
2242- }else
2243-
2244- if( c=='s' && strncmp(azArg[0], "separator", n)==0 && nArg==2 ){
2245- sqlite3_snprintf(sizeof(p->separator), p->separator,
2246- "%.*s", (int)sizeof(p->separator)-1, azArg[1]);
2247- }else
2248-
2249- if( c=='s' && strncmp(azArg[0], "show", n)==0 && nArg==1 ){
2250- int i;
2251- fprintf(p->out,"%9.9s: %s\n","echo", p->echoOn ? "on" : "off");
2252- fprintf(p->out,"%9.9s: %s\n","explain", p->explainPrev.valid ? "on" :"off");
2253- fprintf(p->out,"%9.9s: %s\n","headers", p->showHeader ? "on" : "off");
2254- fprintf(p->out,"%9.9s: %s\n","mode", modeDescr[p->mode]);
2255- fprintf(p->out,"%9.9s: ", "nullvalue");
2256- output_c_string(p->out, p->nullvalue);
2257- fprintf(p->out, "\n");
2258- fprintf(p->out,"%9.9s: %s\n","output",
2259- strlen30(p->outfile) ? p->outfile : "stdout");
2260- fprintf(p->out,"%9.9s: ", "separator");
2261- output_c_string(p->out, p->separator);
2262- fprintf(p->out, "\n");
2263- fprintf(p->out,"%9.9s: %s\n","stats", p->statsOn ? "on" : "off");
2264- fprintf(p->out,"%9.9s: ","width");
2265- for (i=0;i<(int)ArraySize(p->colWidth) && p->colWidth[i] != 0;i++) {
2266- fprintf(p->out,"%d ",p->colWidth[i]);
2267- }
2268- fprintf(p->out,"\n");
2269- }else
2270-
2271- if( c=='s' && strncmp(azArg[0], "stats", n)==0 && nArg>1 && nArg<3 ){
2272- p->statsOn = booleanValue(azArg[1]);
2273- }else
2274-
2275- if( c=='t' && n>1 && strncmp(azArg[0], "tables", n)==0 && nArg<3 ){
2276- sqlite3_stmt *pStmt;
2277- char **azResult;
2278- int nRow, nAlloc;
2279- char *zSql = 0;
2280- int ii;
2281- open_db(p);
2282- rc = sqlite3_prepare_v2(p->db, "PRAGMA database_list", -1, &pStmt, 0);
2283- if( rc ) return rc;
2284- zSql = sqlite3_mprintf(
2285- "SELECT name FROM sqlite_master"
2286- " WHERE type IN ('table','view')"
2287- " AND name NOT LIKE 'sqlite_%%'"
2288- " AND name LIKE ?1");
2289- while( sqlite3_step(pStmt)==SQLITE_ROW ){
2290- const char *zDbName = (const char*)sqlite3_column_text(pStmt, 1);
2291- if( zDbName==0 || strcmp(zDbName,"main")==0 ) continue;
2292- if( strcmp(zDbName,"temp")==0 ){
2293- zSql = sqlite3_mprintf(
2294- "%z UNION ALL "
2295- "SELECT 'temp.' || name FROM sqlite_temp_master"
2296- " WHERE type IN ('table','view')"
2297- " AND name NOT LIKE 'sqlite_%%'"
2298- " AND name LIKE ?1", zSql);
2299- }else{
2300- zSql = sqlite3_mprintf(
2301- "%z UNION ALL "
2302- "SELECT '%q.' || name FROM \"%w\".sqlite_master"
2303- " WHERE type IN ('table','view')"
2304- " AND name NOT LIKE 'sqlite_%%'"
2305- " AND name LIKE ?1", zSql, zDbName, zDbName);
2306- }
2307- }
2308- sqlite3_finalize(pStmt);
2309- zSql = sqlite3_mprintf("%z ORDER BY 1", zSql);
2310- rc = sqlite3_prepare_v2(p->db, zSql, -1, &pStmt, 0);
2311- sqlite3_free(zSql);
2312- if( rc ) return rc;
2313- nRow = nAlloc = 0;
2314- azResult = 0;
2315- if( nArg>1 ){
2316- sqlite3_bind_text(pStmt, 1, azArg[1], -1, SQLITE_TRANSIENT);
2317- }else{
2318- sqlite3_bind_text(pStmt, 1, "%", -1, SQLITE_STATIC);
2319- }
2320- while( sqlite3_step(pStmt)==SQLITE_ROW ){
2321- if( nRow>=nAlloc ){
2322- char **azNew;
2323- int n = nAlloc*2 + 10;
2324- azNew = sqlite3_realloc(azResult, sizeof(azResult[0])*n);
2325- if( azNew==0 ){
2326- fprintf(stderr, "Error: out of memory\n");
2327- break;
2328- }
2329- nAlloc = n;
2330- azResult = azNew;
2331- }
2332- azResult[nRow] = sqlite3_mprintf("%s", sqlite3_column_text(pStmt, 0));
2333- if( azResult[nRow] ) nRow++;
2334- }
2335- sqlite3_finalize(pStmt);
2336- if( nRow>0 ){
2337- int len, maxlen = 0;
2338- int i, j;
2339- int nPrintCol, nPrintRow;
2340- for(i=0; i<nRow; i++){
2341- len = strlen30(azResult[i]);
2342- if( len>maxlen ) maxlen = len;
2343- }
2344- nPrintCol = 80/(maxlen+2);
2345- if( nPrintCol<1 ) nPrintCol = 1;
2346- nPrintRow = (nRow + nPrintCol - 1)/nPrintCol;
2347- for(i=0; i<nPrintRow; i++){
2348- for(j=i; j<nRow; j+=nPrintRow){
2349- char *zSp = j<nPrintRow ? "" : " ";
2350- printf("%s%-*s", zSp, maxlen, azResult[j] ? azResult[j] : "");
2351- }
2352- printf("\n");
2353- }
2354- }
2355- for(ii=0; ii<nRow; ii++) sqlite3_free(azResult[ii]);
2356- sqlite3_free(azResult);
2357- }else
2358-
2359- if( c=='t' && n>=8 && strncmp(azArg[0], "testctrl", n)==0 && nArg>=2 ){
2360- static const struct {
2361- const char *zCtrlName; /* Name of a test-control option */
2362- int ctrlCode; /* Integer code for that option */
2363- } aCtrl[] = {
2364- { "prng_save", SQLITE_TESTCTRL_PRNG_SAVE },
2365- { "prng_restore", SQLITE_TESTCTRL_PRNG_RESTORE },
2366- { "prng_reset", SQLITE_TESTCTRL_PRNG_RESET },
2367- { "bitvec_test", SQLITE_TESTCTRL_BITVEC_TEST },
2368- { "fault_install", SQLITE_TESTCTRL_FAULT_INSTALL },
2369- { "benign_malloc_hooks", SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS },
2370- { "pending_byte", SQLITE_TESTCTRL_PENDING_BYTE },
2371- { "assert", SQLITE_TESTCTRL_ASSERT },
2372- { "always", SQLITE_TESTCTRL_ALWAYS },
2373- { "reserve", SQLITE_TESTCTRL_RESERVE },
2374- { "optimizations", SQLITE_TESTCTRL_OPTIMIZATIONS },
2375- { "iskeyword", SQLITE_TESTCTRL_ISKEYWORD },
2376- { "scratchmalloc", SQLITE_TESTCTRL_SCRATCHMALLOC },
2377- };
2378- int testctrl = -1;
2379- int rc = 0;
2380- int i, n;
2381- open_db(p);
2382-
2383- /* convert testctrl text option to value. allow any unique prefix
2384- ** of the option name, or a numerical value. */
2385- n = strlen30(azArg[1]);
2386- for(i=0; i<(int)(sizeof(aCtrl)/sizeof(aCtrl[0])); i++){
2387- if( strncmp(azArg[1], aCtrl[i].zCtrlName, n)==0 ){
2388- if( testctrl<0 ){
2389- testctrl = aCtrl[i].ctrlCode;
2390- }else{
2391- fprintf(stderr, "ambiguous option name: \"%s\"\n", azArg[1]);
2392- testctrl = -1;
2393- break;
2394- }
2395- }
2396- }
2397- if( testctrl<0 ) testctrl = atoi(azArg[1]);
2398- if( (testctrl<SQLITE_TESTCTRL_FIRST) || (testctrl>SQLITE_TESTCTRL_LAST) ){
2399- fprintf(stderr,"Error: invalid testctrl option: %s\n", azArg[1]);
2400- }else{
2401- switch(testctrl){
2402-
2403- /* sqlite3_test_control(int, db, int) */
2404- case SQLITE_TESTCTRL_OPTIMIZATIONS:
2405- case SQLITE_TESTCTRL_RESERVE:
2406- if( nArg==3 ){
2407- int opt = (int)strtol(azArg[2], 0, 0);
2408- rc = sqlite3_test_control(testctrl, p->db, opt);
2409- printf("%d (0x%08x)\n", rc, rc);
2410- } else {
2411- fprintf(stderr,"Error: testctrl %s takes a single int option\n",
2412- azArg[1]);
2413- }
2414- break;
2415-
2416- /* sqlite3_test_control(int) */
2417- case SQLITE_TESTCTRL_PRNG_SAVE:
2418- case SQLITE_TESTCTRL_PRNG_RESTORE:
2419- case SQLITE_TESTCTRL_PRNG_RESET:
2420- if( nArg==2 ){
2421- rc = sqlite3_test_control(testctrl);
2422- printf("%d (0x%08x)\n", rc, rc);
2423- } else {
2424- fprintf(stderr,"Error: testctrl %s takes no options\n", azArg[1]);
2425- }
2426- break;
2427-
2428- /* sqlite3_test_control(int, uint) */
2429- case SQLITE_TESTCTRL_PENDING_BYTE:
2430- if( nArg==3 ){
2431- unsigned int opt = (unsigned int)atoi(azArg[2]);
2432- rc = sqlite3_test_control(testctrl, opt);
2433- printf("%d (0x%08x)\n", rc, rc);
2434- } else {
2435- fprintf(stderr,"Error: testctrl %s takes a single unsigned"
2436- " int option\n", azArg[1]);
2437- }
2438- break;
2439-
2440- /* sqlite3_test_control(int, int) */
2441- case SQLITE_TESTCTRL_ASSERT:
2442- case SQLITE_TESTCTRL_ALWAYS:
2443- if( nArg==3 ){
2444- int opt = atoi(azArg[2]);
2445- rc = sqlite3_test_control(testctrl, opt);
2446- printf("%d (0x%08x)\n", rc, rc);
2447- } else {
2448- fprintf(stderr,"Error: testctrl %s takes a single int option\n",
2449- azArg[1]);
2450- }
2451- break;
2452-
2453- /* sqlite3_test_control(int, char *) */
2454-#ifdef SQLITE_N_KEYWORD
2455- case SQLITE_TESTCTRL_ISKEYWORD:
2456- if( nArg==3 ){
2457- const char *opt = azArg[2];
2458- rc = sqlite3_test_control(testctrl, opt);
2459- printf("%d (0x%08x)\n", rc, rc);
2460- } else {
2461- fprintf(stderr,"Error: testctrl %s takes a single char * option\n",
2462- azArg[1]);
2463- }
2464- break;
2465-#endif
2466-
2467- case SQLITE_TESTCTRL_BITVEC_TEST:
2468- case SQLITE_TESTCTRL_FAULT_INSTALL:
2469- case SQLITE_TESTCTRL_BENIGN_MALLOC_HOOKS:
2470- case SQLITE_TESTCTRL_SCRATCHMALLOC:
2471- default:
2472- fprintf(stderr,"Error: CLI support for testctrl %s not implemented\n",
2473- azArg[1]);
2474- break;
2475- }
2476- }
2477- }else
2478-
2479- if( c=='t' && n>4 && strncmp(azArg[0], "timeout", n)==0 && nArg==2 ){
2480- open_db(p);
2481- sqlite3_busy_timeout(p->db, atoi(azArg[1]));
2482- }else
2483-
2484- if( HAS_TIMER && c=='t' && n>=5 && strncmp(azArg[0], "timer", n)==0
2485- && nArg==2
2486- ){
2487- enableTimer = booleanValue(azArg[1]);
2488- }else
2489-
2490- if( c=='t' && strncmp(azArg[0], "trace", n)==0 && nArg>1 ){
2491- open_db(p);
2492- output_file_close(p->traceOut);
2493- p->traceOut = output_file_open(azArg[1]);
2494-#if !defined(SQLITE_OMIT_TRACE) && !defined(SQLITE_OMIT_FLOATING_POINT)
2495- if( p->traceOut==0 ){
2496- sqlite3_trace(p->db, 0, 0);
2497- }else{
2498- sqlite3_trace(p->db, sql_trace_callback, p->traceOut);
2499- }
2500-#endif
2501- }else
2502-
2503- if( c=='v' && strncmp(azArg[0], "version", n)==0 ){
2504- printf("SQLite %s %s\n" /*extra-version-info*/,
2505- sqlite3_libversion(), sqlite3_sourceid());
2506- }else
2507-
2508- if( c=='v' && strncmp(azArg[0], "vfsname", n)==0 ){
2509- const char *zDbName = nArg==2 ? azArg[1] : "main";
2510- char *zVfsName = 0;
2511- if( p->db ){
2512- sqlite3_file_control(p->db, zDbName, SQLITE_FCNTL_VFSNAME, &zVfsName);
2513- if( zVfsName ){
2514- printf("%s\n", zVfsName);
2515- sqlite3_free(zVfsName);
2516- }
2517- }
2518- }else
2519-
2520-#if defined(SQLITE_DEBUG) && defined(SQLITE_ENABLE_WHERETRACE)
2521- if( c=='w' && strncmp(azArg[0], "wheretrace", n)==0 ){
2522- extern int sqlite3WhereTrace;
2523- sqlite3WhereTrace = atoi(azArg[1]);
2524- }else
2525-#endif
2526-
2527- if( c=='w' && strncmp(azArg[0], "width", n)==0 && nArg>1 ){
2528- int j;
2529- assert( nArg<=ArraySize(azArg) );
2530- for(j=1; j<nArg && j<ArraySize(p->colWidth); j++){
2531- p->colWidth[j-1] = atoi(azArg[j]);
2532- }
2533- }else
2534-
2535- {
2536- fprintf(stderr, "Error: unknown command or invalid arguments: "
2537- " \"%s\". Enter \".help\" for help\n", azArg[0]);
2538- rc = 1;
2539- }
2540-
2541- return rc;
2542-}
2543-
2544-/*
2545-** Return TRUE if a semicolon occurs anywhere in the first N characters
2546-** of string z[].
2547-*/
2548-static int _contains_semicolon(const char *z, int N){
2549- int i;
2550- for(i=0; i<N; i++){ if( z[i]==';' ) return 1; }
2551- return 0;
2552-}
2553-
2554-/*
2555-** Test to see if a line consists entirely of whitespace.
2556-*/
2557-static int _all_whitespace(const char *z){
2558- for(; *z; z++){
2559- if( IsSpace(z[0]) ) continue;
2560- if( *z=='/' && z[1]=='*' ){
2561- z += 2;
2562- while( *z && (*z!='*' || z[1]!='/') ){ z++; }
2563- if( *z==0 ) return 0;
2564- z++;
2565- continue;
2566- }
2567- if( *z=='-' && z[1]=='-' ){
2568- z += 2;
2569- while( *z && *z!='\n' ){ z++; }
2570- if( *z==0 ) return 1;
2571- continue;
2572- }
2573- return 0;
2574- }
2575- return 1;
2576-}
2577-
2578-/*
2579-** Return TRUE if the line typed in is an SQL command terminator other
2580-** than a semi-colon. The SQL Server style "go" command is understood
2581-** as is the Oracle "/".
2582-*/
2583-static int _is_command_terminator(const char *zLine){
2584- while( IsSpace(zLine[0]) ){ zLine++; };
2585- if( zLine[0]=='/' && _all_whitespace(&zLine[1]) ){
2586- return 1; /* Oracle */
2587- }
2588- if( ToLower(zLine[0])=='g' && ToLower(zLine[1])=='o'
2589- && _all_whitespace(&zLine[2]) ){
2590- return 1; /* SQL Server */
2591- }
2592- return 0;
2593-}
2594-
2595-/*
2596-** Return true if zSql is a complete SQL statement. Return false if it
2597-** ends in the middle of a string literal or C-style comment.
2598-*/
2599-static int _is_complete(char *zSql, int nSql){
2600- int rc;
2601- if( zSql==0 ) return 1;
2602- zSql[nSql] = ';';
2603- zSql[nSql+1] = 0;
2604- rc = sqlite3_complete(zSql);
2605- zSql[nSql] = 0;
2606- return rc;
2607-}
2608-
2609-/*
2610-** Read input from *in and process it. If *in==0 then input
2611-** is interactive - the user is typing it it. Otherwise, input
2612-** is coming from a file or device. A prompt is issued and history
2613-** is saved only if input is interactive. An interrupt signal will
2614-** cause this routine to exit immediately, unless input is interactive.
2615-**
2616-** Return the number of errors.
2617-*/
2618-static int process_input(struct callback_data *p, FILE *in){
2619- char *zLine = 0;
2620- char *zSql = 0;
2621- int nSql = 0;
2622- int nSqlPrior = 0;
2623- char *zErrMsg;
2624- int rc;
2625- int errCnt = 0;
2626- int lineno = 0;
2627- int startline = 0;
2628-
2629- while( errCnt==0 || !bail_on_error || (in==0 && stdin_is_interactive) ){
2630- fflush(p->out);
2631- free(zLine);
2632- zLine = one_input_line(zSql, in);
2633- if( zLine==0 ){
2634- /* End of input */
2635- if( stdin_is_interactive ) printf("\n");
2636- break;
2637- }
2638- if( seenInterrupt ){
2639- if( in!=0 ) break;
2640- seenInterrupt = 0;
2641- }
2642- lineno++;
2643- if( (zSql==0 || zSql[0]==0) && _all_whitespace(zLine) ) continue;
2644- if( zLine && zLine[0]=='.' && nSql==0 ){
2645- if( p->echoOn ) printf("%s\n", zLine);
2646- rc = do_meta_command(zLine, p);
2647- if( rc==2 ){ /* exit requested */
2648- break;
2649- }else if( rc ){
2650- errCnt++;
2651- }
2652- continue;
2653- }
2654- if( _is_command_terminator(zLine) && _is_complete(zSql, nSql) ){
2655- memcpy(zLine,";",2);
2656- }
2657- nSqlPrior = nSql;
2658- if( zSql==0 ){
2659- int i;
2660- for(i=0; zLine[i] && IsSpace(zLine[i]); i++){}
2661- if( zLine[i]!=0 ){
2662- nSql = strlen30(zLine);
2663- zSql = malloc( nSql+3 );
2664- if( zSql==0 ){
2665- fprintf(stderr, "Error: out of memory\n");
2666- exit(1);
2667- }
2668- memcpy(zSql, zLine, nSql+1);
2669- startline = lineno;
2670- }
2671- }else{
2672- int len = strlen30(zLine);
2673- zSql = realloc( zSql, nSql + len + 4 );
2674- if( zSql==0 ){
2675- fprintf(stderr,"Error: out of memory\n");
2676- exit(1);
2677- }
2678- zSql[nSql++] = '\n';
2679- memcpy(&zSql[nSql], zLine, len+1);
2680- nSql += len;
2681- }
2682- if( zSql && _contains_semicolon(&zSql[nSqlPrior], nSql-nSqlPrior)
2683- && sqlite3_complete(zSql) ){
2684- p->cnt = 0;
2685- open_db(p);
2686- BEGIN_TIMER;
2687- rc = shell_exec(p->db, zSql, shell_callback, p, &zErrMsg);
2688- END_TIMER;
2689- if( rc || zErrMsg ){
2690- char zPrefix[100];
2691- if( in!=0 || !stdin_is_interactive ){
2692- sqlite3_snprintf(sizeof(zPrefix), zPrefix,
2693- "Error: near line %d:", startline);
2694- }else{
2695- sqlite3_snprintf(sizeof(zPrefix), zPrefix, "Error:");
2696- }
2697- if( zErrMsg!=0 ){
2698- fprintf(stderr, "%s %s\n", zPrefix, zErrMsg);
2699- sqlite3_free(zErrMsg);
2700- zErrMsg = 0;
2701- }else{
2702- fprintf(stderr, "%s %s\n", zPrefix, sqlite3_errmsg(p->db));
2703- }
2704- errCnt++;
2705- }
2706- free(zSql);
2707- zSql = 0;
2708- nSql = 0;
2709- }
2710- }
2711- if( zSql ){
2712- if( !_all_whitespace(zSql) ){
2713- fprintf(stderr, "Error: incomplete SQL: %s\n", zSql);
2714- }
2715- free(zSql);
2716- }
2717- free(zLine);
2718- return errCnt>0;
2719-}
2720-
2721-/*
2722-** Return a pathname which is the user's home directory. A
2723-** 0 return indicates an error of some kind.
2724-*/
2725-static char *find_home_dir(void){
2726- static char *home_dir = NULL;
2727- if( home_dir ) return home_dir;
2728-
2729-#if !defined(_WIN32) && !defined(WIN32) && !defined(_WIN32_WCE) && !defined(__RTP__) && !defined(_WRS_KERNEL)
2730- {
2731- struct passwd *pwent;
2732- uid_t uid = getuid();
2733- if( (pwent=getpwuid(uid)) != NULL) {
2734- home_dir = pwent->pw_dir;
2735- }
2736- }
2737-#endif
2738-
2739-#if defined(_WIN32_WCE)
2740- /* Windows CE (arm-wince-mingw32ce-gcc) does not provide getenv()
2741- */
2742- home_dir = "/";
2743-#else
2744-
2745-#if defined(_WIN32) || defined(WIN32)
2746- if (!home_dir) {
2747- home_dir = getenv("USERPROFILE");
2748- }
2749-#endif
2750-
2751- if (!home_dir) {
2752- home_dir = getenv("HOME");
2753- }
2754-
2755-#if defined(_WIN32) || defined(WIN32)
2756- if (!home_dir) {
2757- char *zDrive, *zPath;
2758- int n;
2759- zDrive = getenv("HOMEDRIVE");
2760- zPath = getenv("HOMEPATH");
2761- if( zDrive && zPath ){
2762- n = strlen30(zDrive) + strlen30(zPath) + 1;
2763- home_dir = malloc( n );
2764- if( home_dir==0 ) return 0;
2765- sqlite3_snprintf(n, home_dir, "%s%s", zDrive, zPath);
2766- return home_dir;
2767- }
2768- home_dir = "c:\\";
2769- }
2770-#endif
2771-
2772-#endif /* !_WIN32_WCE */
2773-
2774- if( home_dir ){
2775- int n = strlen30(home_dir) + 1;
2776- char *z = malloc( n );
2777- if( z ) memcpy(z, home_dir, n);
2778- home_dir = z;
2779- }
2780-
2781- return home_dir;
2782-}
2783-
2784-/*
2785-** Read input from the file given by sqliterc_override. Or if that
2786-** parameter is NULL, take input from ~/.sqliterc
2787-**
2788-** Returns the number of errors.
2789-*/
2790-static int process_sqliterc(
2791- struct callback_data *p, /* Configuration data */
2792- const char *sqliterc_override /* Name of config file. NULL to use default */
2793-){
2794- char *home_dir = NULL;
2795- const char *sqliterc = sqliterc_override;
2796- char *zBuf = 0;
2797- FILE *in = NULL;
2798- int rc = 0;
2799-
2800- if (sqliterc == NULL) {
2801- home_dir = find_home_dir();
2802- if( home_dir==0 ){
2803-#if !defined(__RTP__) && !defined(_WRS_KERNEL)
2804- fprintf(stderr,"%s: Error: cannot locate your home directory\n", Argv0);
2805-#endif
2806- return 1;
2807- }
2808- sqlite3_initialize();
2809- zBuf = sqlite3_mprintf("%s/.sqliterc",home_dir);
2810- sqliterc = zBuf;
2811- }
2812- in = fopen(sqliterc,"rb");
2813- if( in ){
2814- if( stdin_is_interactive ){
2815- fprintf(stderr,"-- Loading resources from %s\n",sqliterc);
2816- }
2817- rc = process_input(p,in);
2818- fclose(in);
2819- }
2820- sqlite3_free(zBuf);
2821- return rc;
2822-}
2823-
2824-/*
2825-** Show available command line options
2826-*/
2827-static const char zOptions[] =
2828- " -bail stop after hitting an error\n"
2829- " -batch force batch I/O\n"
2830- " -column set output mode to 'column'\n"
2831- " -cmd COMMAND run \"COMMAND\" before reading stdin\n"
2832- " -csv set output mode to 'csv'\n"
2833- " -echo print commands before execution\n"
2834- " -init FILENAME read/process named file\n"
2835- " -[no]header turn headers on or off\n"
2836-#if defined(SQLITE_ENABLE_MEMSYS3) || defined(SQLITE_ENABLE_MEMSYS5)
2837- " -heap SIZE Size of heap for memsys3 or memsys5\n"
2838-#endif
2839- " -help show this message\n"
2840- " -html set output mode to HTML\n"
2841- " -interactive force interactive I/O\n"
2842- " -line set output mode to 'line'\n"
2843- " -list set output mode to 'list'\n"
2844-#ifdef SQLITE_ENABLE_MULTIPLEX
2845- " -multiplex enable the multiplexor VFS\n"
2846-#endif
2847- " -nullvalue TEXT set text string for NULL values. Default ''\n"
2848- " -separator SEP set output field separator. Default: '|'\n"
2849- " -stats print memory stats before each finalize\n"
2850- " -version show SQLite version\n"
2851- " -vfs NAME use NAME as the default VFS\n"
2852-#ifdef SQLITE_ENABLE_VFSTRACE
2853- " -vfstrace enable tracing of all VFS calls\n"
2854-#endif
2855-;
2856-static void usage(int showDetail){
2857- fprintf(stderr,
2858- "Usage: %s [OPTIONS] FILENAME [SQL]\n"
2859- "FILENAME is the name of an SQLite database. A new database is created\n"
2860- "if the file does not previously exist.\n", Argv0);
2861- if( showDetail ){
2862- fprintf(stderr, "OPTIONS include:\n%s", zOptions);
2863- }else{
2864- fprintf(stderr, "Use the -help option for additional information\n");
2865- }
2866- exit(1);
2867-}
2868-
2869-/*
2870-** Initialize the state information in data
2871-*/
2872-static void main_init(struct callback_data *data) {
2873- memset(data, 0, sizeof(*data));
2874- data->mode = MODE_List;
2875- memcpy(data->separator,"|", 2);
2876- data->showHeader = 0;
2877- sqlite3_config(SQLITE_CONFIG_URI, 1);
2878- sqlite3_config(SQLITE_CONFIG_LOG, shellLog, data);
2879- sqlite3_snprintf(sizeof(mainPrompt), mainPrompt,"sqlite> ");
2880- sqlite3_snprintf(sizeof(continuePrompt), continuePrompt," ...> ");
2881- sqlite3_config(SQLITE_CONFIG_SINGLETHREAD);
2882-}
2883-
2884-/*
2885-** Get the argument to an --option. Throw an error and die if no argument
2886-** is available.
2887-*/
2888-static char *cmdline_option_value(int argc, char **argv, int i){
2889- if( i==argc ){
2890- fprintf(stderr, "%s: Error: missing argument to %s\n",
2891- argv[0], argv[argc-1]);
2892- exit(1);
2893- }
2894- return argv[i];
2895-}
2896-
2897-int main(int argc, char **argv){
2898- char *zErrMsg = 0;
2899- struct callback_data data;
2900- const char *zInitFile = 0;
2901- char *zFirstCmd = 0;
2902- int i;
2903- int rc = 0;
2904-
2905- if( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)!=0 ){
2906- fprintf(stderr, "SQLite header and source version mismatch\n%s\n%s\n",
2907- sqlite3_sourceid(), SQLITE_SOURCE_ID);
2908- exit(1);
2909- }
2910- Argv0 = argv[0];
2911- main_init(&data);
2912- stdin_is_interactive = isatty(0);
2913-
2914- /* Make sure we have a valid signal handler early, before anything
2915- ** else is done.
2916- */
2917-#ifdef SIGINT
2918- signal(SIGINT, interrupt_handler);
2919-#endif
2920-
2921- /* Do an initial pass through the command-line argument to locate
2922- ** the name of the database file, the name of the initialization file,
2923- ** the size of the alternative malloc heap,
2924- ** and the first command to execute.
2925- */
2926- for(i=1; i<argc; i++){
2927- char *z;
2928- z = argv[i];
2929- if( z[0]!='-' ){
2930- if( data.zDbFilename==0 ){
2931- data.zDbFilename = z;
2932- continue;
2933- }
2934- if( zFirstCmd==0 ){
2935- zFirstCmd = z;
2936- continue;
2937- }
2938- fprintf(stderr,"%s: Error: too many options: \"%s\"\n", Argv0, argv[i]);
2939- fprintf(stderr,"Use -help for a list of options.\n");
2940- return 1;
2941- }
2942- if( z[1]=='-' ) z++;
2943- if( strcmp(z,"-separator")==0
2944- || strcmp(z,"-nullvalue")==0
2945- || strcmp(z,"-cmd")==0
2946- ){
2947- (void)cmdline_option_value(argc, argv, ++i);
2948- }else if( strcmp(z,"-init")==0 ){
2949- zInitFile = cmdline_option_value(argc, argv, ++i);
2950- }else if( strcmp(z,"-batch")==0 ){
2951- /* Need to check for batch mode here to so we can avoid printing
2952- ** informational messages (like from process_sqliterc) before
2953- ** we do the actual processing of arguments later in a second pass.
2954- */
2955- stdin_is_interactive = 0;
2956- }else if( strcmp(z,"-heap")==0 ){
2957-#if defined(SQLITE_ENABLE_MEMSYS3) || defined(SQLITE_ENABLE_MEMSYS5)
2958- int j, c;
2959- const char *zSize;
2960- sqlite3_int64 szHeap;
2961-
2962- zSize = cmdline_option_value(argc, argv, ++i);
2963- szHeap = atoi(zSize);
2964- for(j=0; (c = zSize[j])!=0; j++){
2965- if( c=='M' ){ szHeap *= 1000000; break; }
2966- if( c=='K' ){ szHeap *= 1000; break; }
2967- if( c=='G' ){ szHeap *= 1000000000; break; }
2968- }
2969- if( szHeap>0x7fff0000 ) szHeap = 0x7fff0000;
2970- sqlite3_config(SQLITE_CONFIG_HEAP, malloc((int)szHeap), (int)szHeap, 64);
2971-#endif
2972-#ifdef SQLITE_ENABLE_VFSTRACE
2973- }else if( strcmp(z,"-vfstrace")==0 ){
2974- extern int vfstrace_register(
2975- const char *zTraceName,
2976- const char *zOldVfsName,
2977- int (*xOut)(const char*,void*),
2978- void *pOutArg,
2979- int makeDefault
2980- );
2981- vfstrace_register("trace",0,(int(*)(const char*,void*))fputs,stderr,1);
2982-#endif
2983-#ifdef SQLITE_ENABLE_MULTIPLEX
2984- }else if( strcmp(z,"-multiplex")==0 ){
2985- extern int sqlite3_multiple_initialize(const char*,int);
2986- sqlite3_multiplex_initialize(0, 1);
2987-#endif
2988- }else if( strcmp(z,"-vfs")==0 ){
2989- sqlite3_vfs *pVfs = sqlite3_vfs_find(cmdline_option_value(argc,argv,++i));
2990- if( pVfs ){
2991- sqlite3_vfs_register(pVfs, 1);
2992- }else{
2993- fprintf(stderr, "no such VFS: \"%s\"\n", argv[i]);
2994- exit(1);
2995- }
2996- }
2997- }
2998- if( data.zDbFilename==0 ){
2999-#ifndef SQLITE_OMIT_MEMORYDB
3000- data.zDbFilename = ":memory:";
3001-#else
3002- fprintf(stderr,"%s: Error: no database filename specified\n", Argv0);
3003- return 1;
3004-#endif
3005- }
3006- data.out = stdout;
3007-
3008- /* Go ahead and open the database file if it already exists. If the
3009- ** file does not exist, delay opening it. This prevents empty database
3010- ** files from being created if a user mistypes the database name argument
3011- ** to the sqlite command-line tool.
3012- */
3013- if( access(data.zDbFilename, 0)==0 ){
3014- open_db(&data);
3015- }
3016-
3017- /* Process the initialization file if there is one. If no -init option
3018- ** is given on the command line, look for a file named ~/.sqliterc and
3019- ** try to process it.
3020- */
3021- rc = process_sqliterc(&data,zInitFile);
3022- if( rc>0 ){
3023- return rc;
3024- }
3025-
3026- /* Make a second pass through the command-line argument and set
3027- ** options. This second pass is delayed until after the initialization
3028- ** file is processed so that the command-line arguments will override
3029- ** settings in the initialization file.
3030- */
3031- for(i=1; i<argc; i++){
3032- char *z = argv[i];
3033- if( z[0]!='-' ) continue;
3034- if( z[1]=='-' ){ z++; }
3035- if( strcmp(z,"-init")==0 ){
3036- i++;
3037- }else if( strcmp(z,"-html")==0 ){
3038- data.mode = MODE_Html;
3039- }else if( strcmp(z,"-list")==0 ){
3040- data.mode = MODE_List;
3041- }else if( strcmp(z,"-line")==0 ){
3042- data.mode = MODE_Line;
3043- }else if( strcmp(z,"-column")==0 ){
3044- data.mode = MODE_Column;
3045- }else if( strcmp(z,"-csv")==0 ){
3046- data.mode = MODE_Csv;
3047- memcpy(data.separator,",",2);
3048- }else if( strcmp(z,"-separator")==0 ){
3049- sqlite3_snprintf(sizeof(data.separator), data.separator,
3050- "%s",cmdline_option_value(argc,argv,++i));
3051- }else if( strcmp(z,"-nullvalue")==0 ){
3052- sqlite3_snprintf(sizeof(data.nullvalue), data.nullvalue,
3053- "%s",cmdline_option_value(argc,argv,++i));
3054- }else if( strcmp(z,"-header")==0 ){
3055- data.showHeader = 1;
3056- }else if( strcmp(z,"-noheader")==0 ){
3057- data.showHeader = 0;
3058- }else if( strcmp(z,"-echo")==0 ){
3059- data.echoOn = 1;
3060- }else if( strcmp(z,"-stats")==0 ){
3061- data.statsOn = 1;
3062- }else if( strcmp(z,"-bail")==0 ){
3063- bail_on_error = 1;
3064- }else if( strcmp(z,"-version")==0 ){
3065- printf("%s %s\n", sqlite3_libversion(), sqlite3_sourceid());
3066- return 0;
3067- }else if( strcmp(z,"-interactive")==0 ){
3068- stdin_is_interactive = 1;
3069- }else if( strcmp(z,"-batch")==0 ){
3070- stdin_is_interactive = 0;
3071- }else if( strcmp(z,"-heap")==0 ){
3072- i++;
3073- }else if( strcmp(z,"-vfs")==0 ){
3074- i++;
3075-#ifdef SQLITE_ENABLE_VFSTRACE
3076- }else if( strcmp(z,"-vfstrace")==0 ){
3077- i++;
3078-#endif
3079-#ifdef SQLITE_ENABLE_MULTIPLEX
3080- }else if( strcmp(z,"-multiplex")==0 ){
3081- i++;
3082-#endif
3083- }else if( strcmp(z,"-help")==0 ){
3084- usage(1);
3085- }else if( strcmp(z,"-cmd")==0 ){
3086- if( i==argc-1 ) break;
3087- z = cmdline_option_value(argc,argv,++i);
3088- if( z[0]=='.' ){
3089- rc = do_meta_command(z, &data);
3090- if( rc && bail_on_error ) return rc;
3091- }else{
3092- open_db(&data);
3093- rc = shell_exec(data.db, z, shell_callback, &data, &zErrMsg);
3094- if( zErrMsg!=0 ){
3095- fprintf(stderr,"Error: %s\n", zErrMsg);
3096- if( bail_on_error ) return rc!=0 ? rc : 1;
3097- }else if( rc!=0 ){
3098- fprintf(stderr,"Error: unable to process SQL \"%s\"\n", z);
3099- if( bail_on_error ) return rc;
3100- }
3101- }
3102- }else{
3103- fprintf(stderr,"%s: Error: unknown option: %s\n", Argv0, z);
3104- fprintf(stderr,"Use -help for a list of options.\n");
3105- return 1;
3106- }
3107- }
3108-
3109- if( zFirstCmd ){
3110- /* Run just the command that follows the database name
3111- */
3112- if( zFirstCmd[0]=='.' ){
3113- rc = do_meta_command(zFirstCmd, &data);
3114- }else{
3115- open_db(&data);
3116- rc = shell_exec(data.db, zFirstCmd, shell_callback, &data, &zErrMsg);
3117- if( zErrMsg!=0 ){
3118- fprintf(stderr,"Error: %s\n", zErrMsg);
3119- return rc!=0 ? rc : 1;
3120- }else if( rc!=0 ){
3121- fprintf(stderr,"Error: unable to process SQL \"%s\"\n", zFirstCmd);
3122- return rc;
3123- }
3124- }
3125- }else{
3126- /* Run commands received from standard input
3127- */
3128- if( stdin_is_interactive ){
3129- char *zHome;
3130- char *zHistory = 0;
3131- int nHistory;
3132- printf(
3133- "SQLite version %s %.19s\n" /*extra-version-info*/
3134- "Enter \".help\" for instructions\n"
3135- "Enter SQL statements terminated with a \";\"\n",
3136- sqlite3_libversion(), sqlite3_sourceid()
3137- );
3138- zHome = find_home_dir();
3139- if( zHome ){
3140- nHistory = strlen30(zHome) + 20;
3141- if( (zHistory = malloc(nHistory))!=0 ){
3142- sqlite3_snprintf(nHistory, zHistory,"%s/.sqlite_history", zHome);
3143- }
3144- }
3145-#if defined(HAVE_READLINE) && HAVE_READLINE==1
3146- if( zHistory ) read_history(zHistory);
3147-#endif
3148- rc = process_input(&data, 0);
3149- if( zHistory ){
3150- stifle_history(100);
3151- write_history(zHistory);
3152- free(zHistory);
3153- }
3154- }else{
3155- rc = process_input(&data, stdin);
3156- }
3157- }
3158- set_table_name(&data, 0);
3159- if( data.db ){
3160- sqlite3_close(data.db);
3161- }
3162- return rc;
3163-}
--- a/Superuser/jni/sqlite3/sqlite3.c
+++ /dev/null
@@ -1,137414 +0,0 @@
1-/******************************************************************************
2-** This file is an amalgamation of many separate C source files from SQLite
3-** version 3.7.15.2. 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 SQLITE_CORE 1
21-#define SQLITE_AMALGAMATION 1
22-#ifndef SQLITE_PRIVATE
23-# define SQLITE_PRIVATE static
24-#endif
25-#ifndef SQLITE_API
26-# define SQLITE_API
27-#endif
28-/************** Begin file sqliteInt.h ***************************************/
29-/*
30-** 2001 September 15
31-**
32-** The author disclaims copyright to this source code. In place of
33-** a legal notice, here is a blessing:
34-**
35-** May you do good and not evil.
36-** May you find forgiveness for yourself and forgive others.
37-** May you share freely, never taking more than you give.
38-**
39-*************************************************************************
40-** Internal interface definitions for SQLite.
41-**
42-*/
43-#ifndef _SQLITEINT_H_
44-#define _SQLITEINT_H_
45-
46-/*
47-** These #defines should enable >2GB file support on POSIX if the
48-** underlying operating system supports it. If the OS lacks
49-** large file support, or if the OS is windows, these should be no-ops.
50-**
51-** Ticket #2739: The _LARGEFILE_SOURCE macro must appear before any
52-** system #includes. Hence, this block of code must be the very first
53-** code in all source files.
54-**
55-** Large file support can be disabled using the -DSQLITE_DISABLE_LFS switch
56-** on the compiler command line. This is necessary if you are compiling
57-** on a recent machine (ex: Red Hat 7.2) but you want your code to work
58-** on an older machine (ex: Red Hat 6.0). If you compile on Red Hat 7.2
59-** without this option, LFS is enable. But LFS does not exist in the kernel
60-** in Red Hat 6.0, so the code won't work. Hence, for maximum binary
61-** portability you should omit LFS.
62-**
63-** Similar is true for Mac OS X. LFS is only supported on Mac OS X 9 and later.
64-*/
65-#ifndef SQLITE_DISABLE_LFS
66-# define _LARGE_FILE 1
67-# ifndef _FILE_OFFSET_BITS
68-# define _FILE_OFFSET_BITS 64
69-# endif
70-# define _LARGEFILE_SOURCE 1
71-#endif
72-
73-/*
74-** Include the configuration header output by 'configure' if we're using the
75-** autoconf-based build
76-*/
77-#ifdef _HAVE_SQLITE_CONFIG_H
78-#include "config.h"
79-#endif
80-
81-/************** Include sqliteLimit.h in the middle of sqliteInt.h ***********/
82-/************** Begin file sqliteLimit.h *************************************/
83-/*
84-** 2007 May 7
85-**
86-** The author disclaims copyright to this source code. In place of
87-** a legal notice, here is a blessing:
88-**
89-** May you do good and not evil.
90-** May you find forgiveness for yourself and forgive others.
91-** May you share freely, never taking more than you give.
92-**
93-*************************************************************************
94-**
95-** This file defines various limits of what SQLite can process.
96-*/
97-
98-/*
99-** The maximum length of a TEXT or BLOB in bytes. This also
100-** limits the size of a row in a table or index.
101-**
102-** The hard limit is the ability of a 32-bit signed integer
103-** to count the size: 2^31-1 or 2147483647.
104-*/
105-#ifndef SQLITE_MAX_LENGTH
106-# define SQLITE_MAX_LENGTH 1000000000
107-#endif
108-
109-/*
110-** This is the maximum number of
111-**
112-** * Columns in a table
113-** * Columns in an index
114-** * Columns in a view
115-** * Terms in the SET clause of an UPDATE statement
116-** * Terms in the result set of a SELECT statement
117-** * Terms in the GROUP BY or ORDER BY clauses of a SELECT statement.
118-** * Terms in the VALUES clause of an INSERT statement
119-**
120-** The hard upper limit here is 32676. Most database people will
121-** tell you that in a well-normalized database, you usually should
122-** not have more than a dozen or so columns in any table. And if
123-** that is the case, there is no point in having more than a few
124-** dozen values in any of the other situations described above.
125-*/
126-#ifndef SQLITE_MAX_COLUMN
127-# define SQLITE_MAX_COLUMN 2000
128-#endif
129-
130-/*
131-** The maximum length of a single SQL statement in bytes.
132-**
133-** It used to be the case that setting this value to zero would
134-** turn the limit off. That is no longer true. It is not possible
135-** to turn this limit off.
136-*/
137-#ifndef SQLITE_MAX_SQL_LENGTH
138-# define SQLITE_MAX_SQL_LENGTH 1000000000
139-#endif
140-
141-/*
142-** The maximum depth of an expression tree. This is limited to
143-** some extent by SQLITE_MAX_SQL_LENGTH. But sometime you might
144-** want to place more severe limits on the complexity of an
145-** expression.
146-**
147-** A value of 0 used to mean that the limit was not enforced.
148-** But that is no longer true. The limit is now strictly enforced
149-** at all times.
150-*/
151-#ifndef SQLITE_MAX_EXPR_DEPTH
152-# define SQLITE_MAX_EXPR_DEPTH 1000
153-#endif
154-
155-/*
156-** The maximum number of terms in a compound SELECT statement.
157-** The code generator for compound SELECT statements does one
158-** level of recursion for each term. A stack overflow can result
159-** if the number of terms is too large. In practice, most SQL
160-** never has more than 3 or 4 terms. Use a value of 0 to disable
161-** any limit on the number of terms in a compount SELECT.
162-*/
163-#ifndef SQLITE_MAX_COMPOUND_SELECT
164-# define SQLITE_MAX_COMPOUND_SELECT 500
165-#endif
166-
167-/*
168-** The maximum number of opcodes in a VDBE program.
169-** Not currently enforced.
170-*/
171-#ifndef SQLITE_MAX_VDBE_OP
172-# define SQLITE_MAX_VDBE_OP 25000
173-#endif
174-
175-/*
176-** The maximum number of arguments to an SQL function.
177-*/
178-#ifndef SQLITE_MAX_FUNCTION_ARG
179-# define SQLITE_MAX_FUNCTION_ARG 127
180-#endif
181-
182-/*
183-** The maximum number of in-memory pages to use for the main database
184-** table and for temporary tables. The SQLITE_DEFAULT_CACHE_SIZE
185-*/
186-#ifndef SQLITE_DEFAULT_CACHE_SIZE
187-# define SQLITE_DEFAULT_CACHE_SIZE 2000
188-#endif
189-#ifndef SQLITE_DEFAULT_TEMP_CACHE_SIZE
190-# define SQLITE_DEFAULT_TEMP_CACHE_SIZE 500
191-#endif
192-
193-/*
194-** The default number of frames to accumulate in the log file before
195-** checkpointing the database in WAL mode.
196-*/
197-#ifndef SQLITE_DEFAULT_WAL_AUTOCHECKPOINT
198-# define SQLITE_DEFAULT_WAL_AUTOCHECKPOINT 1000
199-#endif
200-
201-/*
202-** The maximum number of attached databases. This must be between 0
203-** and 62. The upper bound on 62 is because a 64-bit integer bitmap
204-** is used internally to track attached databases.
205-*/
206-#ifndef SQLITE_MAX_ATTACHED
207-# define SQLITE_MAX_ATTACHED 10
208-#endif
209-
210-
211-/*
212-** The maximum value of a ?nnn wildcard that the parser will accept.
213-*/
214-#ifndef SQLITE_MAX_VARIABLE_NUMBER
215-# define SQLITE_MAX_VARIABLE_NUMBER 999
216-#endif
217-
218-/* Maximum page size. The upper bound on this value is 65536. This a limit
219-** imposed by the use of 16-bit offsets within each page.
220-**
221-** Earlier versions of SQLite allowed the user to change this value at
222-** compile time. This is no longer permitted, on the grounds that it creates
223-** a library that is technically incompatible with an SQLite library
224-** compiled with a different limit. If a process operating on a database
225-** with a page-size of 65536 bytes crashes, then an instance of SQLite
226-** compiled with the default page-size limit will not be able to rollback
227-** the aborted transaction. This could lead to database corruption.
228-*/
229-#ifdef SQLITE_MAX_PAGE_SIZE
230-# undef SQLITE_MAX_PAGE_SIZE
231-#endif
232-#define SQLITE_MAX_PAGE_SIZE 65536
233-
234-
235-/*
236-** The default size of a database page.
237-*/
238-#ifndef SQLITE_DEFAULT_PAGE_SIZE
239-# define SQLITE_DEFAULT_PAGE_SIZE 1024
240-#endif
241-#if SQLITE_DEFAULT_PAGE_SIZE>SQLITE_MAX_PAGE_SIZE
242-# undef SQLITE_DEFAULT_PAGE_SIZE
243-# define SQLITE_DEFAULT_PAGE_SIZE SQLITE_MAX_PAGE_SIZE
244-#endif
245-
246-/*
247-** Ordinarily, if no value is explicitly provided, SQLite creates databases
248-** with page size SQLITE_DEFAULT_PAGE_SIZE. However, based on certain
249-** device characteristics (sector-size and atomic write() support),
250-** SQLite may choose a larger value. This constant is the maximum value
251-** SQLite will choose on its own.
252-*/
253-#ifndef SQLITE_MAX_DEFAULT_PAGE_SIZE
254-# define SQLITE_MAX_DEFAULT_PAGE_SIZE 8192
255-#endif
256-#if SQLITE_MAX_DEFAULT_PAGE_SIZE>SQLITE_MAX_PAGE_SIZE
257-# undef SQLITE_MAX_DEFAULT_PAGE_SIZE
258-# define SQLITE_MAX_DEFAULT_PAGE_SIZE SQLITE_MAX_PAGE_SIZE
259-#endif
260-
261-
262-/*
263-** Maximum number of pages in one database file.
264-**
265-** This is really just the default value for the max_page_count pragma.
266-** This value can be lowered (or raised) at run-time using that the
267-** max_page_count macro.
268-*/
269-#ifndef SQLITE_MAX_PAGE_COUNT
270-# define SQLITE_MAX_PAGE_COUNT 1073741823
271-#endif
272-
273-/*
274-** Maximum length (in bytes) of the pattern in a LIKE or GLOB
275-** operator.
276-*/
277-#ifndef SQLITE_MAX_LIKE_PATTERN_LENGTH
278-# define SQLITE_MAX_LIKE_PATTERN_LENGTH 50000
279-#endif
280-
281-/*
282-** Maximum depth of recursion for triggers.
283-**
284-** A value of 1 means that a trigger program will not be able to itself
285-** fire any triggers. A value of 0 means that no trigger programs at all
286-** may be executed.
287-*/
288-#ifndef SQLITE_MAX_TRIGGER_DEPTH
289-# define SQLITE_MAX_TRIGGER_DEPTH 1000
290-#endif
291-
292-/************** End of sqliteLimit.h *****************************************/
293-/************** Continuing where we left off in sqliteInt.h ******************/
294-
295-/* Disable nuisance warnings on Borland compilers */
296-#if defined(__BORLANDC__)
297-#pragma warn -rch /* unreachable code */
298-#pragma warn -ccc /* Condition is always true or false */
299-#pragma warn -aus /* Assigned value is never used */
300-#pragma warn -csu /* Comparing signed and unsigned */
301-#pragma warn -spa /* Suspicious pointer arithmetic */
302-#endif
303-
304-/* Needed for various definitions... */
305-#ifndef _GNU_SOURCE
306-# define _GNU_SOURCE
307-#endif
308-
309-/*
310-** Include standard header files as necessary
311-*/
312-#ifdef HAVE_STDINT_H
313-#include <stdint.h>
314-#endif
315-#ifdef HAVE_INTTYPES_H
316-#include <inttypes.h>
317-#endif
318-
319-/*
320-** The following macros are used to cast pointers to integers and
321-** integers to pointers. The way you do this varies from one compiler
322-** to the next, so we have developed the following set of #if statements
323-** to generate appropriate macros for a wide range of compilers.
324-**
325-** The correct "ANSI" way to do this is to use the intptr_t type.
326-** Unfortunately, that typedef is not available on all compilers, or
327-** if it is available, it requires an #include of specific headers
328-** that vary from one machine to the next.
329-**
330-** Ticket #3860: The llvm-gcc-4.2 compiler from Apple chokes on
331-** the ((void*)&((char*)0)[X]) construct. But MSVC chokes on ((void*)(X)).
332-** So we have to define the macros in different ways depending on the
333-** compiler.
334-*/
335-#if defined(__PTRDIFF_TYPE__) /* This case should work for GCC */
336-# define SQLITE_INT_TO_PTR(X) ((void*)(__PTRDIFF_TYPE__)(X))
337-# define SQLITE_PTR_TO_INT(X) ((int)(__PTRDIFF_TYPE__)(X))
338-#elif !defined(__GNUC__) /* Works for compilers other than LLVM */
339-# define SQLITE_INT_TO_PTR(X) ((void*)&((char*)0)[X])
340-# define SQLITE_PTR_TO_INT(X) ((int)(((char*)X)-(char*)0))
341-#elif defined(HAVE_STDINT_H) /* Use this case if we have ANSI headers */
342-# define SQLITE_INT_TO_PTR(X) ((void*)(intptr_t)(X))
343-# define SQLITE_PTR_TO_INT(X) ((int)(intptr_t)(X))
344-#else /* Generates a warning - but it always works */
345-# define SQLITE_INT_TO_PTR(X) ((void*)(X))
346-# define SQLITE_PTR_TO_INT(X) ((int)(X))
347-#endif
348-
349-/*
350-** The SQLITE_THREADSAFE macro must be defined as 0, 1, or 2.
351-** 0 means mutexes are permanently disable and the library is never
352-** threadsafe. 1 means the library is serialized which is the highest
353-** level of threadsafety. 2 means the libary is multithreaded - multiple
354-** threads can use SQLite as long as no two threads try to use the same
355-** database connection at the same time.
356-**
357-** Older versions of SQLite used an optional THREADSAFE macro.
358-** We support that for legacy.
359-*/
360-#if !defined(SQLITE_THREADSAFE)
361-#if defined(THREADSAFE)
362-# define SQLITE_THREADSAFE THREADSAFE
363-#else
364-# define SQLITE_THREADSAFE 1 /* IMP: R-07272-22309 */
365-#endif
366-#endif
367-
368-/*
369-** Powersafe overwrite is on by default. But can be turned off using
370-** the -DSQLITE_POWERSAFE_OVERWRITE=0 command-line option.
371-*/
372-#ifndef SQLITE_POWERSAFE_OVERWRITE
373-# define SQLITE_POWERSAFE_OVERWRITE 1
374-#endif
375-
376-/*
377-** The SQLITE_DEFAULT_MEMSTATUS macro must be defined as either 0 or 1.
378-** It determines whether or not the features related to
379-** SQLITE_CONFIG_MEMSTATUS are available by default or not. This value can
380-** be overridden at runtime using the sqlite3_config() API.
381-*/
382-#if !defined(SQLITE_DEFAULT_MEMSTATUS)
383-# define SQLITE_DEFAULT_MEMSTATUS 1
384-#endif
385-
386-/*
387-** Exactly one of the following macros must be defined in order to
388-** specify which memory allocation subsystem to use.
389-**
390-** SQLITE_SYSTEM_MALLOC // Use normal system malloc()
391-** SQLITE_WIN32_MALLOC // Use Win32 native heap API
392-** SQLITE_ZERO_MALLOC // Use a stub allocator that always fails
393-** SQLITE_MEMDEBUG // Debugging version of system malloc()
394-**
395-** On Windows, if the SQLITE_WIN32_MALLOC_VALIDATE macro is defined and the
396-** assert() macro is enabled, each call into the Win32 native heap subsystem
397-** will cause HeapValidate to be called. If heap validation should fail, an
398-** assertion will be triggered.
399-**
400-** (Historical note: There used to be several other options, but we've
401-** pared it down to just these three.)
402-**
403-** If none of the above are defined, then set SQLITE_SYSTEM_MALLOC as
404-** the default.
405-*/
406-#if defined(SQLITE_SYSTEM_MALLOC) \
407- + defined(SQLITE_WIN32_MALLOC) \
408- + defined(SQLITE_ZERO_MALLOC) \
409- + defined(SQLITE_MEMDEBUG)>1
410-# error "Two or more of the following compile-time configuration options\
411- are defined but at most one is allowed:\
412- SQLITE_SYSTEM_MALLOC, SQLITE_WIN32_MALLOC, SQLITE_MEMDEBUG,\
413- SQLITE_ZERO_MALLOC"
414-#endif
415-#if defined(SQLITE_SYSTEM_MALLOC) \
416- + defined(SQLITE_WIN32_MALLOC) \
417- + defined(SQLITE_ZERO_MALLOC) \
418- + defined(SQLITE_MEMDEBUG)==0
419-# define SQLITE_SYSTEM_MALLOC 1
420-#endif
421-
422-/*
423-** If SQLITE_MALLOC_SOFT_LIMIT is not zero, then try to keep the
424-** sizes of memory allocations below this value where possible.
425-*/
426-#if !defined(SQLITE_MALLOC_SOFT_LIMIT)
427-# define SQLITE_MALLOC_SOFT_LIMIT 1024
428-#endif
429-
430-/*
431-** We need to define _XOPEN_SOURCE as follows in order to enable
432-** recursive mutexes on most Unix systems. But Mac OS X is different.
433-** The _XOPEN_SOURCE define causes problems for Mac OS X we are told,
434-** so it is omitted there. See ticket #2673.
435-**
436-** Later we learn that _XOPEN_SOURCE is poorly or incorrectly
437-** implemented on some systems. So we avoid defining it at all
438-** if it is already defined or if it is unneeded because we are
439-** not doing a threadsafe build. Ticket #2681.
440-**
441-** See also ticket #2741.
442-*/
443-#if !defined(_XOPEN_SOURCE) && !defined(__DARWIN__) && !defined(__APPLE__) && SQLITE_THREADSAFE
444-# define _XOPEN_SOURCE 500 /* Needed to enable pthread recursive mutexes */
445-#endif
446-
447-/*
448-** The TCL headers are only needed when compiling the TCL bindings.
449-*/
450-#if defined(SQLITE_TCL) || defined(TCLSH)
451-# include <tcl.h>
452-#endif
453-
454-/*
455-** NDEBUG and SQLITE_DEBUG are opposites. It should always be true that
456-** defined(NDEBUG)==!defined(SQLITE_DEBUG). If this is not currently true,
457-** make it true by defining or undefining NDEBUG.
458-**
459-** Setting NDEBUG makes the code smaller and run faster by disabling the
460-** number assert() statements in the code. So we want the default action
461-** to be for NDEBUG to be set and NDEBUG to be undefined only if SQLITE_DEBUG
462-** is set. Thus NDEBUG becomes an opt-in rather than an opt-out
463-** feature.
464-*/
465-#if !defined(NDEBUG) && !defined(SQLITE_DEBUG)
466-# define NDEBUG 1
467-#endif
468-#if defined(NDEBUG) && defined(SQLITE_DEBUG)
469-# undef NDEBUG
470-#endif
471-
472-/*
473-** The testcase() macro is used to aid in coverage testing. When
474-** doing coverage testing, the condition inside the argument to
475-** testcase() must be evaluated both true and false in order to
476-** get full branch coverage. The testcase() macro is inserted
477-** to help ensure adequate test coverage in places where simple
478-** condition/decision coverage is inadequate. For example, testcase()
479-** can be used to make sure boundary values are tested. For
480-** bitmask tests, testcase() can be used to make sure each bit
481-** is significant and used at least once. On switch statements
482-** where multiple cases go to the same block of code, testcase()
483-** can insure that all cases are evaluated.
484-**
485-*/
486-#ifdef SQLITE_COVERAGE_TEST
487-SQLITE_PRIVATE void sqlite3Coverage(int);
488-# define testcase(X) if( X ){ sqlite3Coverage(__LINE__); }
489-#else
490-# define testcase(X)
491-#endif
492-
493-/*
494-** The TESTONLY macro is used to enclose variable declarations or
495-** other bits of code that are needed to support the arguments
496-** within testcase() and assert() macros.
497-*/
498-#if !defined(NDEBUG) || defined(SQLITE_COVERAGE_TEST)
499-# define TESTONLY(X) X
500-#else
501-# define TESTONLY(X)
502-#endif
503-
504-/*
505-** Sometimes we need a small amount of code such as a variable initialization
506-** to setup for a later assert() statement. We do not want this code to
507-** appear when assert() is disabled. The following macro is therefore
508-** used to contain that setup code. The "VVA" acronym stands for
509-** "Verification, Validation, and Accreditation". In other words, the
510-** code within VVA_ONLY() will only run during verification processes.
511-*/
512-#ifndef NDEBUG
513-# define VVA_ONLY(X) X
514-#else
515-# define VVA_ONLY(X)
516-#endif
517-
518-/*
519-** The ALWAYS and NEVER macros surround boolean expressions which
520-** are intended to always be true or false, respectively. Such
521-** expressions could be omitted from the code completely. But they
522-** are included in a few cases in order to enhance the resilience
523-** of SQLite to unexpected behavior - to make the code "self-healing"
524-** or "ductile" rather than being "brittle" and crashing at the first
525-** hint of unplanned behavior.
526-**
527-** In other words, ALWAYS and NEVER are added for defensive code.
528-**
529-** When doing coverage testing ALWAYS and NEVER are hard-coded to
530-** be true and false so that the unreachable code then specify will
531-** not be counted as untested code.
532-*/
533-#if defined(SQLITE_COVERAGE_TEST)
534-# define ALWAYS(X) (1)
535-# define NEVER(X) (0)
536-#elif !defined(NDEBUG)
537-# define ALWAYS(X) ((X)?1:(assert(0),0))
538-# define NEVER(X) ((X)?(assert(0),1):0)
539-#else
540-# define ALWAYS(X) (X)
541-# define NEVER(X) (X)
542-#endif
543-
544-/*
545-** Return true (non-zero) if the input is a integer that is too large
546-** to fit in 32-bits. This macro is used inside of various testcase()
547-** macros to verify that we have tested SQLite for large-file support.
548-*/
549-#define IS_BIG_INT(X) (((X)&~(i64)0xffffffff)!=0)
550-
551-/*
552-** The macro unlikely() is a hint that surrounds a boolean
553-** expression that is usually false. Macro likely() surrounds
554-** a boolean expression that is usually true. GCC is able to
555-** use these hints to generate better code, sometimes.
556-*/
557-#if defined(__GNUC__) && 0
558-# define likely(X) __builtin_expect((X),1)
559-# define unlikely(X) __builtin_expect((X),0)
560-#else
561-# define likely(X) !!(X)
562-# define unlikely(X) !!(X)
563-#endif
564-
565-/************** Include sqlite3.h in the middle of sqliteInt.h ***************/
566-/************** Begin file sqlite3.h *****************************************/
567-/*
568-** 2001 September 15
569-**
570-** The author disclaims copyright to this source code. In place of
571-** a legal notice, here is a blessing:
572-**
573-** May you do good and not evil.
574-** May you find forgiveness for yourself and forgive others.
575-** May you share freely, never taking more than you give.
576-**
577-*************************************************************************
578-** This header file defines the interface that the SQLite library
579-** presents to client programs. If a C-function, structure, datatype,
580-** or constant definition does not appear in this file, then it is
581-** not a published API of SQLite, is subject to change without
582-** notice, and should not be referenced by programs that use SQLite.
583-**
584-** Some of the definitions that are in this file are marked as
585-** "experimental". Experimental interfaces are normally new
586-** features recently added to SQLite. We do not anticipate changes
587-** to experimental interfaces but reserve the right to make minor changes
588-** if experience from use "in the wild" suggest such changes are prudent.
589-**
590-** The official C-language API documentation for SQLite is derived
591-** from comments in this file. This file is the authoritative source
592-** on how SQLite interfaces are suppose to operate.
593-**
594-** The name of this file under configuration management is "sqlite.h.in".
595-** The makefile makes some minor changes to this file (such as inserting
596-** the version number) and changes its name to "sqlite3.h" as
597-** part of the build process.
598-*/
599-#ifndef _SQLITE3_H_
600-#define _SQLITE3_H_
601-#include <stdarg.h> /* Needed for the definition of va_list */
602-
603-/*
604-** Make sure we can call this stuff from C++.
605-*/
606-#if 0
607-extern "C" {
608-#endif
609-
610-
611-/*
612-** Add the ability to override 'extern'
613-*/
614-#ifndef SQLITE_EXTERN
615-# define SQLITE_EXTERN extern
616-#endif
617-
618-#ifndef SQLITE_API
619-# define SQLITE_API
620-#endif
621-
622-
623-/*
624-** These no-op macros are used in front of interfaces to mark those
625-** interfaces as either deprecated or experimental. New applications
626-** should not use deprecated interfaces - they are support for backwards
627-** compatibility only. Application writers should be aware that
628-** experimental interfaces are subject to change in point releases.
629-**
630-** These macros used to resolve to various kinds of compiler magic that
631-** would generate warning messages when they were used. But that
632-** compiler magic ended up generating such a flurry of bug reports
633-** that we have taken it all out and gone back to using simple
634-** noop macros.
635-*/
636-#define SQLITE_DEPRECATED
637-#define SQLITE_EXPERIMENTAL
638-
639-/*
640-** Ensure these symbols were not defined by some previous header file.
641-*/
642-#ifdef SQLITE_VERSION
643-# undef SQLITE_VERSION
644-#endif
645-#ifdef SQLITE_VERSION_NUMBER
646-# undef SQLITE_VERSION_NUMBER
647-#endif
648-
649-/*
650-** CAPI3REF: Compile-Time Library Version Numbers
651-**
652-** ^(The [SQLITE_VERSION] C preprocessor macro in the sqlite3.h header
653-** evaluates to a string literal that is the SQLite version in the
654-** format "X.Y.Z" where X is the major version number (always 3 for
655-** SQLite3) and Y is the minor version number and Z is the release number.)^
656-** ^(The [SQLITE_VERSION_NUMBER] C preprocessor macro resolves to an integer
657-** with the value (X*1000000 + Y*1000 + Z) where X, Y, and Z are the same
658-** numbers used in [SQLITE_VERSION].)^
659-** The SQLITE_VERSION_NUMBER for any given release of SQLite will also
660-** be larger than the release from which it is derived. Either Y will
661-** be held constant and Z will be incremented or else Y will be incremented
662-** and Z will be reset to zero.
663-**
664-** Since version 3.6.18, SQLite source code has been stored in the
665-** <a href="http://www.fossil-scm.org/">Fossil configuration management
666-** system</a>. ^The SQLITE_SOURCE_ID macro evaluates to
667-** a string which identifies a particular check-in of SQLite
668-** within its configuration management system. ^The SQLITE_SOURCE_ID
669-** string contains the date and time of the check-in (UTC) and an SHA1
670-** hash of the entire source tree.
671-**
672-** See also: [sqlite3_libversion()],
673-** [sqlite3_libversion_number()], [sqlite3_sourceid()],
674-** [sqlite_version()] and [sqlite_source_id()].
675-*/
676-#define SQLITE_VERSION "3.7.15.2"
677-#define SQLITE_VERSION_NUMBER 3007015
678-#define SQLITE_SOURCE_ID "2013-01-09 11:53:05 c0e09560d26f0a6456be9dd3447f5311eb4f238f"
679-
680-/*
681-** CAPI3REF: Run-Time Library Version Numbers
682-** KEYWORDS: sqlite3_version, sqlite3_sourceid
683-**
684-** These interfaces provide the same information as the [SQLITE_VERSION],
685-** [SQLITE_VERSION_NUMBER], and [SQLITE_SOURCE_ID] C preprocessor macros
686-** but are associated with the library instead of the header file. ^(Cautious
687-** programmers might include assert() statements in their application to
688-** verify that values returned by these interfaces match the macros in
689-** the header, and thus insure that the application is
690-** compiled with matching library and header files.
691-**
692-** <blockquote><pre>
693-** assert( sqlite3_libversion_number()==SQLITE_VERSION_NUMBER );
694-** assert( strcmp(sqlite3_sourceid(),SQLITE_SOURCE_ID)==0 );
695-** assert( strcmp(sqlite3_libversion(),SQLITE_VERSION)==0 );
696-** </pre></blockquote>)^
697-**
698-** ^The sqlite3_version[] string constant contains the text of [SQLITE_VERSION]
699-** macro. ^The sqlite3_libversion() function returns a pointer to the
700-** to the sqlite3_version[] string constant. The sqlite3_libversion()
701-** function is provided for use in DLLs since DLL users usually do not have
702-** direct access to string constants within the DLL. ^The
703-** sqlite3_libversion_number() function returns an integer equal to
704-** [SQLITE_VERSION_NUMBER]. ^The sqlite3_sourceid() function returns
705-** a pointer to a string constant whose value is the same as the
706-** [SQLITE_SOURCE_ID] C preprocessor macro.
707-**
708-** See also: [sqlite_version()] and [sqlite_source_id()].
709-*/
710-SQLITE_API const char sqlite3_version[] = SQLITE_VERSION;
711-SQLITE_API const char *sqlite3_libversion(void);
712-SQLITE_API const char *sqlite3_sourceid(void);
713-SQLITE_API int sqlite3_libversion_number(void);
714-
715-/*
716-** CAPI3REF: Run-Time Library Compilation Options Diagnostics
717-**
718-** ^The sqlite3_compileoption_used() function returns 0 or 1
719-** indicating whether the specified option was defined at
720-** compile time. ^The SQLITE_ prefix may be omitted from the
721-** option name passed to sqlite3_compileoption_used().
722-**
723-** ^The sqlite3_compileoption_get() function allows iterating
724-** over the list of options that were defined at compile time by
725-** returning the N-th compile time option string. ^If N is out of range,
726-** sqlite3_compileoption_get() returns a NULL pointer. ^The SQLITE_
727-** prefix is omitted from any strings returned by
728-** sqlite3_compileoption_get().
729-**
730-** ^Support for the diagnostic functions sqlite3_compileoption_used()
731-** and sqlite3_compileoption_get() may be omitted by specifying the
732-** [SQLITE_OMIT_COMPILEOPTION_DIAGS] option at compile time.
733-**
734-** See also: SQL functions [sqlite_compileoption_used()] and
735-** [sqlite_compileoption_get()] and the [compile_options pragma].
736-*/
737-#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
738-SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
739-SQLITE_API const char *sqlite3_compileoption_get(int N);
740-#endif
741-
742-/*
743-** CAPI3REF: Test To See If The Library Is Threadsafe
744-**
745-** ^The sqlite3_threadsafe() function returns zero if and only if
746-** SQLite was compiled with mutexing code omitted due to the
747-** [SQLITE_THREADSAFE] compile-time option being set to 0.
748-**
749-** SQLite can be compiled with or without mutexes. When
750-** the [SQLITE_THREADSAFE] C preprocessor macro is 1 or 2, mutexes
751-** are enabled and SQLite is threadsafe. When the
752-** [SQLITE_THREADSAFE] macro is 0,
753-** the mutexes are omitted. Without the mutexes, it is not safe
754-** to use SQLite concurrently from more than one thread.
755-**
756-** Enabling mutexes incurs a measurable performance penalty.
757-** So if speed is of utmost importance, it makes sense to disable
758-** the mutexes. But for maximum safety, mutexes should be enabled.
759-** ^The default behavior is for mutexes to be enabled.
760-**
761-** This interface can be used by an application to make sure that the
762-** version of SQLite that it is linking against was compiled with
763-** the desired setting of the [SQLITE_THREADSAFE] macro.
764-**
765-** This interface only reports on the compile-time mutex setting
766-** of the [SQLITE_THREADSAFE] flag. If SQLite is compiled with
767-** SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but
768-** can be fully or partially disabled using a call to [sqlite3_config()]
769-** with the verbs [SQLITE_CONFIG_SINGLETHREAD], [SQLITE_CONFIG_MULTITHREAD],
770-** or [SQLITE_CONFIG_MUTEX]. ^(The return value of the
771-** sqlite3_threadsafe() function shows only the compile-time setting of
772-** thread safety, not any run-time changes to that setting made by
773-** sqlite3_config(). In other words, the return value from sqlite3_threadsafe()
774-** is unchanged by calls to sqlite3_config().)^
775-**
776-** See the [threading mode] documentation for additional information.
777-*/
778-SQLITE_API int sqlite3_threadsafe(void);
779-
780-/*
781-** CAPI3REF: Database Connection Handle
782-** KEYWORDS: {database connection} {database connections}
783-**
784-** Each open SQLite database is represented by a pointer to an instance of
785-** the opaque structure named "sqlite3". It is useful to think of an sqlite3
786-** pointer as an object. The [sqlite3_open()], [sqlite3_open16()], and
787-** [sqlite3_open_v2()] interfaces are its constructors, and [sqlite3_close()]
788-** and [sqlite3_close_v2()] are its destructors. There are many other
789-** interfaces (such as
790-** [sqlite3_prepare_v2()], [sqlite3_create_function()], and
791-** [sqlite3_busy_timeout()] to name but three) that are methods on an
792-** sqlite3 object.
793-*/
794-typedef struct sqlite3 sqlite3;
795-
796-/*
797-** CAPI3REF: 64-Bit Integer Types
798-** KEYWORDS: sqlite_int64 sqlite_uint64
799-**
800-** Because there is no cross-platform way to specify 64-bit integer types
801-** SQLite includes typedefs for 64-bit signed and unsigned integers.
802-**
803-** The sqlite3_int64 and sqlite3_uint64 are the preferred type definitions.
804-** The sqlite_int64 and sqlite_uint64 types are supported for backwards
805-** compatibility only.
806-**
807-** ^The sqlite3_int64 and sqlite_int64 types can store integer values
808-** between -9223372036854775808 and +9223372036854775807 inclusive. ^The
809-** sqlite3_uint64 and sqlite_uint64 types can store integer values
810-** between 0 and +18446744073709551615 inclusive.
811-*/
812-#ifdef SQLITE_INT64_TYPE
813- typedef SQLITE_INT64_TYPE sqlite_int64;
814- typedef unsigned SQLITE_INT64_TYPE sqlite_uint64;
815-#elif defined(_MSC_VER) || defined(__BORLANDC__)
816- typedef __int64 sqlite_int64;
817- typedef unsigned __int64 sqlite_uint64;
818-#else
819- typedef long long int sqlite_int64;
820- typedef unsigned long long int sqlite_uint64;
821-#endif
822-typedef sqlite_int64 sqlite3_int64;
823-typedef sqlite_uint64 sqlite3_uint64;
824-
825-/*
826-** If compiling for a processor that lacks floating point support,
827-** substitute integer for floating-point.
828-*/
829-#ifdef SQLITE_OMIT_FLOATING_POINT
830-# define double sqlite3_int64
831-#endif
832-
833-/*
834-** CAPI3REF: Closing A Database Connection
835-**
836-** ^The sqlite3_close() and sqlite3_close_v2() routines are destructors
837-** for the [sqlite3] object.
838-** ^Calls to sqlite3_close() and sqlite3_close_v2() return SQLITE_OK if
839-** the [sqlite3] object is successfully destroyed and all associated
840-** resources are deallocated.
841-**
842-** ^If the database connection is associated with unfinalized prepared
843-** statements or unfinished sqlite3_backup objects then sqlite3_close()
844-** will leave the database connection open and return [SQLITE_BUSY].
845-** ^If sqlite3_close_v2() is called with unfinalized prepared statements
846-** and unfinished sqlite3_backups, then the database connection becomes
847-** an unusable "zombie" which will automatically be deallocated when the
848-** last prepared statement is finalized or the last sqlite3_backup is
849-** finished. The sqlite3_close_v2() interface is intended for use with
850-** host languages that are garbage collected, and where the order in which
851-** destructors are called is arbitrary.
852-**
853-** Applications should [sqlite3_finalize | finalize] all [prepared statements],
854-** [sqlite3_blob_close | close] all [BLOB handles], and
855-** [sqlite3_backup_finish | finish] all [sqlite3_backup] objects associated
856-** with the [sqlite3] object prior to attempting to close the object. ^If
857-** sqlite3_close() is called on a [database connection] that still has
858-** outstanding [prepared statements], [BLOB handles], and/or
859-** [sqlite3_backup] objects then it returns SQLITE_OK but the deallocation
860-** of resources is deferred until all [prepared statements], [BLOB handles],
861-** and [sqlite3_backup] objects are also destroyed.
862-**
863-** ^If an [sqlite3] object is destroyed while a transaction is open,
864-** the transaction is automatically rolled back.
865-**
866-** The C parameter to [sqlite3_close(C)] and [sqlite3_close_v2(C)]
867-** must be either a NULL
868-** pointer or an [sqlite3] object pointer obtained
869-** from [sqlite3_open()], [sqlite3_open16()], or
870-** [sqlite3_open_v2()], and not previously closed.
871-** ^Calling sqlite3_close() or sqlite3_close_v2() with a NULL pointer
872-** argument is a harmless no-op.
873-*/
874-SQLITE_API int sqlite3_close(sqlite3*);
875-SQLITE_API int sqlite3_close_v2(sqlite3*);
876-
877-/*
878-** The type for a callback function.
879-** This is legacy and deprecated. It is included for historical
880-** compatibility and is not documented.
881-*/
882-typedef int (*sqlite3_callback)(void*,int,char**, char**);
883-
884-/*
885-** CAPI3REF: One-Step Query Execution Interface
886-**
887-** The sqlite3_exec() interface is a convenience wrapper around
888-** [sqlite3_prepare_v2()], [sqlite3_step()], and [sqlite3_finalize()],
889-** that allows an application to run multiple statements of SQL
890-** without having to use a lot of C code.
891-**
892-** ^The sqlite3_exec() interface runs zero or more UTF-8 encoded,
893-** semicolon-separate SQL statements passed into its 2nd argument,
894-** in the context of the [database connection] passed in as its 1st
895-** argument. ^If the callback function of the 3rd argument to
896-** sqlite3_exec() is not NULL, then it is invoked for each result row
897-** coming out of the evaluated SQL statements. ^The 4th argument to
898-** sqlite3_exec() is relayed through to the 1st argument of each
899-** callback invocation. ^If the callback pointer to sqlite3_exec()
900-** is NULL, then no callback is ever invoked and result rows are
901-** ignored.
902-**
903-** ^If an error occurs while evaluating the SQL statements passed into
904-** sqlite3_exec(), then execution of the current statement stops and
905-** subsequent statements are skipped. ^If the 5th parameter to sqlite3_exec()
906-** is not NULL then any error message is written into memory obtained
907-** from [sqlite3_malloc()] and passed back through the 5th parameter.
908-** To avoid memory leaks, the application should invoke [sqlite3_free()]
909-** on error message strings returned through the 5th parameter of
910-** of sqlite3_exec() after the error message string is no longer needed.
911-** ^If the 5th parameter to sqlite3_exec() is not NULL and no errors
912-** occur, then sqlite3_exec() sets the pointer in its 5th parameter to
913-** NULL before returning.
914-**
915-** ^If an sqlite3_exec() callback returns non-zero, the sqlite3_exec()
916-** routine returns SQLITE_ABORT without invoking the callback again and
917-** without running any subsequent SQL statements.
918-**
919-** ^The 2nd argument to the sqlite3_exec() callback function is the
920-** number of columns in the result. ^The 3rd argument to the sqlite3_exec()
921-** callback is an array of pointers to strings obtained as if from
922-** [sqlite3_column_text()], one for each column. ^If an element of a
923-** result row is NULL then the corresponding string pointer for the
924-** sqlite3_exec() callback is a NULL pointer. ^The 4th argument to the
925-** sqlite3_exec() callback is an array of pointers to strings where each
926-** entry represents the name of corresponding result column as obtained
927-** from [sqlite3_column_name()].
928-**
929-** ^If the 2nd parameter to sqlite3_exec() is a NULL pointer, a pointer
930-** to an empty string, or a pointer that contains only whitespace and/or
931-** SQL comments, then no SQL statements are evaluated and the database
932-** is not changed.
933-**
934-** Restrictions:
935-**
936-** <ul>
937-** <li> The application must insure that the 1st parameter to sqlite3_exec()
938-** is a valid and open [database connection].
939-** <li> The application must not close [database connection] specified by
940-** the 1st parameter to sqlite3_exec() while sqlite3_exec() is running.
941-** <li> The application must not modify the SQL statement text passed into
942-** the 2nd parameter of sqlite3_exec() while sqlite3_exec() is running.
943-** </ul>
944-*/
945-SQLITE_API int sqlite3_exec(
946- sqlite3*, /* An open database */
947- const char *sql, /* SQL to be evaluated */
948- int (*callback)(void*,int,char**,char**), /* Callback function */
949- void *, /* 1st argument to callback */
950- char **errmsg /* Error msg written here */
951-);
952-
953-/*
954-** CAPI3REF: Result Codes
955-** KEYWORDS: SQLITE_OK {error code} {error codes}
956-** KEYWORDS: {result code} {result codes}
957-**
958-** Many SQLite functions return an integer result code from the set shown
959-** here in order to indicate success or failure.
960-**
961-** New error codes may be added in future versions of SQLite.
962-**
963-** See also: [SQLITE_IOERR_READ | extended result codes],
964-** [sqlite3_vtab_on_conflict()] [SQLITE_ROLLBACK | result codes].
965-*/
966-#define SQLITE_OK 0 /* Successful result */
967-/* beginning-of-error-codes */
968-#define SQLITE_ERROR 1 /* SQL error or missing database */
969-#define SQLITE_INTERNAL 2 /* Internal logic error in SQLite */
970-#define SQLITE_PERM 3 /* Access permission denied */
971-#define SQLITE_ABORT 4 /* Callback routine requested an abort */
972-#define SQLITE_BUSY 5 /* The database file is locked */
973-#define SQLITE_LOCKED 6 /* A table in the database is locked */
974-#define SQLITE_NOMEM 7 /* A malloc() failed */
975-#define SQLITE_READONLY 8 /* Attempt to write a readonly database */
976-#define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite3_interrupt()*/
977-#define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
978-#define SQLITE_CORRUPT 11 /* The database disk image is malformed */
979-#define SQLITE_NOTFOUND 12 /* Unknown opcode in sqlite3_file_control() */
980-#define SQLITE_FULL 13 /* Insertion failed because database is full */
981-#define SQLITE_CANTOPEN 14 /* Unable to open the database file */
982-#define SQLITE_PROTOCOL 15 /* Database lock protocol error */
983-#define SQLITE_EMPTY 16 /* Database is empty */
984-#define SQLITE_SCHEMA 17 /* The database schema changed */
985-#define SQLITE_TOOBIG 18 /* String or BLOB exceeds size limit */
986-#define SQLITE_CONSTRAINT 19 /* Abort due to constraint violation */
987-#define SQLITE_MISMATCH 20 /* Data type mismatch */
988-#define SQLITE_MISUSE 21 /* Library used incorrectly */
989-#define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
990-#define SQLITE_AUTH 23 /* Authorization denied */
991-#define SQLITE_FORMAT 24 /* Auxiliary database format error */
992-#define SQLITE_RANGE 25 /* 2nd parameter to sqlite3_bind out of range */
993-#define SQLITE_NOTADB 26 /* File opened that is not a database file */
994-#define SQLITE_ROW 100 /* sqlite3_step() has another row ready */
995-#define SQLITE_DONE 101 /* sqlite3_step() has finished executing */
996-/* end-of-error-codes */
997-
998-/*
999-** CAPI3REF: Extended Result Codes
1000-** KEYWORDS: {extended error code} {extended error codes}
1001-** KEYWORDS: {extended result code} {extended result codes}
1002-**
1003-** In its default configuration, SQLite API routines return one of 26 integer
1004-** [SQLITE_OK | result codes]. However, experience has shown that many of
1005-** these result codes are too coarse-grained. They do not provide as
1006-** much information about problems as programmers might like. In an effort to
1007-** address this, newer versions of SQLite (version 3.3.8 and later) include
1008-** support for additional result codes that provide more detailed information
1009-** about errors. The extended result codes are enabled or disabled
1010-** on a per database connection basis using the
1011-** [sqlite3_extended_result_codes()] API.
1012-**
1013-** Some of the available extended result codes are listed here.
1014-** One may expect the number of extended result codes will be expand
1015-** over time. Software that uses extended result codes should expect
1016-** to see new result codes in future releases of SQLite.
1017-**
1018-** The SQLITE_OK result code will never be extended. It will always
1019-** be exactly zero.
1020-*/
1021-#define SQLITE_IOERR_READ (SQLITE_IOERR | (1<<8))
1022-#define SQLITE_IOERR_SHORT_READ (SQLITE_IOERR | (2<<8))
1023-#define SQLITE_IOERR_WRITE (SQLITE_IOERR | (3<<8))
1024-#define SQLITE_IOERR_FSYNC (SQLITE_IOERR | (4<<8))
1025-#define SQLITE_IOERR_DIR_FSYNC (SQLITE_IOERR | (5<<8))
1026-#define SQLITE_IOERR_TRUNCATE (SQLITE_IOERR | (6<<8))
1027-#define SQLITE_IOERR_FSTAT (SQLITE_IOERR | (7<<8))
1028-#define SQLITE_IOERR_UNLOCK (SQLITE_IOERR | (8<<8))
1029-#define SQLITE_IOERR_RDLOCK (SQLITE_IOERR | (9<<8))
1030-#define SQLITE_IOERR_DELETE (SQLITE_IOERR | (10<<8))
1031-#define SQLITE_IOERR_BLOCKED (SQLITE_IOERR | (11<<8))
1032-#define SQLITE_IOERR_NOMEM (SQLITE_IOERR | (12<<8))
1033-#define SQLITE_IOERR_ACCESS (SQLITE_IOERR | (13<<8))
1034-#define SQLITE_IOERR_CHECKRESERVEDLOCK (SQLITE_IOERR | (14<<8))
1035-#define SQLITE_IOERR_LOCK (SQLITE_IOERR | (15<<8))
1036-#define SQLITE_IOERR_CLOSE (SQLITE_IOERR | (16<<8))
1037-#define SQLITE_IOERR_DIR_CLOSE (SQLITE_IOERR | (17<<8))
1038-#define SQLITE_IOERR_SHMOPEN (SQLITE_IOERR | (18<<8))
1039-#define SQLITE_IOERR_SHMSIZE (SQLITE_IOERR | (19<<8))
1040-#define SQLITE_IOERR_SHMLOCK (SQLITE_IOERR | (20<<8))
1041-#define SQLITE_IOERR_SHMMAP (SQLITE_IOERR | (21<<8))
1042-#define SQLITE_IOERR_SEEK (SQLITE_IOERR | (22<<8))
1043-#define SQLITE_IOERR_DELETE_NOENT (SQLITE_IOERR | (23<<8))
1044-#define SQLITE_LOCKED_SHAREDCACHE (SQLITE_LOCKED | (1<<8))
1045-#define SQLITE_BUSY_RECOVERY (SQLITE_BUSY | (1<<8))
1046-#define SQLITE_CANTOPEN_NOTEMPDIR (SQLITE_CANTOPEN | (1<<8))
1047-#define SQLITE_CANTOPEN_ISDIR (SQLITE_CANTOPEN | (2<<8))
1048-#define SQLITE_CANTOPEN_FULLPATH (SQLITE_CANTOPEN | (3<<8))
1049-#define SQLITE_CORRUPT_VTAB (SQLITE_CORRUPT | (1<<8))
1050-#define SQLITE_READONLY_RECOVERY (SQLITE_READONLY | (1<<8))
1051-#define SQLITE_READONLY_CANTLOCK (SQLITE_READONLY | (2<<8))
1052-#define SQLITE_ABORT_ROLLBACK (SQLITE_ABORT | (2<<8))
1053-
1054-/*
1055-** CAPI3REF: Flags For File Open Operations
1056-**
1057-** These bit values are intended for use in the
1058-** 3rd parameter to the [sqlite3_open_v2()] interface and
1059-** in the 4th parameter to the [sqlite3_vfs.xOpen] method.
1060-*/
1061-#define SQLITE_OPEN_READONLY 0x00000001 /* Ok for sqlite3_open_v2() */
1062-#define SQLITE_OPEN_READWRITE 0x00000002 /* Ok for sqlite3_open_v2() */
1063-#define SQLITE_OPEN_CREATE 0x00000004 /* Ok for sqlite3_open_v2() */
1064-#define SQLITE_OPEN_DELETEONCLOSE 0x00000008 /* VFS only */
1065-#define SQLITE_OPEN_EXCLUSIVE 0x00000010 /* VFS only */
1066-#define SQLITE_OPEN_AUTOPROXY 0x00000020 /* VFS only */
1067-#define SQLITE_OPEN_URI 0x00000040 /* Ok for sqlite3_open_v2() */
1068-#define SQLITE_OPEN_MEMORY 0x00000080 /* Ok for sqlite3_open_v2() */
1069-#define SQLITE_OPEN_MAIN_DB 0x00000100 /* VFS only */
1070-#define SQLITE_OPEN_TEMP_DB 0x00000200 /* VFS only */
1071-#define SQLITE_OPEN_TRANSIENT_DB 0x00000400 /* VFS only */
1072-#define SQLITE_OPEN_MAIN_JOURNAL 0x00000800 /* VFS only */
1073-#define SQLITE_OPEN_TEMP_JOURNAL 0x00001000 /* VFS only */
1074-#define SQLITE_OPEN_SUBJOURNAL 0x00002000 /* VFS only */
1075-#define SQLITE_OPEN_MASTER_JOURNAL 0x00004000 /* VFS only */
1076-#define SQLITE_OPEN_NOMUTEX 0x00008000 /* Ok for sqlite3_open_v2() */
1077-#define SQLITE_OPEN_FULLMUTEX 0x00010000 /* Ok for sqlite3_open_v2() */
1078-#define SQLITE_OPEN_SHAREDCACHE 0x00020000 /* Ok for sqlite3_open_v2() */
1079-#define SQLITE_OPEN_PRIVATECACHE 0x00040000 /* Ok for sqlite3_open_v2() */
1080-#define SQLITE_OPEN_WAL 0x00080000 /* VFS only */
1081-
1082-/* Reserved: 0x00F00000 */
1083-
1084-/*
1085-** CAPI3REF: Device Characteristics
1086-**
1087-** The xDeviceCharacteristics method of the [sqlite3_io_methods]
1088-** object returns an integer which is a vector of these
1089-** bit values expressing I/O characteristics of the mass storage
1090-** device that holds the file that the [sqlite3_io_methods]
1091-** refers to.
1092-**
1093-** The SQLITE_IOCAP_ATOMIC property means that all writes of
1094-** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
1095-** mean that writes of blocks that are nnn bytes in size and
1096-** are aligned to an address which is an integer multiple of
1097-** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
1098-** that when data is appended to a file, the data is appended
1099-** first then the size of the file is extended, never the other
1100-** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
1101-** information is written to disk in the same order as calls
1102-** to xWrite(). The SQLITE_IOCAP_POWERSAFE_OVERWRITE property means that
1103-** after reboot following a crash or power loss, the only bytes in a
1104-** file that were written at the application level might have changed
1105-** and that adjacent bytes, even bytes within the same sector are
1106-** guaranteed to be unchanged.
1107-*/
1108-#define SQLITE_IOCAP_ATOMIC 0x00000001
1109-#define SQLITE_IOCAP_ATOMIC512 0x00000002
1110-#define SQLITE_IOCAP_ATOMIC1K 0x00000004
1111-#define SQLITE_IOCAP_ATOMIC2K 0x00000008
1112-#define SQLITE_IOCAP_ATOMIC4K 0x00000010
1113-#define SQLITE_IOCAP_ATOMIC8K 0x00000020
1114-#define SQLITE_IOCAP_ATOMIC16K 0x00000040
1115-#define SQLITE_IOCAP_ATOMIC32K 0x00000080
1116-#define SQLITE_IOCAP_ATOMIC64K 0x00000100
1117-#define SQLITE_IOCAP_SAFE_APPEND 0x00000200
1118-#define SQLITE_IOCAP_SEQUENTIAL 0x00000400
1119-#define SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN 0x00000800
1120-#define SQLITE_IOCAP_POWERSAFE_OVERWRITE 0x00001000
1121-
1122-/*
1123-** CAPI3REF: File Locking Levels
1124-**
1125-** SQLite uses one of these integer values as the second
1126-** argument to calls it makes to the xLock() and xUnlock() methods
1127-** of an [sqlite3_io_methods] object.
1128-*/
1129-#define SQLITE_LOCK_NONE 0
1130-#define SQLITE_LOCK_SHARED 1
1131-#define SQLITE_LOCK_RESERVED 2
1132-#define SQLITE_LOCK_PENDING 3
1133-#define SQLITE_LOCK_EXCLUSIVE 4
1134-
1135-/*
1136-** CAPI3REF: Synchronization Type Flags
1137-**
1138-** When SQLite invokes the xSync() method of an
1139-** [sqlite3_io_methods] object it uses a combination of
1140-** these integer values as the second argument.
1141-**
1142-** When the SQLITE_SYNC_DATAONLY flag is used, it means that the
1143-** sync operation only needs to flush data to mass storage. Inode
1144-** information need not be flushed. If the lower four bits of the flag
1145-** equal SQLITE_SYNC_NORMAL, that means to use normal fsync() semantics.
1146-** If the lower four bits equal SQLITE_SYNC_FULL, that means
1147-** to use Mac OS X style fullsync instead of fsync().
1148-**
1149-** Do not confuse the SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags
1150-** with the [PRAGMA synchronous]=NORMAL and [PRAGMA synchronous]=FULL
1151-** settings. The [synchronous pragma] determines when calls to the
1152-** xSync VFS method occur and applies uniformly across all platforms.
1153-** The SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL flags determine how
1154-** energetic or rigorous or forceful the sync operations are and
1155-** only make a difference on Mac OSX for the default SQLite code.
1156-** (Third-party VFS implementations might also make the distinction
1157-** between SQLITE_SYNC_NORMAL and SQLITE_SYNC_FULL, but among the
1158-** operating systems natively supported by SQLite, only Mac OSX
1159-** cares about the difference.)
1160-*/
1161-#define SQLITE_SYNC_NORMAL 0x00002
1162-#define SQLITE_SYNC_FULL 0x00003
1163-#define SQLITE_SYNC_DATAONLY 0x00010
1164-
1165-/*
1166-** CAPI3REF: OS Interface Open File Handle
1167-**
1168-** An [sqlite3_file] object represents an open file in the
1169-** [sqlite3_vfs | OS interface layer]. Individual OS interface
1170-** implementations will
1171-** want to subclass this object by appending additional fields
1172-** for their own use. The pMethods entry is a pointer to an
1173-** [sqlite3_io_methods] object that defines methods for performing
1174-** I/O operations on the open file.
1175-*/
1176-typedef struct sqlite3_file sqlite3_file;
1177-struct sqlite3_file {
1178- const struct sqlite3_io_methods *pMethods; /* Methods for an open file */
1179-};
1180-
1181-/*
1182-** CAPI3REF: OS Interface File Virtual Methods Object
1183-**
1184-** Every file opened by the [sqlite3_vfs.xOpen] method populates an
1185-** [sqlite3_file] object (or, more commonly, a subclass of the
1186-** [sqlite3_file] object) with a pointer to an instance of this object.
1187-** This object defines the methods used to perform various operations
1188-** against the open file represented by the [sqlite3_file] object.
1189-**
1190-** If the [sqlite3_vfs.xOpen] method sets the sqlite3_file.pMethods element
1191-** to a non-NULL pointer, then the sqlite3_io_methods.xClose method
1192-** may be invoked even if the [sqlite3_vfs.xOpen] reported that it failed. The
1193-** only way to prevent a call to xClose following a failed [sqlite3_vfs.xOpen]
1194-** is for the [sqlite3_vfs.xOpen] to set the sqlite3_file.pMethods element
1195-** to NULL.
1196-**
1197-** The flags argument to xSync may be one of [SQLITE_SYNC_NORMAL] or
1198-** [SQLITE_SYNC_FULL]. The first choice is the normal fsync().
1199-** The second choice is a Mac OS X style fullsync. The [SQLITE_SYNC_DATAONLY]
1200-** flag may be ORed in to indicate that only the data of the file
1201-** and not its inode needs to be synced.
1202-**
1203-** The integer values to xLock() and xUnlock() are one of
1204-** <ul>
1205-** <li> [SQLITE_LOCK_NONE],
1206-** <li> [SQLITE_LOCK_SHARED],
1207-** <li> [SQLITE_LOCK_RESERVED],
1208-** <li> [SQLITE_LOCK_PENDING], or
1209-** <li> [SQLITE_LOCK_EXCLUSIVE].
1210-** </ul>
1211-** xLock() increases the lock. xUnlock() decreases the lock.
1212-** The xCheckReservedLock() method checks whether any database connection,
1213-** either in this process or in some other process, is holding a RESERVED,
1214-** PENDING, or EXCLUSIVE lock on the file. It returns true
1215-** if such a lock exists and false otherwise.
1216-**
1217-** The xFileControl() method is a generic interface that allows custom
1218-** VFS implementations to directly control an open file using the
1219-** [sqlite3_file_control()] interface. The second "op" argument is an
1220-** integer opcode. The third argument is a generic pointer intended to
1221-** point to a structure that may contain arguments or space in which to
1222-** write return values. Potential uses for xFileControl() might be
1223-** functions to enable blocking locks with timeouts, to change the
1224-** locking strategy (for example to use dot-file locks), to inquire
1225-** about the status of a lock, or to break stale locks. The SQLite
1226-** core reserves all opcodes less than 100 for its own use.
1227-** A [SQLITE_FCNTL_LOCKSTATE | list of opcodes] less than 100 is available.
1228-** Applications that define a custom xFileControl method should use opcodes
1229-** greater than 100 to avoid conflicts. VFS implementations should
1230-** return [SQLITE_NOTFOUND] for file control opcodes that they do not
1231-** recognize.
1232-**
1233-** The xSectorSize() method returns the sector size of the
1234-** device that underlies the file. The sector size is the
1235-** minimum write that can be performed without disturbing
1236-** other bytes in the file. The xDeviceCharacteristics()
1237-** method returns a bit vector describing behaviors of the
1238-** underlying device:
1239-**
1240-** <ul>
1241-** <li> [SQLITE_IOCAP_ATOMIC]
1242-** <li> [SQLITE_IOCAP_ATOMIC512]
1243-** <li> [SQLITE_IOCAP_ATOMIC1K]
1244-** <li> [SQLITE_IOCAP_ATOMIC2K]
1245-** <li> [SQLITE_IOCAP_ATOMIC4K]
1246-** <li> [SQLITE_IOCAP_ATOMIC8K]
1247-** <li> [SQLITE_IOCAP_ATOMIC16K]
1248-** <li> [SQLITE_IOCAP_ATOMIC32K]
1249-** <li> [SQLITE_IOCAP_ATOMIC64K]
1250-** <li> [SQLITE_IOCAP_SAFE_APPEND]
1251-** <li> [SQLITE_IOCAP_SEQUENTIAL]
1252-** </ul>
1253-**
1254-** The SQLITE_IOCAP_ATOMIC property means that all writes of
1255-** any size are atomic. The SQLITE_IOCAP_ATOMICnnn values
1256-** mean that writes of blocks that are nnn bytes in size and
1257-** are aligned to an address which is an integer multiple of
1258-** nnn are atomic. The SQLITE_IOCAP_SAFE_APPEND value means
1259-** that when data is appended to a file, the data is appended
1260-** first then the size of the file is extended, never the other
1261-** way around. The SQLITE_IOCAP_SEQUENTIAL property means that
1262-** information is written to disk in the same order as calls
1263-** to xWrite().
1264-**
1265-** If xRead() returns SQLITE_IOERR_SHORT_READ it must also fill
1266-** in the unread portions of the buffer with zeros. A VFS that
1267-** fails to zero-fill short reads might seem to work. However,
1268-** failure to zero-fill short reads will eventually lead to
1269-** database corruption.
1270-*/
1271-typedef struct sqlite3_io_methods sqlite3_io_methods;
1272-struct sqlite3_io_methods {
1273- int iVersion;
1274- int (*xClose)(sqlite3_file*);
1275- int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
1276- int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
1277- int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
1278- int (*xSync)(sqlite3_file*, int flags);
1279- int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
1280- int (*xLock)(sqlite3_file*, int);
1281- int (*xUnlock)(sqlite3_file*, int);
1282- int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
1283- int (*xFileControl)(sqlite3_file*, int op, void *pArg);
1284- int (*xSectorSize)(sqlite3_file*);
1285- int (*xDeviceCharacteristics)(sqlite3_file*);
1286- /* Methods above are valid for version 1 */
1287- int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
1288- int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
1289- void (*xShmBarrier)(sqlite3_file*);
1290- int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
1291- /* Methods above are valid for version 2 */
1292- /* Additional methods may be added in future releases */
1293-};
1294-
1295-/*
1296-** CAPI3REF: Standard File Control Opcodes
1297-**
1298-** These integer constants are opcodes for the xFileControl method
1299-** of the [sqlite3_io_methods] object and for the [sqlite3_file_control()]
1300-** interface.
1301-**
1302-** The [SQLITE_FCNTL_LOCKSTATE] opcode is used for debugging. This
1303-** opcode causes the xFileControl method to write the current state of
1304-** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
1305-** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
1306-** into an integer that the pArg argument points to. This capability
1307-** is used during testing and only needs to be supported when SQLITE_TEST
1308-** is defined.
1309-** <ul>
1310-** <li>[[SQLITE_FCNTL_SIZE_HINT]]
1311-** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS
1312-** layer a hint of how large the database file will grow to be during the
1313-** current transaction. This hint is not guaranteed to be accurate but it
1314-** is often close. The underlying VFS might choose to preallocate database
1315-** file space based on this hint in order to help writes to the database
1316-** file run faster.
1317-**
1318-** <li>[[SQLITE_FCNTL_CHUNK_SIZE]]
1319-** The [SQLITE_FCNTL_CHUNK_SIZE] opcode is used to request that the VFS
1320-** extends and truncates the database file in chunks of a size specified
1321-** by the user. The fourth argument to [sqlite3_file_control()] should
1322-** point to an integer (type int) containing the new chunk-size to use
1323-** for the nominated database. Allocating database file space in large
1324-** chunks (say 1MB at a time), may reduce file-system fragmentation and
1325-** improve performance on some systems.
1326-**
1327-** <li>[[SQLITE_FCNTL_FILE_POINTER]]
1328-** The [SQLITE_FCNTL_FILE_POINTER] opcode is used to obtain a pointer
1329-** to the [sqlite3_file] object associated with a particular database
1330-** connection. See the [sqlite3_file_control()] documentation for
1331-** additional information.
1332-**
1333-** <li>[[SQLITE_FCNTL_SYNC_OMITTED]]
1334-** ^(The [SQLITE_FCNTL_SYNC_OMITTED] opcode is generated internally by
1335-** SQLite and sent to all VFSes in place of a call to the xSync method
1336-** when the database connection has [PRAGMA synchronous] set to OFF.)^
1337-** Some specialized VFSes need this signal in order to operate correctly
1338-** when [PRAGMA synchronous | PRAGMA synchronous=OFF] is set, but most
1339-** VFSes do not need this signal and should silently ignore this opcode.
1340-** Applications should not call [sqlite3_file_control()] with this
1341-** opcode as doing so may disrupt the operation of the specialized VFSes
1342-** that do require it.
1343-**
1344-** <li>[[SQLITE_FCNTL_WIN32_AV_RETRY]]
1345-** ^The [SQLITE_FCNTL_WIN32_AV_RETRY] opcode is used to configure automatic
1346-** retry counts and intervals for certain disk I/O operations for the
1347-** windows [VFS] in order to provide robustness in the presence of
1348-** anti-virus programs. By default, the windows VFS will retry file read,
1349-** file write, and file delete operations up to 10 times, with a delay
1350-** of 25 milliseconds before the first retry and with the delay increasing
1351-** by an additional 25 milliseconds with each subsequent retry. This
1352-** opcode allows these two values (10 retries and 25 milliseconds of delay)
1353-** to be adjusted. The values are changed for all database connections
1354-** within the same process. The argument is a pointer to an array of two
1355-** integers where the first integer i the new retry count and the second
1356-** integer is the delay. If either integer is negative, then the setting
1357-** is not changed but instead the prior value of that setting is written
1358-** into the array entry, allowing the current retry settings to be
1359-** interrogated. The zDbName parameter is ignored.
1360-**
1361-** <li>[[SQLITE_FCNTL_PERSIST_WAL]]
1362-** ^The [SQLITE_FCNTL_PERSIST_WAL] opcode is used to set or query the
1363-** persistent [WAL | Write Ahead Log] setting. By default, the auxiliary
1364-** write ahead log and shared memory files used for transaction control
1365-** are automatically deleted when the latest connection to the database
1366-** closes. Setting persistent WAL mode causes those files to persist after
1367-** close. Persisting the files is useful when other processes that do not
1368-** have write permission on the directory containing the database file want
1369-** to read the database file, as the WAL and shared memory files must exist
1370-** in order for the database to be readable. The fourth parameter to
1371-** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
1372-** That integer is 0 to disable persistent WAL mode or 1 to enable persistent
1373-** WAL mode. If the integer is -1, then it is overwritten with the current
1374-** WAL persistence setting.
1375-**
1376-** <li>[[SQLITE_FCNTL_POWERSAFE_OVERWRITE]]
1377-** ^The [SQLITE_FCNTL_POWERSAFE_OVERWRITE] opcode is used to set or query the
1378-** persistent "powersafe-overwrite" or "PSOW" setting. The PSOW setting
1379-** determines the [SQLITE_IOCAP_POWERSAFE_OVERWRITE] bit of the
1380-** xDeviceCharacteristics methods. The fourth parameter to
1381-** [sqlite3_file_control()] for this opcode should be a pointer to an integer.
1382-** That integer is 0 to disable zero-damage mode or 1 to enable zero-damage
1383-** mode. If the integer is -1, then it is overwritten with the current
1384-** zero-damage mode setting.
1385-**
1386-** <li>[[SQLITE_FCNTL_OVERWRITE]]
1387-** ^The [SQLITE_FCNTL_OVERWRITE] opcode is invoked by SQLite after opening
1388-** a write transaction to indicate that, unless it is rolled back for some
1389-** reason, the entire database file will be overwritten by the current
1390-** transaction. This is used by VACUUM operations.
1391-**
1392-** <li>[[SQLITE_FCNTL_VFSNAME]]
1393-** ^The [SQLITE_FCNTL_VFSNAME] opcode can be used to obtain the names of
1394-** all [VFSes] in the VFS stack. The names are of all VFS shims and the
1395-** final bottom-level VFS are written into memory obtained from
1396-** [sqlite3_malloc()] and the result is stored in the char* variable
1397-** that the fourth parameter of [sqlite3_file_control()] points to.
1398-** The caller is responsible for freeing the memory when done. As with
1399-** all file-control actions, there is no guarantee that this will actually
1400-** do anything. Callers should initialize the char* variable to a NULL
1401-** pointer in case this file-control is not implemented. This file-control
1402-** is intended for diagnostic use only.
1403-**
1404-** <li>[[SQLITE_FCNTL_PRAGMA]]
1405-** ^Whenever a [PRAGMA] statement is parsed, an [SQLITE_FCNTL_PRAGMA]
1406-** file control is sent to the open [sqlite3_file] object corresponding
1407-** to the database file to which the pragma statement refers. ^The argument
1408-** to the [SQLITE_FCNTL_PRAGMA] file control is an array of
1409-** pointers to strings (char**) in which the second element of the array
1410-** is the name of the pragma and the third element is the argument to the
1411-** pragma or NULL if the pragma has no argument. ^The handler for an
1412-** [SQLITE_FCNTL_PRAGMA] file control can optionally make the first element
1413-** of the char** argument point to a string obtained from [sqlite3_mprintf()]
1414-** or the equivalent and that string will become the result of the pragma or
1415-** the error message if the pragma fails. ^If the
1416-** [SQLITE_FCNTL_PRAGMA] file control returns [SQLITE_NOTFOUND], then normal
1417-** [PRAGMA] processing continues. ^If the [SQLITE_FCNTL_PRAGMA]
1418-** file control returns [SQLITE_OK], then the parser assumes that the
1419-** VFS has handled the PRAGMA itself and the parser generates a no-op
1420-** prepared statement. ^If the [SQLITE_FCNTL_PRAGMA] file control returns
1421-** any result code other than [SQLITE_OK] or [SQLITE_NOTFOUND], that means
1422-** that the VFS encountered an error while handling the [PRAGMA] and the
1423-** compilation of the PRAGMA fails with an error. ^The [SQLITE_FCNTL_PRAGMA]
1424-** file control occurs at the beginning of pragma statement analysis and so
1425-** it is able to override built-in [PRAGMA] statements.
1426-**
1427-** <li>[[SQLITE_FCNTL_BUSYHANDLER]]
1428-** ^This file-control may be invoked by SQLite on the database file handle
1429-** shortly after it is opened in order to provide a custom VFS with access
1430-** to the connections busy-handler callback. The argument is of type (void **)
1431-** - an array of two (void *) values. The first (void *) actually points
1432-** to a function of type (int (*)(void *)). In order to invoke the connections
1433-** busy-handler, this function should be invoked with the second (void *) in
1434-** the array as the only argument. If it returns non-zero, then the operation
1435-** should be retried. If it returns zero, the custom VFS should abandon the
1436-** current operation.
1437-**
1438-** <li>[[SQLITE_FCNTL_TEMPFILENAME]]
1439-** ^Application can invoke this file-control to have SQLite generate a
1440-** temporary filename using the same algorithm that is followed to generate
1441-** temporary filenames for TEMP tables and other internal uses. The
1442-** argument should be a char** which will be filled with the filename
1443-** written into memory obtained from [sqlite3_malloc()]. The caller should
1444-** invoke [sqlite3_free()] on the result to avoid a memory leak.
1445-**
1446-** </ul>
1447-*/
1448-#define SQLITE_FCNTL_LOCKSTATE 1
1449-#define SQLITE_GET_LOCKPROXYFILE 2
1450-#define SQLITE_SET_LOCKPROXYFILE 3
1451-#define SQLITE_LAST_ERRNO 4
1452-#define SQLITE_FCNTL_SIZE_HINT 5
1453-#define SQLITE_FCNTL_CHUNK_SIZE 6
1454-#define SQLITE_FCNTL_FILE_POINTER 7
1455-#define SQLITE_FCNTL_SYNC_OMITTED 8
1456-#define SQLITE_FCNTL_WIN32_AV_RETRY 9
1457-#define SQLITE_FCNTL_PERSIST_WAL 10
1458-#define SQLITE_FCNTL_OVERWRITE 11
1459-#define SQLITE_FCNTL_VFSNAME 12
1460-#define SQLITE_FCNTL_POWERSAFE_OVERWRITE 13
1461-#define SQLITE_FCNTL_PRAGMA 14
1462-#define SQLITE_FCNTL_BUSYHANDLER 15
1463-#define SQLITE_FCNTL_TEMPFILENAME 16
1464-
1465-/*
1466-** CAPI3REF: Mutex Handle
1467-**
1468-** The mutex module within SQLite defines [sqlite3_mutex] to be an
1469-** abstract type for a mutex object. The SQLite core never looks
1470-** at the internal representation of an [sqlite3_mutex]. It only
1471-** deals with pointers to the [sqlite3_mutex] object.
1472-**
1473-** Mutexes are created using [sqlite3_mutex_alloc()].
1474-*/
1475-typedef struct sqlite3_mutex sqlite3_mutex;
1476-
1477-/*
1478-** CAPI3REF: OS Interface Object
1479-**
1480-** An instance of the sqlite3_vfs object defines the interface between
1481-** the SQLite core and the underlying operating system. The "vfs"
1482-** in the name of the object stands for "virtual file system". See
1483-** the [VFS | VFS documentation] for further information.
1484-**
1485-** The value of the iVersion field is initially 1 but may be larger in
1486-** future versions of SQLite. Additional fields may be appended to this
1487-** object when the iVersion value is increased. Note that the structure
1488-** of the sqlite3_vfs object changes in the transaction between
1489-** SQLite version 3.5.9 and 3.6.0 and yet the iVersion field was not
1490-** modified.
1491-**
1492-** The szOsFile field is the size of the subclassed [sqlite3_file]
1493-** structure used by this VFS. mxPathname is the maximum length of
1494-** a pathname in this VFS.
1495-**
1496-** Registered sqlite3_vfs objects are kept on a linked list formed by
1497-** the pNext pointer. The [sqlite3_vfs_register()]
1498-** and [sqlite3_vfs_unregister()] interfaces manage this list
1499-** in a thread-safe way. The [sqlite3_vfs_find()] interface
1500-** searches the list. Neither the application code nor the VFS
1501-** implementation should use the pNext pointer.
1502-**
1503-** The pNext field is the only field in the sqlite3_vfs
1504-** structure that SQLite will ever modify. SQLite will only access
1505-** or modify this field while holding a particular static mutex.
1506-** The application should never modify anything within the sqlite3_vfs
1507-** object once the object has been registered.
1508-**
1509-** The zName field holds the name of the VFS module. The name must
1510-** be unique across all VFS modules.
1511-**
1512-** [[sqlite3_vfs.xOpen]]
1513-** ^SQLite guarantees that the zFilename parameter to xOpen
1514-** is either a NULL pointer or string obtained
1515-** from xFullPathname() with an optional suffix added.
1516-** ^If a suffix is added to the zFilename parameter, it will
1517-** consist of a single "-" character followed by no more than
1518-** 11 alphanumeric and/or "-" characters.
1519-** ^SQLite further guarantees that
1520-** the string will be valid and unchanged until xClose() is
1521-** called. Because of the previous sentence,
1522-** the [sqlite3_file] can safely store a pointer to the
1523-** filename if it needs to remember the filename for some reason.
1524-** If the zFilename parameter to xOpen is a NULL pointer then xOpen
1525-** must invent its own temporary name for the file. ^Whenever the
1526-** xFilename parameter is NULL it will also be the case that the
1527-** flags parameter will include [SQLITE_OPEN_DELETEONCLOSE].
1528-**
1529-** The flags argument to xOpen() includes all bits set in
1530-** the flags argument to [sqlite3_open_v2()]. Or if [sqlite3_open()]
1531-** or [sqlite3_open16()] is used, then flags includes at least
1532-** [SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE].
1533-** If xOpen() opens a file read-only then it sets *pOutFlags to
1534-** include [SQLITE_OPEN_READONLY]. Other bits in *pOutFlags may be set.
1535-**
1536-** ^(SQLite will also add one of the following flags to the xOpen()
1537-** call, depending on the object being opened:
1538-**
1539-** <ul>
1540-** <li> [SQLITE_OPEN_MAIN_DB]
1541-** <li> [SQLITE_OPEN_MAIN_JOURNAL]
1542-** <li> [SQLITE_OPEN_TEMP_DB]
1543-** <li> [SQLITE_OPEN_TEMP_JOURNAL]
1544-** <li> [SQLITE_OPEN_TRANSIENT_DB]
1545-** <li> [SQLITE_OPEN_SUBJOURNAL]
1546-** <li> [SQLITE_OPEN_MASTER_JOURNAL]
1547-** <li> [SQLITE_OPEN_WAL]
1548-** </ul>)^
1549-**
1550-** The file I/O implementation can use the object type flags to
1551-** change the way it deals with files. For example, an application
1552-** that does not care about crash recovery or rollback might make
1553-** the open of a journal file a no-op. Writes to this journal would
1554-** also be no-ops, and any attempt to read the journal would return
1555-** SQLITE_IOERR. Or the implementation might recognize that a database
1556-** file will be doing page-aligned sector reads and writes in a random
1557-** order and set up its I/O subsystem accordingly.
1558-**
1559-** SQLite might also add one of the following flags to the xOpen method:
1560-**
1561-** <ul>
1562-** <li> [SQLITE_OPEN_DELETEONCLOSE]
1563-** <li> [SQLITE_OPEN_EXCLUSIVE]
1564-** </ul>
1565-**
1566-** The [SQLITE_OPEN_DELETEONCLOSE] flag means the file should be
1567-** deleted when it is closed. ^The [SQLITE_OPEN_DELETEONCLOSE]
1568-** will be set for TEMP databases and their journals, transient
1569-** databases, and subjournals.
1570-**
1571-** ^The [SQLITE_OPEN_EXCLUSIVE] flag is always used in conjunction
1572-** with the [SQLITE_OPEN_CREATE] flag, which are both directly
1573-** analogous to the O_EXCL and O_CREAT flags of the POSIX open()
1574-** API. The SQLITE_OPEN_EXCLUSIVE flag, when paired with the
1575-** SQLITE_OPEN_CREATE, is used to indicate that file should always
1576-** be created, and that it is an error if it already exists.
1577-** It is <i>not</i> used to indicate the file should be opened
1578-** for exclusive access.
1579-**
1580-** ^At least szOsFile bytes of memory are allocated by SQLite
1581-** to hold the [sqlite3_file] structure passed as the third
1582-** argument to xOpen. The xOpen method does not have to
1583-** allocate the structure; it should just fill it in. Note that
1584-** the xOpen method must set the sqlite3_file.pMethods to either
1585-** a valid [sqlite3_io_methods] object or to NULL. xOpen must do
1586-** this even if the open fails. SQLite expects that the sqlite3_file.pMethods
1587-** element will be valid after xOpen returns regardless of the success
1588-** or failure of the xOpen call.
1589-**
1590-** [[sqlite3_vfs.xAccess]]
1591-** ^The flags argument to xAccess() may be [SQLITE_ACCESS_EXISTS]
1592-** to test for the existence of a file, or [SQLITE_ACCESS_READWRITE] to
1593-** test whether a file is readable and writable, or [SQLITE_ACCESS_READ]
1594-** to test whether a file is at least readable. The file can be a
1595-** directory.
1596-**
1597-** ^SQLite will always allocate at least mxPathname+1 bytes for the
1598-** output buffer xFullPathname. The exact size of the output buffer
1599-** is also passed as a parameter to both methods. If the output buffer
1600-** is not large enough, [SQLITE_CANTOPEN] should be returned. Since this is
1601-** handled as a fatal error by SQLite, vfs implementations should endeavor
1602-** to prevent this by setting mxPathname to a sufficiently large value.
1603-**
1604-** The xRandomness(), xSleep(), xCurrentTime(), and xCurrentTimeInt64()
1605-** interfaces are not strictly a part of the filesystem, but they are
1606-** included in the VFS structure for completeness.
1607-** The xRandomness() function attempts to return nBytes bytes
1608-** of good-quality randomness into zOut. The return value is
1609-** the actual number of bytes of randomness obtained.
1610-** The xSleep() method causes the calling thread to sleep for at
1611-** least the number of microseconds given. ^The xCurrentTime()
1612-** method returns a Julian Day Number for the current date and time as
1613-** a floating point value.
1614-** ^The xCurrentTimeInt64() method returns, as an integer, the Julian
1615-** Day Number multiplied by 86400000 (the number of milliseconds in
1616-** a 24-hour day).
1617-** ^SQLite will use the xCurrentTimeInt64() method to get the current
1618-** date and time if that method is available (if iVersion is 2 or
1619-** greater and the function pointer is not NULL) and will fall back
1620-** to xCurrentTime() if xCurrentTimeInt64() is unavailable.
1621-**
1622-** ^The xSetSystemCall(), xGetSystemCall(), and xNestSystemCall() interfaces
1623-** are not used by the SQLite core. These optional interfaces are provided
1624-** by some VFSes to facilitate testing of the VFS code. By overriding
1625-** system calls with functions under its control, a test program can
1626-** simulate faults and error conditions that would otherwise be difficult
1627-** or impossible to induce. The set of system calls that can be overridden
1628-** varies from one VFS to another, and from one version of the same VFS to the
1629-** next. Applications that use these interfaces must be prepared for any
1630-** or all of these interfaces to be NULL or for their behavior to change
1631-** from one release to the next. Applications must not attempt to access
1632-** any of these methods if the iVersion of the VFS is less than 3.
1633-*/
1634-typedef struct sqlite3_vfs sqlite3_vfs;
1635-typedef void (*sqlite3_syscall_ptr)(void);
1636-struct sqlite3_vfs {
1637- int iVersion; /* Structure version number (currently 3) */
1638- int szOsFile; /* Size of subclassed sqlite3_file */
1639- int mxPathname; /* Maximum file pathname length */
1640- sqlite3_vfs *pNext; /* Next registered VFS */
1641- const char *zName; /* Name of this virtual file system */
1642- void *pAppData; /* Pointer to application-specific data */
1643- int (*xOpen)(sqlite3_vfs*, const char *zName, sqlite3_file*,
1644- int flags, int *pOutFlags);
1645- int (*xDelete)(sqlite3_vfs*, const char *zName, int syncDir);
1646- int (*xAccess)(sqlite3_vfs*, const char *zName, int flags, int *pResOut);
1647- int (*xFullPathname)(sqlite3_vfs*, const char *zName, int nOut, char *zOut);
1648- void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
1649- void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
1650- void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
1651- void (*xDlClose)(sqlite3_vfs*, void*);
1652- int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
1653- int (*xSleep)(sqlite3_vfs*, int microseconds);
1654- int (*xCurrentTime)(sqlite3_vfs*, double*);
1655- int (*xGetLastError)(sqlite3_vfs*, int, char *);
1656- /*
1657- ** The methods above are in version 1 of the sqlite_vfs object
1658- ** definition. Those that follow are added in version 2 or later
1659- */
1660- int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
1661- /*
1662- ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
1663- ** Those below are for version 3 and greater.
1664- */
1665- int (*xSetSystemCall)(sqlite3_vfs*, const char *zName, sqlite3_syscall_ptr);
1666- sqlite3_syscall_ptr (*xGetSystemCall)(sqlite3_vfs*, const char *zName);
1667- const char *(*xNextSystemCall)(sqlite3_vfs*, const char *zName);
1668- /*
1669- ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
1670- ** New fields may be appended in figure versions. The iVersion
1671- ** value will increment whenever this happens.
1672- */
1673-};
1674-
1675-/*
1676-** CAPI3REF: Flags for the xAccess VFS method
1677-**
1678-** These integer constants can be used as the third parameter to
1679-** the xAccess method of an [sqlite3_vfs] object. They determine
1680-** what kind of permissions the xAccess method is looking for.
1681-** With SQLITE_ACCESS_EXISTS, the xAccess method
1682-** simply checks whether the file exists.
1683-** With SQLITE_ACCESS_READWRITE, the xAccess method
1684-** checks whether the named directory is both readable and writable
1685-** (in other words, if files can be added, removed, and renamed within
1686-** the directory).
1687-** The SQLITE_ACCESS_READWRITE constant is currently used only by the
1688-** [temp_store_directory pragma], though this could change in a future
1689-** release of SQLite.
1690-** With SQLITE_ACCESS_READ, the xAccess method
1691-** checks whether the file is readable. The SQLITE_ACCESS_READ constant is
1692-** currently unused, though it might be used in a future release of
1693-** SQLite.
1694-*/
1695-#define SQLITE_ACCESS_EXISTS 0
1696-#define SQLITE_ACCESS_READWRITE 1 /* Used by PRAGMA temp_store_directory */
1697-#define SQLITE_ACCESS_READ 2 /* Unused */
1698-
1699-/*
1700-** CAPI3REF: Flags for the xShmLock VFS method
1701-**
1702-** These integer constants define the various locking operations
1703-** allowed by the xShmLock method of [sqlite3_io_methods]. The
1704-** following are the only legal combinations of flags to the
1705-** xShmLock method:
1706-**
1707-** <ul>
1708-** <li> SQLITE_SHM_LOCK | SQLITE_SHM_SHARED
1709-** <li> SQLITE_SHM_LOCK | SQLITE_SHM_EXCLUSIVE
1710-** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_SHARED
1711-** <li> SQLITE_SHM_UNLOCK | SQLITE_SHM_EXCLUSIVE
1712-** </ul>
1713-**
1714-** When unlocking, the same SHARED or EXCLUSIVE flag must be supplied as
1715-** was given no the corresponding lock.
1716-**
1717-** The xShmLock method can transition between unlocked and SHARED or
1718-** between unlocked and EXCLUSIVE. It cannot transition between SHARED
1719-** and EXCLUSIVE.
1720-*/
1721-#define SQLITE_SHM_UNLOCK 1
1722-#define SQLITE_SHM_LOCK 2
1723-#define SQLITE_SHM_SHARED 4
1724-#define SQLITE_SHM_EXCLUSIVE 8
1725-
1726-/*
1727-** CAPI3REF: Maximum xShmLock index
1728-**
1729-** The xShmLock method on [sqlite3_io_methods] may use values
1730-** between 0 and this upper bound as its "offset" argument.
1731-** The SQLite core will never attempt to acquire or release a
1732-** lock outside of this range
1733-*/
1734-#define SQLITE_SHM_NLOCK 8
1735-
1736-
1737-/*
1738-** CAPI3REF: Initialize The SQLite Library
1739-**
1740-** ^The sqlite3_initialize() routine initializes the
1741-** SQLite library. ^The sqlite3_shutdown() routine
1742-** deallocates any resources that were allocated by sqlite3_initialize().
1743-** These routines are designed to aid in process initialization and
1744-** shutdown on embedded systems. Workstation applications using
1745-** SQLite normally do not need to invoke either of these routines.
1746-**
1747-** A call to sqlite3_initialize() is an "effective" call if it is
1748-** the first time sqlite3_initialize() is invoked during the lifetime of
1749-** the process, or if it is the first time sqlite3_initialize() is invoked
1750-** following a call to sqlite3_shutdown(). ^(Only an effective call
1751-** of sqlite3_initialize() does any initialization. All other calls
1752-** are harmless no-ops.)^
1753-**
1754-** A call to sqlite3_shutdown() is an "effective" call if it is the first
1755-** call to sqlite3_shutdown() since the last sqlite3_initialize(). ^(Only
1756-** an effective call to sqlite3_shutdown() does any deinitialization.
1757-** All other valid calls to sqlite3_shutdown() are harmless no-ops.)^
1758-**
1759-** The sqlite3_initialize() interface is threadsafe, but sqlite3_shutdown()
1760-** is not. The sqlite3_shutdown() interface must only be called from a
1761-** single thread. All open [database connections] must be closed and all
1762-** other SQLite resources must be deallocated prior to invoking
1763-** sqlite3_shutdown().
1764-**
1765-** Among other things, ^sqlite3_initialize() will invoke
1766-** sqlite3_os_init(). Similarly, ^sqlite3_shutdown()
1767-** will invoke sqlite3_os_end().
1768-**
1769-** ^The sqlite3_initialize() routine returns [SQLITE_OK] on success.
1770-** ^If for some reason, sqlite3_initialize() is unable to initialize
1771-** the library (perhaps it is unable to allocate a needed resource such
1772-** as a mutex) it returns an [error code] other than [SQLITE_OK].
1773-**
1774-** ^The sqlite3_initialize() routine is called internally by many other
1775-** SQLite interfaces so that an application usually does not need to
1776-** invoke sqlite3_initialize() directly. For example, [sqlite3_open()]
1777-** calls sqlite3_initialize() so the SQLite library will be automatically
1778-** initialized when [sqlite3_open()] is called if it has not be initialized
1779-** already. ^However, if SQLite is compiled with the [SQLITE_OMIT_AUTOINIT]
1780-** compile-time option, then the automatic calls to sqlite3_initialize()
1781-** are omitted and the application must call sqlite3_initialize() directly
1782-** prior to using any other SQLite interface. For maximum portability,
1783-** it is recommended that applications always invoke sqlite3_initialize()
1784-** directly prior to using any other SQLite interface. Future releases
1785-** of SQLite may require this. In other words, the behavior exhibited
1786-** when SQLite is compiled with [SQLITE_OMIT_AUTOINIT] might become the
1787-** default behavior in some future release of SQLite.
1788-**
1789-** The sqlite3_os_init() routine does operating-system specific
1790-** initialization of the SQLite library. The sqlite3_os_end()
1791-** routine undoes the effect of sqlite3_os_init(). Typical tasks
1792-** performed by these routines include allocation or deallocation
1793-** of static resources, initialization of global variables,
1794-** setting up a default [sqlite3_vfs] module, or setting up
1795-** a default configuration using [sqlite3_config()].
1796-**
1797-** The application should never invoke either sqlite3_os_init()
1798-** or sqlite3_os_end() directly. The application should only invoke
1799-** sqlite3_initialize() and sqlite3_shutdown(). The sqlite3_os_init()
1800-** interface is called automatically by sqlite3_initialize() and
1801-** sqlite3_os_end() is called by sqlite3_shutdown(). Appropriate
1802-** implementations for sqlite3_os_init() and sqlite3_os_end()
1803-** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
1804-** When [custom builds | built for other platforms]
1805-** (using the [SQLITE_OS_OTHER=1] compile-time
1806-** option) the application must supply a suitable implementation for
1807-** sqlite3_os_init() and sqlite3_os_end(). An application-supplied
1808-** implementation of sqlite3_os_init() or sqlite3_os_end()
1809-** must return [SQLITE_OK] on success and some other [error code] upon
1810-** failure.
1811-*/
1812-SQLITE_API int sqlite3_initialize(void);
1813-SQLITE_API int sqlite3_shutdown(void);
1814-SQLITE_API int sqlite3_os_init(void);
1815-SQLITE_API int sqlite3_os_end(void);
1816-
1817-/*
1818-** CAPI3REF: Configuring The SQLite Library
1819-**
1820-** The sqlite3_config() interface is used to make global configuration
1821-** changes to SQLite in order to tune SQLite to the specific needs of
1822-** the application. The default configuration is recommended for most
1823-** applications and so this routine is usually not necessary. It is
1824-** provided to support rare applications with unusual needs.
1825-**
1826-** The sqlite3_config() interface is not threadsafe. The application
1827-** must insure that no other SQLite interfaces are invoked by other
1828-** threads while sqlite3_config() is running. Furthermore, sqlite3_config()
1829-** may only be invoked prior to library initialization using
1830-** [sqlite3_initialize()] or after shutdown by [sqlite3_shutdown()].
1831-** ^If sqlite3_config() is called after [sqlite3_initialize()] and before
1832-** [sqlite3_shutdown()] then it will return SQLITE_MISUSE.
1833-** Note, however, that ^sqlite3_config() can be called as part of the
1834-** implementation of an application-defined [sqlite3_os_init()].
1835-**
1836-** The first argument to sqlite3_config() is an integer
1837-** [configuration option] that determines
1838-** what property of SQLite is to be configured. Subsequent arguments
1839-** vary depending on the [configuration option]
1840-** in the first argument.
1841-**
1842-** ^When a configuration option is set, sqlite3_config() returns [SQLITE_OK].
1843-** ^If the option is unknown or SQLite is unable to set the option
1844-** then this routine returns a non-zero [error code].
1845-*/
1846-SQLITE_API int sqlite3_config(int, ...);
1847-
1848-/*
1849-** CAPI3REF: Configure database connections
1850-**
1851-** The sqlite3_db_config() interface is used to make configuration
1852-** changes to a [database connection]. The interface is similar to
1853-** [sqlite3_config()] except that the changes apply to a single
1854-** [database connection] (specified in the first argument).
1855-**
1856-** The second argument to sqlite3_db_config(D,V,...) is the
1857-** [SQLITE_DBCONFIG_LOOKASIDE | configuration verb] - an integer code
1858-** that indicates what aspect of the [database connection] is being configured.
1859-** Subsequent arguments vary depending on the configuration verb.
1860-**
1861-** ^Calls to sqlite3_db_config() return SQLITE_OK if and only if
1862-** the call is considered successful.
1863-*/
1864-SQLITE_API int sqlite3_db_config(sqlite3*, int op, ...);
1865-
1866-/*
1867-** CAPI3REF: Memory Allocation Routines
1868-**
1869-** An instance of this object defines the interface between SQLite
1870-** and low-level memory allocation routines.
1871-**
1872-** This object is used in only one place in the SQLite interface.
1873-** A pointer to an instance of this object is the argument to
1874-** [sqlite3_config()] when the configuration option is
1875-** [SQLITE_CONFIG_MALLOC] or [SQLITE_CONFIG_GETMALLOC].
1876-** By creating an instance of this object
1877-** and passing it to [sqlite3_config]([SQLITE_CONFIG_MALLOC])
1878-** during configuration, an application can specify an alternative
1879-** memory allocation subsystem for SQLite to use for all of its
1880-** dynamic memory needs.
1881-**
1882-** Note that SQLite comes with several [built-in memory allocators]
1883-** that are perfectly adequate for the overwhelming majority of applications
1884-** and that this object is only useful to a tiny minority of applications
1885-** with specialized memory allocation requirements. This object is
1886-** also used during testing of SQLite in order to specify an alternative
1887-** memory allocator that simulates memory out-of-memory conditions in
1888-** order to verify that SQLite recovers gracefully from such
1889-** conditions.
1890-**
1891-** The xMalloc, xRealloc, and xFree methods must work like the
1892-** malloc(), realloc() and free() functions from the standard C library.
1893-** ^SQLite guarantees that the second argument to
1894-** xRealloc is always a value returned by a prior call to xRoundup.
1895-**
1896-** xSize should return the allocated size of a memory allocation
1897-** previously obtained from xMalloc or xRealloc. The allocated size
1898-** is always at least as big as the requested size but may be larger.
1899-**
1900-** The xRoundup method returns what would be the allocated size of
1901-** a memory allocation given a particular requested size. Most memory
1902-** allocators round up memory allocations at least to the next multiple
1903-** of 8. Some allocators round up to a larger multiple or to a power of 2.
1904-** Every memory allocation request coming in through [sqlite3_malloc()]
1905-** or [sqlite3_realloc()] first calls xRoundup. If xRoundup returns 0,
1906-** that causes the corresponding memory allocation to fail.
1907-**
1908-** The xInit method initializes the memory allocator. (For example,
1909-** it might allocate any require mutexes or initialize internal data
1910-** structures. The xShutdown method is invoked (indirectly) by
1911-** [sqlite3_shutdown()] and should deallocate any resources acquired
1912-** by xInit. The pAppData pointer is used as the only parameter to
1913-** xInit and xShutdown.
1914-**
1915-** SQLite holds the [SQLITE_MUTEX_STATIC_MASTER] mutex when it invokes
1916-** the xInit method, so the xInit method need not be threadsafe. The
1917-** xShutdown method is only called from [sqlite3_shutdown()] so it does
1918-** not need to be threadsafe either. For all other methods, SQLite
1919-** holds the [SQLITE_MUTEX_STATIC_MEM] mutex as long as the
1920-** [SQLITE_CONFIG_MEMSTATUS] configuration option is turned on (which
1921-** it is by default) and so the methods are automatically serialized.
1922-** However, if [SQLITE_CONFIG_MEMSTATUS] is disabled, then the other
1923-** methods must be threadsafe or else make their own arrangements for
1924-** serialization.
1925-**
1926-** SQLite will never invoke xInit() more than once without an intervening
1927-** call to xShutdown().
1928-*/
1929-typedef struct sqlite3_mem_methods sqlite3_mem_methods;
1930-struct sqlite3_mem_methods {
1931- void *(*xMalloc)(int); /* Memory allocation function */
1932- void (*xFree)(void*); /* Free a prior allocation */
1933- void *(*xRealloc)(void*,int); /* Resize an allocation */
1934- int (*xSize)(void*); /* Return the size of an allocation */
1935- int (*xRoundup)(int); /* Round up request size to allocation size */
1936- int (*xInit)(void*); /* Initialize the memory allocator */
1937- void (*xShutdown)(void*); /* Deinitialize the memory allocator */
1938- void *pAppData; /* Argument to xInit() and xShutdown() */
1939-};
1940-
1941-/*
1942-** CAPI3REF: Configuration Options
1943-** KEYWORDS: {configuration option}
1944-**
1945-** These constants are the available integer configuration options that
1946-** can be passed as the first argument to the [sqlite3_config()] interface.
1947-**
1948-** New configuration options may be added in future releases of SQLite.
1949-** Existing configuration options might be discontinued. Applications
1950-** should check the return code from [sqlite3_config()] to make sure that
1951-** the call worked. The [sqlite3_config()] interface will return a
1952-** non-zero [error code] if a discontinued or unsupported configuration option
1953-** is invoked.
1954-**
1955-** <dl>
1956-** [[SQLITE_CONFIG_SINGLETHREAD]] <dt>SQLITE_CONFIG_SINGLETHREAD</dt>
1957-** <dd>There are no arguments to this option. ^This option sets the
1958-** [threading mode] to Single-thread. In other words, it disables
1959-** all mutexing and puts SQLite into a mode where it can only be used
1960-** by a single thread. ^If SQLite is compiled with
1961-** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1962-** it is not possible to change the [threading mode] from its default
1963-** value of Single-thread and so [sqlite3_config()] will return
1964-** [SQLITE_ERROR] if called with the SQLITE_CONFIG_SINGLETHREAD
1965-** configuration option.</dd>
1966-**
1967-** [[SQLITE_CONFIG_MULTITHREAD]] <dt>SQLITE_CONFIG_MULTITHREAD</dt>
1968-** <dd>There are no arguments to this option. ^This option sets the
1969-** [threading mode] to Multi-thread. In other words, it disables
1970-** mutexing on [database connection] and [prepared statement] objects.
1971-** The application is responsible for serializing access to
1972-** [database connections] and [prepared statements]. But other mutexes
1973-** are enabled so that SQLite will be safe to use in a multi-threaded
1974-** environment as long as no two threads attempt to use the same
1975-** [database connection] at the same time. ^If SQLite is compiled with
1976-** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1977-** it is not possible to set the Multi-thread [threading mode] and
1978-** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1979-** SQLITE_CONFIG_MULTITHREAD configuration option.</dd>
1980-**
1981-** [[SQLITE_CONFIG_SERIALIZED]] <dt>SQLITE_CONFIG_SERIALIZED</dt>
1982-** <dd>There are no arguments to this option. ^This option sets the
1983-** [threading mode] to Serialized. In other words, this option enables
1984-** all mutexes including the recursive
1985-** mutexes on [database connection] and [prepared statement] objects.
1986-** In this mode (which is the default when SQLite is compiled with
1987-** [SQLITE_THREADSAFE=1]) the SQLite library will itself serialize access
1988-** to [database connections] and [prepared statements] so that the
1989-** application is free to use the same [database connection] or the
1990-** same [prepared statement] in different threads at the same time.
1991-** ^If SQLite is compiled with
1992-** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
1993-** it is not possible to set the Serialized [threading mode] and
1994-** [sqlite3_config()] will return [SQLITE_ERROR] if called with the
1995-** SQLITE_CONFIG_SERIALIZED configuration option.</dd>
1996-**
1997-** [[SQLITE_CONFIG_MALLOC]] <dt>SQLITE_CONFIG_MALLOC</dt>
1998-** <dd> ^(This option takes a single argument which is a pointer to an
1999-** instance of the [sqlite3_mem_methods] structure. The argument specifies
2000-** alternative low-level memory allocation routines to be used in place of
2001-** the memory allocation routines built into SQLite.)^ ^SQLite makes
2002-** its own private copy of the content of the [sqlite3_mem_methods] structure
2003-** before the [sqlite3_config()] call returns.</dd>
2004-**
2005-** [[SQLITE_CONFIG_GETMALLOC]] <dt>SQLITE_CONFIG_GETMALLOC</dt>
2006-** <dd> ^(This option takes a single argument which is a pointer to an
2007-** instance of the [sqlite3_mem_methods] structure. The [sqlite3_mem_methods]
2008-** structure is filled with the currently defined memory allocation routines.)^
2009-** This option can be used to overload the default memory allocation
2010-** routines with a wrapper that simulations memory allocation failure or
2011-** tracks memory usage, for example. </dd>
2012-**
2013-** [[SQLITE_CONFIG_MEMSTATUS]] <dt>SQLITE_CONFIG_MEMSTATUS</dt>
2014-** <dd> ^This option takes single argument of type int, interpreted as a
2015-** boolean, which enables or disables the collection of memory allocation
2016-** statistics. ^(When memory allocation statistics are disabled, the
2017-** following SQLite interfaces become non-operational:
2018-** <ul>
2019-** <li> [sqlite3_memory_used()]
2020-** <li> [sqlite3_memory_highwater()]
2021-** <li> [sqlite3_soft_heap_limit64()]
2022-** <li> [sqlite3_status()]
2023-** </ul>)^
2024-** ^Memory allocation statistics are enabled by default unless SQLite is
2025-** compiled with [SQLITE_DEFAULT_MEMSTATUS]=0 in which case memory
2026-** allocation statistics are disabled by default.
2027-** </dd>
2028-**
2029-** [[SQLITE_CONFIG_SCRATCH]] <dt>SQLITE_CONFIG_SCRATCH</dt>
2030-** <dd> ^This option specifies a static memory buffer that SQLite can use for
2031-** scratch memory. There are three arguments: A pointer an 8-byte
2032-** aligned memory buffer from which the scratch allocations will be
2033-** drawn, the size of each scratch allocation (sz),
2034-** and the maximum number of scratch allocations (N). The sz
2035-** argument must be a multiple of 16.
2036-** The first argument must be a pointer to an 8-byte aligned buffer
2037-** of at least sz*N bytes of memory.
2038-** ^SQLite will use no more than two scratch buffers per thread. So
2039-** N should be set to twice the expected maximum number of threads.
2040-** ^SQLite will never require a scratch buffer that is more than 6
2041-** times the database page size. ^If SQLite needs needs additional
2042-** scratch memory beyond what is provided by this configuration option, then
2043-** [sqlite3_malloc()] will be used to obtain the memory needed.</dd>
2044-**
2045-** [[SQLITE_CONFIG_PAGECACHE]] <dt>SQLITE_CONFIG_PAGECACHE</dt>
2046-** <dd> ^This option specifies a static memory buffer that SQLite can use for
2047-** the database page cache with the default page cache implementation.
2048-** This configuration should not be used if an application-define page
2049-** cache implementation is loaded using the SQLITE_CONFIG_PCACHE2 option.
2050-** There are three arguments to this option: A pointer to 8-byte aligned
2051-** memory, the size of each page buffer (sz), and the number of pages (N).
2052-** The sz argument should be the size of the largest database page
2053-** (a power of two between 512 and 32768) plus a little extra for each
2054-** page header. ^The page header size is 20 to 40 bytes depending on
2055-** the host architecture. ^It is harmless, apart from the wasted memory,
2056-** to make sz a little too large. The first
2057-** argument should point to an allocation of at least sz*N bytes of memory.
2058-** ^SQLite will use the memory provided by the first argument to satisfy its
2059-** memory needs for the first N pages that it adds to cache. ^If additional
2060-** page cache memory is needed beyond what is provided by this option, then
2061-** SQLite goes to [sqlite3_malloc()] for the additional storage space.
2062-** The pointer in the first argument must
2063-** be aligned to an 8-byte boundary or subsequent behavior of SQLite
2064-** will be undefined.</dd>
2065-**
2066-** [[SQLITE_CONFIG_HEAP]] <dt>SQLITE_CONFIG_HEAP</dt>
2067-** <dd> ^This option specifies a static memory buffer that SQLite will use
2068-** for all of its dynamic memory allocation needs beyond those provided
2069-** for by [SQLITE_CONFIG_SCRATCH] and [SQLITE_CONFIG_PAGECACHE].
2070-** There are three arguments: An 8-byte aligned pointer to the memory,
2071-** the number of bytes in the memory buffer, and the minimum allocation size.
2072-** ^If the first pointer (the memory pointer) is NULL, then SQLite reverts
2073-** to using its default memory allocator (the system malloc() implementation),
2074-** undoing any prior invocation of [SQLITE_CONFIG_MALLOC]. ^If the
2075-** memory pointer is not NULL and either [SQLITE_ENABLE_MEMSYS3] or
2076-** [SQLITE_ENABLE_MEMSYS5] are defined, then the alternative memory
2077-** allocator is engaged to handle all of SQLites memory allocation needs.
2078-** The first pointer (the memory pointer) must be aligned to an 8-byte
2079-** boundary or subsequent behavior of SQLite will be undefined.
2080-** The minimum allocation size is capped at 2**12. Reasonable values
2081-** for the minimum allocation size are 2**5 through 2**8.</dd>
2082-**
2083-** [[SQLITE_CONFIG_MUTEX]] <dt>SQLITE_CONFIG_MUTEX</dt>
2084-** <dd> ^(This option takes a single argument which is a pointer to an
2085-** instance of the [sqlite3_mutex_methods] structure. The argument specifies
2086-** alternative low-level mutex routines to be used in place
2087-** the mutex routines built into SQLite.)^ ^SQLite makes a copy of the
2088-** content of the [sqlite3_mutex_methods] structure before the call to
2089-** [sqlite3_config()] returns. ^If SQLite is compiled with
2090-** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
2091-** the entire mutexing subsystem is omitted from the build and hence calls to
2092-** [sqlite3_config()] with the SQLITE_CONFIG_MUTEX configuration option will
2093-** return [SQLITE_ERROR].</dd>
2094-**
2095-** [[SQLITE_CONFIG_GETMUTEX]] <dt>SQLITE_CONFIG_GETMUTEX</dt>
2096-** <dd> ^(This option takes a single argument which is a pointer to an
2097-** instance of the [sqlite3_mutex_methods] structure. The
2098-** [sqlite3_mutex_methods]
2099-** structure is filled with the currently defined mutex routines.)^
2100-** This option can be used to overload the default mutex allocation
2101-** routines with a wrapper used to track mutex usage for performance
2102-** profiling or testing, for example. ^If SQLite is compiled with
2103-** the [SQLITE_THREADSAFE | SQLITE_THREADSAFE=0] compile-time option then
2104-** the entire mutexing subsystem is omitted from the build and hence calls to
2105-** [sqlite3_config()] with the SQLITE_CONFIG_GETMUTEX configuration option will
2106-** return [SQLITE_ERROR].</dd>
2107-**
2108-** [[SQLITE_CONFIG_LOOKASIDE]] <dt>SQLITE_CONFIG_LOOKASIDE</dt>
2109-** <dd> ^(This option takes two arguments that determine the default
2110-** memory allocation for the lookaside memory allocator on each
2111-** [database connection]. The first argument is the
2112-** size of each lookaside buffer slot and the second is the number of
2113-** slots allocated to each database connection.)^ ^(This option sets the
2114-** <i>default</i> lookaside size. The [SQLITE_DBCONFIG_LOOKASIDE]
2115-** verb to [sqlite3_db_config()] can be used to change the lookaside
2116-** configuration on individual connections.)^ </dd>
2117-**
2118-** [[SQLITE_CONFIG_PCACHE2]] <dt>SQLITE_CONFIG_PCACHE2</dt>
2119-** <dd> ^(This option takes a single argument which is a pointer to
2120-** an [sqlite3_pcache_methods2] object. This object specifies the interface
2121-** to a custom page cache implementation.)^ ^SQLite makes a copy of the
2122-** object and uses it for page cache memory allocations.</dd>
2123-**
2124-** [[SQLITE_CONFIG_GETPCACHE2]] <dt>SQLITE_CONFIG_GETPCACHE2</dt>
2125-** <dd> ^(This option takes a single argument which is a pointer to an
2126-** [sqlite3_pcache_methods2] object. SQLite copies of the current
2127-** page cache implementation into that object.)^ </dd>
2128-**
2129-** [[SQLITE_CONFIG_LOG]] <dt>SQLITE_CONFIG_LOG</dt>
2130-** <dd> ^The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
2131-** function with a call signature of void(*)(void*,int,const char*),
2132-** and a pointer to void. ^If the function pointer is not NULL, it is
2133-** invoked by [sqlite3_log()] to process each logging event. ^If the
2134-** function pointer is NULL, the [sqlite3_log()] interface becomes a no-op.
2135-** ^The void pointer that is the second argument to SQLITE_CONFIG_LOG is
2136-** passed through as the first parameter to the application-defined logger
2137-** function whenever that function is invoked. ^The second parameter to
2138-** the logger function is a copy of the first parameter to the corresponding
2139-** [sqlite3_log()] call and is intended to be a [result code] or an
2140-** [extended result code]. ^The third parameter passed to the logger is
2141-** log message after formatting via [sqlite3_snprintf()].
2142-** The SQLite logging interface is not reentrant; the logger function
2143-** supplied by the application must not invoke any SQLite interface.
2144-** In a multi-threaded application, the application-defined logger
2145-** function must be threadsafe. </dd>
2146-**
2147-** [[SQLITE_CONFIG_URI]] <dt>SQLITE_CONFIG_URI
2148-** <dd> This option takes a single argument of type int. If non-zero, then
2149-** URI handling is globally enabled. If the parameter is zero, then URI handling
2150-** is globally disabled. If URI handling is globally enabled, all filenames
2151-** passed to [sqlite3_open()], [sqlite3_open_v2()], [sqlite3_open16()] or
2152-** specified as part of [ATTACH] commands are interpreted as URIs, regardless
2153-** of whether or not the [SQLITE_OPEN_URI] flag is set when the database
2154-** connection is opened. If it is globally disabled, filenames are
2155-** only interpreted as URIs if the SQLITE_OPEN_URI flag is set when the
2156-** database connection is opened. By default, URI handling is globally
2157-** disabled. The default value may be changed by compiling with the
2158-** [SQLITE_USE_URI] symbol defined.
2159-**
2160-** [[SQLITE_CONFIG_COVERING_INDEX_SCAN]] <dt>SQLITE_CONFIG_COVERING_INDEX_SCAN
2161-** <dd> This option takes a single integer argument which is interpreted as
2162-** a boolean in order to enable or disable the use of covering indices for
2163-** full table scans in the query optimizer. The default setting is determined
2164-** by the [SQLITE_ALLOW_COVERING_INDEX_SCAN] compile-time option, or is "on"
2165-** if that compile-time option is omitted.
2166-** The ability to disable the use of covering indices for full table scans
2167-** is because some incorrectly coded legacy applications might malfunction
2168-** malfunction when the optimization is enabled. Providing the ability to
2169-** disable the optimization allows the older, buggy application code to work
2170-** without change even with newer versions of SQLite.
2171-**
2172-** [[SQLITE_CONFIG_PCACHE]] [[SQLITE_CONFIG_GETPCACHE]]
2173-** <dt>SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE
2174-** <dd> These options are obsolete and should not be used by new code.
2175-** They are retained for backwards compatibility but are now no-ops.
2176-** </dl>
2177-**
2178-** [[SQLITE_CONFIG_SQLLOG]]
2179-** <dt>SQLITE_CONFIG_SQLLOG
2180-** <dd>This option is only available if sqlite is compiled with the
2181-** SQLITE_ENABLE_SQLLOG pre-processor macro defined. The first argument should
2182-** be a pointer to a function of type void(*)(void*,sqlite3*,const char*, int).
2183-** The second should be of type (void*). The callback is invoked by the library
2184-** in three separate circumstances, identified by the value passed as the
2185-** fourth parameter. If the fourth parameter is 0, then the database connection
2186-** passed as the second argument has just been opened. The third argument
2187-** points to a buffer containing the name of the main database file. If the
2188-** fourth parameter is 1, then the SQL statement that the third parameter
2189-** points to has just been executed. Or, if the fourth parameter is 2, then
2190-** the connection being passed as the second parameter is being closed. The
2191-** third parameter is passed NULL In this case.
2192-** </dl>
2193-*/
2194-#define SQLITE_CONFIG_SINGLETHREAD 1 /* nil */
2195-#define SQLITE_CONFIG_MULTITHREAD 2 /* nil */
2196-#define SQLITE_CONFIG_SERIALIZED 3 /* nil */
2197-#define SQLITE_CONFIG_MALLOC 4 /* sqlite3_mem_methods* */
2198-#define SQLITE_CONFIG_GETMALLOC 5 /* sqlite3_mem_methods* */
2199-#define SQLITE_CONFIG_SCRATCH 6 /* void*, int sz, int N */
2200-#define SQLITE_CONFIG_PAGECACHE 7 /* void*, int sz, int N */
2201-#define SQLITE_CONFIG_HEAP 8 /* void*, int nByte, int min */
2202-#define SQLITE_CONFIG_MEMSTATUS 9 /* boolean */
2203-#define SQLITE_CONFIG_MUTEX 10 /* sqlite3_mutex_methods* */
2204-#define SQLITE_CONFIG_GETMUTEX 11 /* sqlite3_mutex_methods* */
2205-/* previously SQLITE_CONFIG_CHUNKALLOC 12 which is now unused. */
2206-#define SQLITE_CONFIG_LOOKASIDE 13 /* int int */
2207-#define SQLITE_CONFIG_PCACHE 14 /* no-op */
2208-#define SQLITE_CONFIG_GETPCACHE 15 /* no-op */
2209-#define SQLITE_CONFIG_LOG 16 /* xFunc, void* */
2210-#define SQLITE_CONFIG_URI 17 /* int */
2211-#define SQLITE_CONFIG_PCACHE2 18 /* sqlite3_pcache_methods2* */
2212-#define SQLITE_CONFIG_GETPCACHE2 19 /* sqlite3_pcache_methods2* */
2213-#define SQLITE_CONFIG_COVERING_INDEX_SCAN 20 /* int */
2214-#define SQLITE_CONFIG_SQLLOG 21 /* xSqllog, void* */
2215-
2216-/*
2217-** CAPI3REF: Database Connection Configuration Options
2218-**
2219-** These constants are the available integer configuration options that
2220-** can be passed as the second argument to the [sqlite3_db_config()] interface.
2221-**
2222-** New configuration options may be added in future releases of SQLite.
2223-** Existing configuration options might be discontinued. Applications
2224-** should check the return code from [sqlite3_db_config()] to make sure that
2225-** the call worked. ^The [sqlite3_db_config()] interface will return a
2226-** non-zero [error code] if a discontinued or unsupported configuration option
2227-** is invoked.
2228-**
2229-** <dl>
2230-** <dt>SQLITE_DBCONFIG_LOOKASIDE</dt>
2231-** <dd> ^This option takes three additional arguments that determine the
2232-** [lookaside memory allocator] configuration for the [database connection].
2233-** ^The first argument (the third parameter to [sqlite3_db_config()] is a
2234-** pointer to a memory buffer to use for lookaside memory.
2235-** ^The first argument after the SQLITE_DBCONFIG_LOOKASIDE verb
2236-** may be NULL in which case SQLite will allocate the
2237-** lookaside buffer itself using [sqlite3_malloc()]. ^The second argument is the
2238-** size of each lookaside buffer slot. ^The third argument is the number of
2239-** slots. The size of the buffer in the first argument must be greater than
2240-** or equal to the product of the second and third arguments. The buffer
2241-** must be aligned to an 8-byte boundary. ^If the second argument to
2242-** SQLITE_DBCONFIG_LOOKASIDE is not a multiple of 8, it is internally
2243-** rounded down to the next smaller multiple of 8. ^(The lookaside memory
2244-** configuration for a database connection can only be changed when that
2245-** connection is not currently using lookaside memory, or in other words
2246-** when the "current value" returned by
2247-** [sqlite3_db_status](D,[SQLITE_CONFIG_LOOKASIDE],...) is zero.
2248-** Any attempt to change the lookaside memory configuration when lookaside
2249-** memory is in use leaves the configuration unchanged and returns
2250-** [SQLITE_BUSY].)^</dd>
2251-**
2252-** <dt>SQLITE_DBCONFIG_ENABLE_FKEY</dt>
2253-** <dd> ^This option is used to enable or disable the enforcement of
2254-** [foreign key constraints]. There should be two additional arguments.
2255-** The first argument is an integer which is 0 to disable FK enforcement,
2256-** positive to enable FK enforcement or negative to leave FK enforcement
2257-** unchanged. The second parameter is a pointer to an integer into which
2258-** is written 0 or 1 to indicate whether FK enforcement is off or on
2259-** following this call. The second parameter may be a NULL pointer, in
2260-** which case the FK enforcement setting is not reported back. </dd>
2261-**
2262-** <dt>SQLITE_DBCONFIG_ENABLE_TRIGGER</dt>
2263-** <dd> ^This option is used to enable or disable [CREATE TRIGGER | triggers].
2264-** There should be two additional arguments.
2265-** The first argument is an integer which is 0 to disable triggers,
2266-** positive to enable triggers or negative to leave the setting unchanged.
2267-** The second parameter is a pointer to an integer into which
2268-** is written 0 or 1 to indicate whether triggers are disabled or enabled
2269-** following this call. The second parameter may be a NULL pointer, in
2270-** which case the trigger setting is not reported back. </dd>
2271-**
2272-** </dl>
2273-*/
2274-#define SQLITE_DBCONFIG_LOOKASIDE 1001 /* void* int int */
2275-#define SQLITE_DBCONFIG_ENABLE_FKEY 1002 /* int int* */
2276-#define SQLITE_DBCONFIG_ENABLE_TRIGGER 1003 /* int int* */
2277-
2278-
2279-/*
2280-** CAPI3REF: Enable Or Disable Extended Result Codes
2281-**
2282-** ^The sqlite3_extended_result_codes() routine enables or disables the
2283-** [extended result codes] feature of SQLite. ^The extended result
2284-** codes are disabled by default for historical compatibility.
2285-*/
2286-SQLITE_API int sqlite3_extended_result_codes(sqlite3*, int onoff);
2287-
2288-/*
2289-** CAPI3REF: Last Insert Rowid
2290-**
2291-** ^Each entry in an SQLite table has a unique 64-bit signed
2292-** integer key called the [ROWID | "rowid"]. ^The rowid is always available
2293-** as an undeclared column named ROWID, OID, or _ROWID_ as long as those
2294-** names are not also used by explicitly declared columns. ^If
2295-** the table has a column of type [INTEGER PRIMARY KEY] then that column
2296-** is another alias for the rowid.
2297-**
2298-** ^This routine returns the [rowid] of the most recent
2299-** successful [INSERT] into the database from the [database connection]
2300-** in the first argument. ^As of SQLite version 3.7.7, this routines
2301-** records the last insert rowid of both ordinary tables and [virtual tables].
2302-** ^If no successful [INSERT]s
2303-** have ever occurred on that database connection, zero is returned.
2304-**
2305-** ^(If an [INSERT] occurs within a trigger or within a [virtual table]
2306-** method, then this routine will return the [rowid] of the inserted
2307-** row as long as the trigger or virtual table method is running.
2308-** But once the trigger or virtual table method ends, the value returned
2309-** by this routine reverts to what it was before the trigger or virtual
2310-** table method began.)^
2311-**
2312-** ^An [INSERT] that fails due to a constraint violation is not a
2313-** successful [INSERT] and does not change the value returned by this
2314-** routine. ^Thus INSERT OR FAIL, INSERT OR IGNORE, INSERT OR ROLLBACK,
2315-** and INSERT OR ABORT make no changes to the return value of this
2316-** routine when their insertion fails. ^(When INSERT OR REPLACE
2317-** encounters a constraint violation, it does not fail. The
2318-** INSERT continues to completion after deleting rows that caused
2319-** the constraint problem so INSERT OR REPLACE will always change
2320-** the return value of this interface.)^
2321-**
2322-** ^For the purposes of this routine, an [INSERT] is considered to
2323-** be successful even if it is subsequently rolled back.
2324-**
2325-** This function is accessible to SQL statements via the
2326-** [last_insert_rowid() SQL function].
2327-**
2328-** If a separate thread performs a new [INSERT] on the same
2329-** database connection while the [sqlite3_last_insert_rowid()]
2330-** function is running and thus changes the last insert [rowid],
2331-** then the value returned by [sqlite3_last_insert_rowid()] is
2332-** unpredictable and might not equal either the old or the new
2333-** last insert [rowid].
2334-*/
2335-SQLITE_API sqlite3_int64 sqlite3_last_insert_rowid(sqlite3*);
2336-
2337-/*
2338-** CAPI3REF: Count The Number Of Rows Modified
2339-**
2340-** ^This function returns the number of database rows that were changed
2341-** or inserted or deleted by the most recently completed SQL statement
2342-** on the [database connection] specified by the first parameter.
2343-** ^(Only changes that are directly specified by the [INSERT], [UPDATE],
2344-** or [DELETE] statement are counted. Auxiliary changes caused by
2345-** triggers or [foreign key actions] are not counted.)^ Use the
2346-** [sqlite3_total_changes()] function to find the total number of changes
2347-** including changes caused by triggers and foreign key actions.
2348-**
2349-** ^Changes to a view that are simulated by an [INSTEAD OF trigger]
2350-** are not counted. Only real table changes are counted.
2351-**
2352-** ^(A "row change" is a change to a single row of a single table
2353-** caused by an INSERT, DELETE, or UPDATE statement. Rows that
2354-** are changed as side effects of [REPLACE] constraint resolution,
2355-** rollback, ABORT processing, [DROP TABLE], or by any other
2356-** mechanisms do not count as direct row changes.)^
2357-**
2358-** A "trigger context" is a scope of execution that begins and
2359-** ends with the script of a [CREATE TRIGGER | trigger].
2360-** Most SQL statements are
2361-** evaluated outside of any trigger. This is the "top level"
2362-** trigger context. If a trigger fires from the top level, a
2363-** new trigger context is entered for the duration of that one
2364-** trigger. Subtriggers create subcontexts for their duration.
2365-**
2366-** ^Calling [sqlite3_exec()] or [sqlite3_step()] recursively does
2367-** not create a new trigger context.
2368-**
2369-** ^This function returns the number of direct row changes in the
2370-** most recent INSERT, UPDATE, or DELETE statement within the same
2371-** trigger context.
2372-**
2373-** ^Thus, when called from the top level, this function returns the
2374-** number of changes in the most recent INSERT, UPDATE, or DELETE
2375-** that also occurred at the top level. ^(Within the body of a trigger,
2376-** the sqlite3_changes() interface can be called to find the number of
2377-** changes in the most recently completed INSERT, UPDATE, or DELETE
2378-** statement within the body of the same trigger.
2379-** However, the number returned does not include changes
2380-** caused by subtriggers since those have their own context.)^
2381-**
2382-** See also the [sqlite3_total_changes()] interface, the
2383-** [count_changes pragma], and the [changes() SQL function].
2384-**
2385-** If a separate thread makes changes on the same database connection
2386-** while [sqlite3_changes()] is running then the value returned
2387-** is unpredictable and not meaningful.
2388-*/
2389-SQLITE_API int sqlite3_changes(sqlite3*);
2390-
2391-/*
2392-** CAPI3REF: Total Number Of Rows Modified
2393-**
2394-** ^This function returns the number of row changes caused by [INSERT],
2395-** [UPDATE] or [DELETE] statements since the [database connection] was opened.
2396-** ^(The count returned by sqlite3_total_changes() includes all changes
2397-** from all [CREATE TRIGGER | trigger] contexts and changes made by
2398-** [foreign key actions]. However,
2399-** the count does not include changes used to implement [REPLACE] constraints,
2400-** do rollbacks or ABORT processing, or [DROP TABLE] processing. The
2401-** count does not include rows of views that fire an [INSTEAD OF trigger],
2402-** though if the INSTEAD OF trigger makes changes of its own, those changes
2403-** are counted.)^
2404-** ^The sqlite3_total_changes() function counts the changes as soon as
2405-** the statement that makes them is completed (when the statement handle
2406-** is passed to [sqlite3_reset()] or [sqlite3_finalize()]).
2407-**
2408-** See also the [sqlite3_changes()] interface, the
2409-** [count_changes pragma], and the [total_changes() SQL function].
2410-**
2411-** If a separate thread makes changes on the same database connection
2412-** while [sqlite3_total_changes()] is running then the value
2413-** returned is unpredictable and not meaningful.
2414-*/
2415-SQLITE_API int sqlite3_total_changes(sqlite3*);
2416-
2417-/*
2418-** CAPI3REF: Interrupt A Long-Running Query
2419-**
2420-** ^This function causes any pending database operation to abort and
2421-** return at its earliest opportunity. This routine is typically
2422-** called in response to a user action such as pressing "Cancel"
2423-** or Ctrl-C where the user wants a long query operation to halt
2424-** immediately.
2425-**
2426-** ^It is safe to call this routine from a thread different from the
2427-** thread that is currently running the database operation. But it
2428-** is not safe to call this routine with a [database connection] that
2429-** is closed or might close before sqlite3_interrupt() returns.
2430-**
2431-** ^If an SQL operation is very nearly finished at the time when
2432-** sqlite3_interrupt() is called, then it might not have an opportunity
2433-** to be interrupted and might continue to completion.
2434-**
2435-** ^An SQL operation that is interrupted will return [SQLITE_INTERRUPT].
2436-** ^If the interrupted SQL operation is an INSERT, UPDATE, or DELETE
2437-** that is inside an explicit transaction, then the entire transaction
2438-** will be rolled back automatically.
2439-**
2440-** ^The sqlite3_interrupt(D) call is in effect until all currently running
2441-** SQL statements on [database connection] D complete. ^Any new SQL statements
2442-** that are started after the sqlite3_interrupt() call and before the
2443-** running statements reaches zero are interrupted as if they had been
2444-** running prior to the sqlite3_interrupt() call. ^New SQL statements
2445-** that are started after the running statement count reaches zero are
2446-** not effected by the sqlite3_interrupt().
2447-** ^A call to sqlite3_interrupt(D) that occurs when there are no running
2448-** SQL statements is a no-op and has no effect on SQL statements
2449-** that are started after the sqlite3_interrupt() call returns.
2450-**
2451-** If the database connection closes while [sqlite3_interrupt()]
2452-** is running then bad things will likely happen.
2453-*/
2454-SQLITE_API void sqlite3_interrupt(sqlite3*);
2455-
2456-/*
2457-** CAPI3REF: Determine If An SQL Statement Is Complete
2458-**
2459-** These routines are useful during command-line input to determine if the
2460-** currently entered text seems to form a complete SQL statement or
2461-** if additional input is needed before sending the text into
2462-** SQLite for parsing. ^These routines return 1 if the input string
2463-** appears to be a complete SQL statement. ^A statement is judged to be
2464-** complete if it ends with a semicolon token and is not a prefix of a
2465-** well-formed CREATE TRIGGER statement. ^Semicolons that are embedded within
2466-** string literals or quoted identifier names or comments are not
2467-** independent tokens (they are part of the token in which they are
2468-** embedded) and thus do not count as a statement terminator. ^Whitespace
2469-** and comments that follow the final semicolon are ignored.
2470-**
2471-** ^These routines return 0 if the statement is incomplete. ^If a
2472-** memory allocation fails, then SQLITE_NOMEM is returned.
2473-**
2474-** ^These routines do not parse the SQL statements thus
2475-** will not detect syntactically incorrect SQL.
2476-**
2477-** ^(If SQLite has not been initialized using [sqlite3_initialize()] prior
2478-** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
2479-** automatically by sqlite3_complete16(). If that initialization fails,
2480-** then the return value from sqlite3_complete16() will be non-zero
2481-** regardless of whether or not the input SQL is complete.)^
2482-**
2483-** The input to [sqlite3_complete()] must be a zero-terminated
2484-** UTF-8 string.
2485-**
2486-** The input to [sqlite3_complete16()] must be a zero-terminated
2487-** UTF-16 string in native byte order.
2488-*/
2489-SQLITE_API int sqlite3_complete(const char *sql);
2490-SQLITE_API int sqlite3_complete16(const void *sql);
2491-
2492-/*
2493-** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
2494-**
2495-** ^This routine sets a callback function that might be invoked whenever
2496-** an attempt is made to open a database table that another thread
2497-** or process has locked.
2498-**
2499-** ^If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]
2500-** is returned immediately upon encountering the lock. ^If the busy callback
2501-** is not NULL, then the callback might be invoked with two arguments.
2502-**
2503-** ^The first argument to the busy handler is a copy of the void* pointer which
2504-** is the third argument to sqlite3_busy_handler(). ^The second argument to
2505-** the busy handler callback is the number of times that the busy handler has
2506-** been invoked for this locking event. ^If the
2507-** busy callback returns 0, then no additional attempts are made to
2508-** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
2509-** ^If the callback returns non-zero, then another attempt
2510-** is made to open the database for reading and the cycle repeats.
2511-**
2512-** The presence of a busy handler does not guarantee that it will be invoked
2513-** when there is lock contention. ^If SQLite determines that invoking the busy
2514-** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
2515-** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler.
2516-** Consider a scenario where one process is holding a read lock that
2517-** it is trying to promote to a reserved lock and
2518-** a second process is holding a reserved lock that it is trying
2519-** to promote to an exclusive lock. The first process cannot proceed
2520-** because it is blocked by the second and the second process cannot
2521-** proceed because it is blocked by the first. If both processes
2522-** invoke the busy handlers, neither will make any progress. Therefore,
2523-** SQLite returns [SQLITE_BUSY] for the first process, hoping that this
2524-** will induce the first process to release its read lock and allow
2525-** the second process to proceed.
2526-**
2527-** ^The default busy callback is NULL.
2528-**
2529-** ^The [SQLITE_BUSY] error is converted to [SQLITE_IOERR_BLOCKED]
2530-** when SQLite is in the middle of a large transaction where all the
2531-** changes will not fit into the in-memory cache. SQLite will
2532-** already hold a RESERVED lock on the database file, but it needs
2533-** to promote this lock to EXCLUSIVE so that it can spill cache
2534-** pages into the database file without harm to concurrent
2535-** readers. ^If it is unable to promote the lock, then the in-memory
2536-** cache will be left in an inconsistent state and so the error
2537-** code is promoted from the relatively benign [SQLITE_BUSY] to
2538-** the more severe [SQLITE_IOERR_BLOCKED]. ^This error code promotion
2539-** forces an automatic rollback of the changes. See the
2540-** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError">
2541-** CorruptionFollowingBusyError</a> wiki page for a discussion of why
2542-** this is important.
2543-**
2544-** ^(There can only be a single busy handler defined for each
2545-** [database connection]. Setting a new busy handler clears any
2546-** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()]
2547-** will also set or clear the busy handler.
2548-**
2549-** The busy callback should not take any actions which modify the
2550-** database connection that invoked the busy handler. Any such actions
2551-** result in undefined behavior.
2552-**
2553-** A busy handler must not close the database connection
2554-** or [prepared statement] that invoked the busy handler.
2555-*/
2556-SQLITE_API int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
2557-
2558-/*
2559-** CAPI3REF: Set A Busy Timeout
2560-**
2561-** ^This routine sets a [sqlite3_busy_handler | busy handler] that sleeps
2562-** for a specified amount of time when a table is locked. ^The handler
2563-** will sleep multiple times until at least "ms" milliseconds of sleeping
2564-** have accumulated. ^After at least "ms" milliseconds of sleeping,
2565-** the handler returns 0 which causes [sqlite3_step()] to return
2566-** [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED].
2567-**
2568-** ^Calling this routine with an argument less than or equal to zero
2569-** turns off all busy handlers.
2570-**
2571-** ^(There can only be a single busy handler for a particular
2572-** [database connection] any any given moment. If another busy handler
2573-** was defined (using [sqlite3_busy_handler()]) prior to calling
2574-** this routine, that other busy handler is cleared.)^
2575-*/
2576-SQLITE_API int sqlite3_busy_timeout(sqlite3*, int ms);
2577-
2578-/*
2579-** CAPI3REF: Convenience Routines For Running Queries
2580-**
2581-** This is a legacy interface that is preserved for backwards compatibility.
2582-** Use of this interface is not recommended.
2583-**
2584-** Definition: A <b>result table</b> is memory data structure created by the
2585-** [sqlite3_get_table()] interface. A result table records the
2586-** complete query results from one or more queries.
2587-**
2588-** The table conceptually has a number of rows and columns. But
2589-** these numbers are not part of the result table itself. These
2590-** numbers are obtained separately. Let N be the number of rows
2591-** and M be the number of columns.
2592-**
2593-** A result table is an array of pointers to zero-terminated UTF-8 strings.
2594-** There are (N+1)*M elements in the array. The first M pointers point
2595-** to zero-terminated strings that contain the names of the columns.
2596-** The remaining entries all point to query results. NULL values result
2597-** in NULL pointers. All other values are in their UTF-8 zero-terminated
2598-** string representation as returned by [sqlite3_column_text()].
2599-**
2600-** A result table might consist of one or more memory allocations.
2601-** It is not safe to pass a result table directly to [sqlite3_free()].
2602-** A result table should be deallocated using [sqlite3_free_table()].
2603-**
2604-** ^(As an example of the result table format, suppose a query result
2605-** is as follows:
2606-**
2607-** <blockquote><pre>
2608-** Name | Age
2609-** -----------------------
2610-** Alice | 43
2611-** Bob | 28
2612-** Cindy | 21
2613-** </pre></blockquote>
2614-**
2615-** There are two column (M==2) and three rows (N==3). Thus the
2616-** result table has 8 entries. Suppose the result table is stored
2617-** in an array names azResult. Then azResult holds this content:
2618-**
2619-** <blockquote><pre>
2620-** azResult&#91;0] = "Name";
2621-** azResult&#91;1] = "Age";
2622-** azResult&#91;2] = "Alice";
2623-** azResult&#91;3] = "43";
2624-** azResult&#91;4] = "Bob";
2625-** azResult&#91;5] = "28";
2626-** azResult&#91;6] = "Cindy";
2627-** azResult&#91;7] = "21";
2628-** </pre></blockquote>)^
2629-**
2630-** ^The sqlite3_get_table() function evaluates one or more
2631-** semicolon-separated SQL statements in the zero-terminated UTF-8
2632-** string of its 2nd parameter and returns a result table to the
2633-** pointer given in its 3rd parameter.
2634-**
2635-** After the application has finished with the result from sqlite3_get_table(),
2636-** it must pass the result table pointer to sqlite3_free_table() in order to
2637-** release the memory that was malloced. Because of the way the
2638-** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling
2639-** function must not try to call [sqlite3_free()] directly. Only
2640-** [sqlite3_free_table()] is able to release the memory properly and safely.
2641-**
2642-** The sqlite3_get_table() interface is implemented as a wrapper around
2643-** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access
2644-** to any internal data structures of SQLite. It uses only the public
2645-** interface defined here. As a consequence, errors that occur in the
2646-** wrapper layer outside of the internal [sqlite3_exec()] call are not
2647-** reflected in subsequent calls to [sqlite3_errcode()] or
2648-** [sqlite3_errmsg()].
2649-*/
2650-SQLITE_API int sqlite3_get_table(
2651- sqlite3 *db, /* An open database */
2652- const char *zSql, /* SQL to be evaluated */
2653- char ***pazResult, /* Results of the query */
2654- int *pnRow, /* Number of result rows written here */
2655- int *pnColumn, /* Number of result columns written here */
2656- char **pzErrmsg /* Error msg written here */
2657-);
2658-SQLITE_API void sqlite3_free_table(char **result);
2659-
2660-/*
2661-** CAPI3REF: Formatted String Printing Functions
2662-**
2663-** These routines are work-alikes of the "printf()" family of functions
2664-** from the standard C library.
2665-**
2666-** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
2667-** results into memory obtained from [sqlite3_malloc()].
2668-** The strings returned by these two routines should be
2669-** released by [sqlite3_free()]. ^Both routines return a
2670-** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
2671-** memory to hold the resulting string.
2672-**
2673-** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
2674-** the standard C library. The result is written into the
2675-** buffer supplied as the second parameter whose size is given by
2676-** the first parameter. Note that the order of the
2677-** first two parameters is reversed from snprintf().)^ This is an
2678-** historical accident that cannot be fixed without breaking
2679-** backwards compatibility. ^(Note also that sqlite3_snprintf()
2680-** returns a pointer to its buffer instead of the number of
2681-** characters actually written into the buffer.)^ We admit that
2682-** the number of characters written would be a more useful return
2683-** value but we cannot change the implementation of sqlite3_snprintf()
2684-** now without breaking compatibility.
2685-**
2686-** ^As long as the buffer size is greater than zero, sqlite3_snprintf()
2687-** guarantees that the buffer is always zero-terminated. ^The first
2688-** parameter "n" is the total size of the buffer, including space for
2689-** the zero terminator. So the longest string that can be completely
2690-** written will be n-1 characters.
2691-**
2692-** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
2693-**
2694-** These routines all implement some additional formatting
2695-** options that are useful for constructing SQL statements.
2696-** All of the usual printf() formatting options apply. In addition, there
2697-** is are "%q", "%Q", and "%z" options.
2698-**
2699-** ^(The %q option works like %s in that it substitutes a nul-terminated
2700-** string from the argument list. But %q also doubles every '\'' character.
2701-** %q is designed for use inside a string literal.)^ By doubling each '\''
2702-** character it escapes that character and allows it to be inserted into
2703-** the string.
2704-**
2705-** For example, assume the string variable zText contains text as follows:
2706-**
2707-** <blockquote><pre>
2708-** char *zText = "It's a happy day!";
2709-** </pre></blockquote>
2710-**
2711-** One can use this text in an SQL statement as follows:
2712-**
2713-** <blockquote><pre>
2714-** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
2715-** sqlite3_exec(db, zSQL, 0, 0, 0);
2716-** sqlite3_free(zSQL);
2717-** </pre></blockquote>
2718-**
2719-** Because the %q format string is used, the '\'' character in zText
2720-** is escaped and the SQL generated is as follows:
2721-**
2722-** <blockquote><pre>
2723-** INSERT INTO table1 VALUES('It''s a happy day!')
2724-** </pre></blockquote>
2725-**
2726-** This is correct. Had we used %s instead of %q, the generated SQL
2727-** would have looked like this:
2728-**
2729-** <blockquote><pre>
2730-** INSERT INTO table1 VALUES('It's a happy day!');
2731-** </pre></blockquote>
2732-**
2733-** This second example is an SQL syntax error. As a general rule you should
2734-** always use %q instead of %s when inserting text into a string literal.
2735-**
2736-** ^(The %Q option works like %q except it also adds single quotes around
2737-** the outside of the total string. Additionally, if the parameter in the
2738-** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
2739-** single quotes).)^ So, for example, one could say:
2740-**
2741-** <blockquote><pre>
2742-** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
2743-** sqlite3_exec(db, zSQL, 0, 0, 0);
2744-** sqlite3_free(zSQL);
2745-** </pre></blockquote>
2746-**
2747-** The code above will render a correct SQL statement in the zSQL
2748-** variable even if the zText variable is a NULL pointer.
2749-**
2750-** ^(The "%z" formatting option works like "%s" but with the
2751-** addition that after the string has been read and copied into
2752-** the result, [sqlite3_free()] is called on the input string.)^
2753-*/
2754-SQLITE_API char *sqlite3_mprintf(const char*,...);
2755-SQLITE_API char *sqlite3_vmprintf(const char*, va_list);
2756-SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...);
2757-SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list);
2758-
2759-/*
2760-** CAPI3REF: Memory Allocation Subsystem
2761-**
2762-** The SQLite core uses these three routines for all of its own
2763-** internal memory allocation needs. "Core" in the previous sentence
2764-** does not include operating-system specific VFS implementation. The
2765-** Windows VFS uses native malloc() and free() for some operations.
2766-**
2767-** ^The sqlite3_malloc() routine returns a pointer to a block
2768-** of memory at least N bytes in length, where N is the parameter.
2769-** ^If sqlite3_malloc() is unable to obtain sufficient free
2770-** memory, it returns a NULL pointer. ^If the parameter N to
2771-** sqlite3_malloc() is zero or negative then sqlite3_malloc() returns
2772-** a NULL pointer.
2773-**
2774-** ^Calling sqlite3_free() with a pointer previously returned
2775-** by sqlite3_malloc() or sqlite3_realloc() releases that memory so
2776-** that it might be reused. ^The sqlite3_free() routine is
2777-** a no-op if is called with a NULL pointer. Passing a NULL pointer
2778-** to sqlite3_free() is harmless. After being freed, memory
2779-** should neither be read nor written. Even reading previously freed
2780-** memory might result in a segmentation fault or other severe error.
2781-** Memory corruption, a segmentation fault, or other severe error
2782-** might result if sqlite3_free() is called with a non-NULL pointer that
2783-** was not obtained from sqlite3_malloc() or sqlite3_realloc().
2784-**
2785-** ^(The sqlite3_realloc() interface attempts to resize a
2786-** prior memory allocation to be at least N bytes, where N is the
2787-** second parameter. The memory allocation to be resized is the first
2788-** parameter.)^ ^ If the first parameter to sqlite3_realloc()
2789-** is a NULL pointer then its behavior is identical to calling
2790-** sqlite3_malloc(N) where N is the second parameter to sqlite3_realloc().
2791-** ^If the second parameter to sqlite3_realloc() is zero or
2792-** negative then the behavior is exactly the same as calling
2793-** sqlite3_free(P) where P is the first parameter to sqlite3_realloc().
2794-** ^sqlite3_realloc() returns a pointer to a memory allocation
2795-** of at least N bytes in size or NULL if sufficient memory is unavailable.
2796-** ^If M is the size of the prior allocation, then min(N,M) bytes
2797-** of the prior allocation are copied into the beginning of buffer returned
2798-** by sqlite3_realloc() and the prior allocation is freed.
2799-** ^If sqlite3_realloc() returns NULL, then the prior allocation
2800-** is not freed.
2801-**
2802-** ^The memory returned by sqlite3_malloc() and sqlite3_realloc()
2803-** is always aligned to at least an 8 byte boundary, or to a
2804-** 4 byte boundary if the [SQLITE_4_BYTE_ALIGNED_MALLOC] compile-time
2805-** option is used.
2806-**
2807-** In SQLite version 3.5.0 and 3.5.1, it was possible to define
2808-** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in
2809-** implementation of these routines to be omitted. That capability
2810-** is no longer provided. Only built-in memory allocators can be used.
2811-**
2812-** Prior to SQLite version 3.7.10, the Windows OS interface layer called
2813-** the system malloc() and free() directly when converting
2814-** filenames between the UTF-8 encoding used by SQLite
2815-** and whatever filename encoding is used by the particular Windows
2816-** installation. Memory allocation errors were detected, but
2817-** they were reported back as [SQLITE_CANTOPEN] or
2818-** [SQLITE_IOERR] rather than [SQLITE_NOMEM].
2819-**
2820-** The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()]
2821-** must be either NULL or else pointers obtained from a prior
2822-** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that have
2823-** not yet been released.
2824-**
2825-** The application must not read or write any part of
2826-** a block of memory after it has been released using
2827-** [sqlite3_free()] or [sqlite3_realloc()].
2828-*/
2829-SQLITE_API void *sqlite3_malloc(int);
2830-SQLITE_API void *sqlite3_realloc(void*, int);
2831-SQLITE_API void sqlite3_free(void*);
2832-
2833-/*
2834-** CAPI3REF: Memory Allocator Statistics
2835-**
2836-** SQLite provides these two interfaces for reporting on the status
2837-** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()]
2838-** routines, which form the built-in memory allocation subsystem.
2839-**
2840-** ^The [sqlite3_memory_used()] routine returns the number of bytes
2841-** of memory currently outstanding (malloced but not freed).
2842-** ^The [sqlite3_memory_highwater()] routine returns the maximum
2843-** value of [sqlite3_memory_used()] since the high-water mark
2844-** was last reset. ^The values returned by [sqlite3_memory_used()] and
2845-** [sqlite3_memory_highwater()] include any overhead
2846-** added by SQLite in its implementation of [sqlite3_malloc()],
2847-** but not overhead added by the any underlying system library
2848-** routines that [sqlite3_malloc()] may call.
2849-**
2850-** ^The memory high-water mark is reset to the current value of
2851-** [sqlite3_memory_used()] if and only if the parameter to
2852-** [sqlite3_memory_highwater()] is true. ^The value returned
2853-** by [sqlite3_memory_highwater(1)] is the high-water mark
2854-** prior to the reset.
2855-*/
2856-SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
2857-SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);
2858-
2859-/*
2860-** CAPI3REF: Pseudo-Random Number Generator
2861-**
2862-** SQLite contains a high-quality pseudo-random number generator (PRNG) used to
2863-** select random [ROWID | ROWIDs] when inserting new records into a table that
2864-** already uses the largest possible [ROWID]. The PRNG is also used for
2865-** the build-in random() and randomblob() SQL functions. This interface allows
2866-** applications to access the same PRNG for other purposes.
2867-**
2868-** ^A call to this routine stores N bytes of randomness into buffer P.
2869-**
2870-** ^The first time this routine is invoked (either internally or by
2871-** the application) the PRNG is seeded using randomness obtained
2872-** from the xRandomness method of the default [sqlite3_vfs] object.
2873-** ^On all subsequent invocations, the pseudo-randomness is generated
2874-** internally and without recourse to the [sqlite3_vfs] xRandomness
2875-** method.
2876-*/
2877-SQLITE_API void sqlite3_randomness(int N, void *P);
2878-
2879-/*
2880-** CAPI3REF: Compile-Time Authorization Callbacks
2881-**
2882-** ^This routine registers an authorizer callback with a particular
2883-** [database connection], supplied in the first argument.
2884-** ^The authorizer callback is invoked as SQL statements are being compiled
2885-** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()],
2886-** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. ^At various
2887-** points during the compilation process, as logic is being created
2888-** to perform various actions, the authorizer callback is invoked to
2889-** see if those actions are allowed. ^The authorizer callback should
2890-** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the
2891-** specific action but allow the SQL statement to continue to be
2892-** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be
2893-** rejected with an error. ^If the authorizer callback returns
2894-** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY]
2895-** then the [sqlite3_prepare_v2()] or equivalent call that triggered
2896-** the authorizer will fail with an error message.
2897-**
2898-** When the callback returns [SQLITE_OK], that means the operation
2899-** requested is ok. ^When the callback returns [SQLITE_DENY], the
2900-** [sqlite3_prepare_v2()] or equivalent call that triggered the
2901-** authorizer will fail with an error message explaining that
2902-** access is denied.
2903-**
2904-** ^The first parameter to the authorizer callback is a copy of the third
2905-** parameter to the sqlite3_set_authorizer() interface. ^The second parameter
2906-** to the callback is an integer [SQLITE_COPY | action code] that specifies
2907-** the particular action to be authorized. ^The third through sixth parameters
2908-** to the callback are zero-terminated strings that contain additional
2909-** details about the action to be authorized.
2910-**
2911-** ^If the action code is [SQLITE_READ]
2912-** and the callback returns [SQLITE_IGNORE] then the
2913-** [prepared statement] statement is constructed to substitute
2914-** a NULL value in place of the table column that would have
2915-** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE]
2916-** return can be used to deny an untrusted user access to individual
2917-** columns of a table.
2918-** ^If the action code is [SQLITE_DELETE] and the callback returns
2919-** [SQLITE_IGNORE] then the [DELETE] operation proceeds but the
2920-** [truncate optimization] is disabled and all rows are deleted individually.
2921-**
2922-** An authorizer is used when [sqlite3_prepare | preparing]
2923-** SQL statements from an untrusted source, to ensure that the SQL statements
2924-** do not try to access data they are not allowed to see, or that they do not
2925-** try to execute malicious statements that damage the database. For
2926-** example, an application may allow a user to enter arbitrary
2927-** SQL queries for evaluation by a database. But the application does
2928-** not want the user to be able to make arbitrary changes to the
2929-** database. An authorizer could then be put in place while the
2930-** user-entered SQL is being [sqlite3_prepare | prepared] that
2931-** disallows everything except [SELECT] statements.
2932-**
2933-** Applications that need to process SQL from untrusted sources
2934-** might also consider lowering resource limits using [sqlite3_limit()]
2935-** and limiting database size using the [max_page_count] [PRAGMA]
2936-** in addition to using an authorizer.
2937-**
2938-** ^(Only a single authorizer can be in place on a database connection
2939-** at a time. Each call to sqlite3_set_authorizer overrides the
2940-** previous call.)^ ^Disable the authorizer by installing a NULL callback.
2941-** The authorizer is disabled by default.
2942-**
2943-** The authorizer callback must not do anything that will modify
2944-** the database connection that invoked the authorizer callback.
2945-** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
2946-** database connections for the meaning of "modify" in this paragraph.
2947-**
2948-** ^When [sqlite3_prepare_v2()] is used to prepare a statement, the
2949-** statement might be re-prepared during [sqlite3_step()] due to a
2950-** schema change. Hence, the application should ensure that the
2951-** correct authorizer callback remains in place during the [sqlite3_step()].
2952-**
2953-** ^Note that the authorizer callback is invoked only during
2954-** [sqlite3_prepare()] or its variants. Authorization is not
2955-** performed during statement evaluation in [sqlite3_step()], unless
2956-** as stated in the previous paragraph, sqlite3_step() invokes
2957-** sqlite3_prepare_v2() to reprepare a statement after a schema change.
2958-*/
2959-SQLITE_API int sqlite3_set_authorizer(
2960- sqlite3*,
2961- int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
2962- void *pUserData
2963-);
2964-
2965-/*
2966-** CAPI3REF: Authorizer Return Codes
2967-**
2968-** The [sqlite3_set_authorizer | authorizer callback function] must
2969-** return either [SQLITE_OK] or one of these two constants in order
2970-** to signal SQLite whether or not the action is permitted. See the
2971-** [sqlite3_set_authorizer | authorizer documentation] for additional
2972-** information.
2973-**
2974-** Note that SQLITE_IGNORE is also used as a [SQLITE_ROLLBACK | return code]
2975-** from the [sqlite3_vtab_on_conflict()] interface.
2976-*/
2977-#define SQLITE_DENY 1 /* Abort the SQL statement with an error */
2978-#define SQLITE_IGNORE 2 /* Don't allow access, but don't generate an error */
2979-
2980-/*
2981-** CAPI3REF: Authorizer Action Codes
2982-**
2983-** The [sqlite3_set_authorizer()] interface registers a callback function
2984-** that is invoked to authorize certain SQL statement actions. The
2985-** second parameter to the callback is an integer code that specifies
2986-** what action is being authorized. These are the integer action codes that
2987-** the authorizer callback may be passed.
2988-**
2989-** These action code values signify what kind of operation is to be
2990-** authorized. The 3rd and 4th parameters to the authorization
2991-** callback function will be parameters or NULL depending on which of these
2992-** codes is used as the second parameter. ^(The 5th parameter to the
2993-** authorizer callback is the name of the database ("main", "temp",
2994-** etc.) if applicable.)^ ^The 6th parameter to the authorizer callback
2995-** is the name of the inner-most trigger or view that is responsible for
2996-** the access attempt or NULL if this access attempt is directly from
2997-** top-level SQL code.
2998-*/
2999-/******************************************* 3rd ************ 4th ***********/
3000-#define SQLITE_CREATE_INDEX 1 /* Index Name Table Name */
3001-#define SQLITE_CREATE_TABLE 2 /* Table Name NULL */
3002-#define SQLITE_CREATE_TEMP_INDEX 3 /* Index Name Table Name */
3003-#define SQLITE_CREATE_TEMP_TABLE 4 /* Table Name NULL */
3004-#define SQLITE_CREATE_TEMP_TRIGGER 5 /* Trigger Name Table Name */
3005-#define SQLITE_CREATE_TEMP_VIEW 6 /* View Name NULL */
3006-#define SQLITE_CREATE_TRIGGER 7 /* Trigger Name Table Name */
3007-#define SQLITE_CREATE_VIEW 8 /* View Name NULL */
3008-#define SQLITE_DELETE 9 /* Table Name NULL */
3009-#define SQLITE_DROP_INDEX 10 /* Index Name Table Name */
3010-#define SQLITE_DROP_TABLE 11 /* Table Name NULL */
3011-#define SQLITE_DROP_TEMP_INDEX 12 /* Index Name Table Name */
3012-#define SQLITE_DROP_TEMP_TABLE 13 /* Table Name NULL */
3013-#define SQLITE_DROP_TEMP_TRIGGER 14 /* Trigger Name Table Name */
3014-#define SQLITE_DROP_TEMP_VIEW 15 /* View Name NULL */
3015-#define SQLITE_DROP_TRIGGER 16 /* Trigger Name Table Name */
3016-#define SQLITE_DROP_VIEW 17 /* View Name NULL */
3017-#define SQLITE_INSERT 18 /* Table Name NULL */
3018-#define SQLITE_PRAGMA 19 /* Pragma Name 1st arg or NULL */
3019-#define SQLITE_READ 20 /* Table Name Column Name */
3020-#define SQLITE_SELECT 21 /* NULL NULL */
3021-#define SQLITE_TRANSACTION 22 /* Operation NULL */
3022-#define SQLITE_UPDATE 23 /* Table Name Column Name */
3023-#define SQLITE_ATTACH 24 /* Filename NULL */
3024-#define SQLITE_DETACH 25 /* Database Name NULL */
3025-#define SQLITE_ALTER_TABLE 26 /* Database Name Table Name */
3026-#define SQLITE_REINDEX 27 /* Index Name NULL */
3027-#define SQLITE_ANALYZE 28 /* Table Name NULL */
3028-#define SQLITE_CREATE_VTABLE 29 /* Table Name Module Name */
3029-#define SQLITE_DROP_VTABLE 30 /* Table Name Module Name */
3030-#define SQLITE_FUNCTION 31 /* NULL Function Name */
3031-#define SQLITE_SAVEPOINT 32 /* Operation Savepoint Name */
3032-#define SQLITE_COPY 0 /* No longer used */
3033-
3034-/*
3035-** CAPI3REF: Tracing And Profiling Functions
3036-**
3037-** These routines register callback functions that can be used for
3038-** tracing and profiling the execution of SQL statements.
3039-**
3040-** ^The callback function registered by sqlite3_trace() is invoked at
3041-** various times when an SQL statement is being run by [sqlite3_step()].
3042-** ^The sqlite3_trace() callback is invoked with a UTF-8 rendering of the
3043-** SQL statement text as the statement first begins executing.
3044-** ^(Additional sqlite3_trace() callbacks might occur
3045-** as each triggered subprogram is entered. The callbacks for triggers
3046-** contain a UTF-8 SQL comment that identifies the trigger.)^
3047-**
3048-** ^The callback function registered by sqlite3_profile() is invoked
3049-** as each SQL statement finishes. ^The profile callback contains
3050-** the original statement text and an estimate of wall-clock time
3051-** of how long that statement took to run. ^The profile callback
3052-** time is in units of nanoseconds, however the current implementation
3053-** is only capable of millisecond resolution so the six least significant
3054-** digits in the time are meaningless. Future versions of SQLite
3055-** might provide greater resolution on the profiler callback. The
3056-** sqlite3_profile() function is considered experimental and is
3057-** subject to change in future versions of SQLite.
3058-*/
3059-SQLITE_API void *sqlite3_trace(sqlite3*, void(*xTrace)(void*,const char*), void*);
3060-SQLITE_API SQLITE_EXPERIMENTAL void *sqlite3_profile(sqlite3*,
3061- void(*xProfile)(void*,const char*,sqlite3_uint64), void*);
3062-
3063-/*
3064-** CAPI3REF: Query Progress Callbacks
3065-**
3066-** ^The sqlite3_progress_handler(D,N,X,P) interface causes the callback
3067-** function X to be invoked periodically during long running calls to
3068-** [sqlite3_exec()], [sqlite3_step()] and [sqlite3_get_table()] for
3069-** database connection D. An example use for this
3070-** interface is to keep a GUI updated during a large query.
3071-**
3072-** ^The parameter P is passed through as the only parameter to the
3073-** callback function X. ^The parameter N is the number of
3074-** [virtual machine instructions] that are evaluated between successive
3075-** invocations of the callback X.
3076-**
3077-** ^Only a single progress handler may be defined at one time per
3078-** [database connection]; setting a new progress handler cancels the
3079-** old one. ^Setting parameter X to NULL disables the progress handler.
3080-** ^The progress handler is also disabled by setting N to a value less
3081-** than 1.
3082-**
3083-** ^If the progress callback returns non-zero, the operation is
3084-** interrupted. This feature can be used to implement a
3085-** "Cancel" button on a GUI progress dialog box.
3086-**
3087-** The progress handler callback must not do anything that will modify
3088-** the database connection that invoked the progress handler.
3089-** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
3090-** database connections for the meaning of "modify" in this paragraph.
3091-**
3092-*/
3093-SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
3094-
3095-/*
3096-** CAPI3REF: Opening A New Database Connection
3097-**
3098-** ^These routines open an SQLite database file as specified by the
3099-** filename argument. ^The filename argument is interpreted as UTF-8 for
3100-** sqlite3_open() and sqlite3_open_v2() and as UTF-16 in the native byte
3101-** order for sqlite3_open16(). ^(A [database connection] handle is usually
3102-** returned in *ppDb, even if an error occurs. The only exception is that
3103-** if SQLite is unable to allocate memory to hold the [sqlite3] object,
3104-** a NULL will be written into *ppDb instead of a pointer to the [sqlite3]
3105-** object.)^ ^(If the database is opened (and/or created) successfully, then
3106-** [SQLITE_OK] is returned. Otherwise an [error code] is returned.)^ ^The
3107-** [sqlite3_errmsg()] or [sqlite3_errmsg16()] routines can be used to obtain
3108-** an English language description of the error following a failure of any
3109-** of the sqlite3_open() routines.
3110-**
3111-** ^The default encoding for the database will be UTF-8 if
3112-** sqlite3_open() or sqlite3_open_v2() is called and
3113-** UTF-16 in the native byte order if sqlite3_open16() is used.
3114-**
3115-** Whether or not an error occurs when it is opened, resources
3116-** associated with the [database connection] handle should be released by
3117-** passing it to [sqlite3_close()] when it is no longer required.
3118-**
3119-** The sqlite3_open_v2() interface works like sqlite3_open()
3120-** except that it accepts two additional parameters for additional control
3121-** over the new database connection. ^(The flags parameter to
3122-** sqlite3_open_v2() can take one of
3123-** the following three values, optionally combined with the
3124-** [SQLITE_OPEN_NOMUTEX], [SQLITE_OPEN_FULLMUTEX], [SQLITE_OPEN_SHAREDCACHE],
3125-** [SQLITE_OPEN_PRIVATECACHE], and/or [SQLITE_OPEN_URI] flags:)^
3126-**
3127-** <dl>
3128-** ^(<dt>[SQLITE_OPEN_READONLY]</dt>
3129-** <dd>The database is opened in read-only mode. If the database does not
3130-** already exist, an error is returned.</dd>)^
3131-**
3132-** ^(<dt>[SQLITE_OPEN_READWRITE]</dt>
3133-** <dd>The database is opened for reading and writing if possible, or reading
3134-** only if the file is write protected by the operating system. In either
3135-** case the database must already exist, otherwise an error is returned.</dd>)^
3136-**
3137-** ^(<dt>[SQLITE_OPEN_READWRITE] | [SQLITE_OPEN_CREATE]</dt>
3138-** <dd>The database is opened for reading and writing, and is created if
3139-** it does not already exist. This is the behavior that is always used for
3140-** sqlite3_open() and sqlite3_open16().</dd>)^
3141-** </dl>
3142-**
3143-** If the 3rd parameter to sqlite3_open_v2() is not one of the
3144-** combinations shown above optionally combined with other
3145-** [SQLITE_OPEN_READONLY | SQLITE_OPEN_* bits]
3146-** then the behavior is undefined.
3147-**
3148-** ^If the [SQLITE_OPEN_NOMUTEX] flag is set, then the database connection
3149-** opens in the multi-thread [threading mode] as long as the single-thread
3150-** mode has not been set at compile-time or start-time. ^If the
3151-** [SQLITE_OPEN_FULLMUTEX] flag is set then the database connection opens
3152-** in the serialized [threading mode] unless single-thread was
3153-** previously selected at compile-time or start-time.
3154-** ^The [SQLITE_OPEN_SHAREDCACHE] flag causes the database connection to be
3155-** eligible to use [shared cache mode], regardless of whether or not shared
3156-** cache is enabled using [sqlite3_enable_shared_cache()]. ^The
3157-** [SQLITE_OPEN_PRIVATECACHE] flag causes the database connection to not
3158-** participate in [shared cache mode] even if it is enabled.
3159-**
3160-** ^The fourth parameter to sqlite3_open_v2() is the name of the
3161-** [sqlite3_vfs] object that defines the operating system interface that
3162-** the new database connection should use. ^If the fourth parameter is
3163-** a NULL pointer then the default [sqlite3_vfs] object is used.
3164-**
3165-** ^If the filename is ":memory:", then a private, temporary in-memory database
3166-** is created for the connection. ^This in-memory database will vanish when
3167-** the database connection is closed. Future versions of SQLite might
3168-** make use of additional special filenames that begin with the ":" character.
3169-** It is recommended that when a database filename actually does begin with
3170-** a ":" character you should prefix the filename with a pathname such as
3171-** "./" to avoid ambiguity.
3172-**
3173-** ^If the filename is an empty string, then a private, temporary
3174-** on-disk database will be created. ^This private database will be
3175-** automatically deleted as soon as the database connection is closed.
3176-**
3177-** [[URI filenames in sqlite3_open()]] <h3>URI Filenames</h3>
3178-**
3179-** ^If [URI filename] interpretation is enabled, and the filename argument
3180-** begins with "file:", then the filename is interpreted as a URI. ^URI
3181-** filename interpretation is enabled if the [SQLITE_OPEN_URI] flag is
3182-** set in the fourth argument to sqlite3_open_v2(), or if it has
3183-** been enabled globally using the [SQLITE_CONFIG_URI] option with the
3184-** [sqlite3_config()] method or by the [SQLITE_USE_URI] compile-time option.
3185-** As of SQLite version 3.7.7, URI filename interpretation is turned off
3186-** by default, but future releases of SQLite might enable URI filename
3187-** interpretation by default. See "[URI filenames]" for additional
3188-** information.
3189-**
3190-** URI filenames are parsed according to RFC 3986. ^If the URI contains an
3191-** authority, then it must be either an empty string or the string
3192-** "localhost". ^If the authority is not an empty string or "localhost", an
3193-** error is returned to the caller. ^The fragment component of a URI, if
3194-** present, is ignored.
3195-**
3196-** ^SQLite uses the path component of the URI as the name of the disk file
3197-** which contains the database. ^If the path begins with a '/' character,
3198-** then it is interpreted as an absolute path. ^If the path does not begin
3199-** with a '/' (meaning that the authority section is omitted from the URI)
3200-** then the path is interpreted as a relative path.
3201-** ^On windows, the first component of an absolute path
3202-** is a drive specification (e.g. "C:").
3203-**
3204-** [[core URI query parameters]]
3205-** The query component of a URI may contain parameters that are interpreted
3206-** either by SQLite itself, or by a [VFS | custom VFS implementation].
3207-** SQLite interprets the following three query parameters:
3208-**
3209-** <ul>
3210-** <li> <b>vfs</b>: ^The "vfs" parameter may be used to specify the name of
3211-** a VFS object that provides the operating system interface that should
3212-** be used to access the database file on disk. ^If this option is set to
3213-** an empty string the default VFS object is used. ^Specifying an unknown
3214-** VFS is an error. ^If sqlite3_open_v2() is used and the vfs option is
3215-** present, then the VFS specified by the option takes precedence over
3216-** the value passed as the fourth parameter to sqlite3_open_v2().
3217-**
3218-** <li> <b>mode</b>: ^(The mode parameter may be set to either "ro", "rw",
3219-** "rwc", or "memory". Attempting to set it to any other value is
3220-** an error)^.
3221-** ^If "ro" is specified, then the database is opened for read-only
3222-** access, just as if the [SQLITE_OPEN_READONLY] flag had been set in the
3223-** third argument to sqlite3_open_v2(). ^If the mode option is set to
3224-** "rw", then the database is opened for read-write (but not create)
3225-** access, as if SQLITE_OPEN_READWRITE (but not SQLITE_OPEN_CREATE) had
3226-** been set. ^Value "rwc" is equivalent to setting both
3227-** SQLITE_OPEN_READWRITE and SQLITE_OPEN_CREATE. ^If the mode option is
3228-** set to "memory" then a pure [in-memory database] that never reads
3229-** or writes from disk is used. ^It is an error to specify a value for
3230-** the mode parameter that is less restrictive than that specified by
3231-** the flags passed in the third parameter to sqlite3_open_v2().
3232-**
3233-** <li> <b>cache</b>: ^The cache parameter may be set to either "shared" or
3234-** "private". ^Setting it to "shared" is equivalent to setting the
3235-** SQLITE_OPEN_SHAREDCACHE bit in the flags argument passed to
3236-** sqlite3_open_v2(). ^Setting the cache parameter to "private" is
3237-** equivalent to setting the SQLITE_OPEN_PRIVATECACHE bit.
3238-** ^If sqlite3_open_v2() is used and the "cache" parameter is present in
3239-** a URI filename, its value overrides any behaviour requested by setting
3240-** SQLITE_OPEN_PRIVATECACHE or SQLITE_OPEN_SHAREDCACHE flag.
3241-** </ul>
3242-**
3243-** ^Specifying an unknown parameter in the query component of a URI is not an
3244-** error. Future versions of SQLite might understand additional query
3245-** parameters. See "[query parameters with special meaning to SQLite]" for
3246-** additional information.
3247-**
3248-** [[URI filename examples]] <h3>URI filename examples</h3>
3249-**
3250-** <table border="1" align=center cellpadding=5>
3251-** <tr><th> URI filenames <th> Results
3252-** <tr><td> file:data.db <td>
3253-** Open the file "data.db" in the current directory.
3254-** <tr><td> file:/home/fred/data.db<br>
3255-** file:///home/fred/data.db <br>
3256-** file://localhost/home/fred/data.db <br> <td>
3257-** Open the database file "/home/fred/data.db".
3258-** <tr><td> file://darkstar/home/fred/data.db <td>
3259-** An error. "darkstar" is not a recognized authority.
3260-** <tr><td style="white-space:nowrap">
3261-** file:///C:/Documents%20and%20Settings/fred/Desktop/data.db
3262-** <td> Windows only: Open the file "data.db" on fred's desktop on drive
3263-** C:. Note that the %20 escaping in this example is not strictly
3264-** necessary - space characters can be used literally
3265-** in URI filenames.
3266-** <tr><td> file:data.db?mode=ro&cache=private <td>
3267-** Open file "data.db" in the current directory for read-only access.
3268-** Regardless of whether or not shared-cache mode is enabled by
3269-** default, use a private cache.
3270-** <tr><td> file:/home/fred/data.db?vfs=unix-nolock <td>
3271-** Open file "/home/fred/data.db". Use the special VFS "unix-nolock".
3272-** <tr><td> file:data.db?mode=readonly <td>
3273-** An error. "readonly" is not a valid option for the "mode" parameter.
3274-** </table>
3275-**
3276-** ^URI hexadecimal escape sequences (%HH) are supported within the path and
3277-** query components of a URI. A hexadecimal escape sequence consists of a
3278-** percent sign - "%" - followed by exactly two hexadecimal digits
3279-** specifying an octet value. ^Before the path or query components of a
3280-** URI filename are interpreted, they are encoded using UTF-8 and all
3281-** hexadecimal escape sequences replaced by a single byte containing the
3282-** corresponding octet. If this process generates an invalid UTF-8 encoding,
3283-** the results are undefined.
3284-**
3285-** <b>Note to Windows users:</b> The encoding used for the filename argument
3286-** of sqlite3_open() and sqlite3_open_v2() must be UTF-8, not whatever
3287-** codepage is currently defined. Filenames containing international
3288-** characters must be converted to UTF-8 prior to passing them into
3289-** sqlite3_open() or sqlite3_open_v2().
3290-**
3291-** <b>Note to Windows Runtime users:</b> The temporary directory must be set
3292-** prior to calling sqlite3_open() or sqlite3_open_v2(). Otherwise, various
3293-** features that require the use of temporary files may fail.
3294-**
3295-** See also: [sqlite3_temp_directory]
3296-*/
3297-SQLITE_API int sqlite3_open(
3298- const char *filename, /* Database filename (UTF-8) */
3299- sqlite3 **ppDb /* OUT: SQLite db handle */
3300-);
3301-SQLITE_API int sqlite3_open16(
3302- const void *filename, /* Database filename (UTF-16) */
3303- sqlite3 **ppDb /* OUT: SQLite db handle */
3304-);
3305-SQLITE_API int sqlite3_open_v2(
3306- const char *filename, /* Database filename (UTF-8) */
3307- sqlite3 **ppDb, /* OUT: SQLite db handle */
3308- int flags, /* Flags */
3309- const char *zVfs /* Name of VFS module to use */
3310-);
3311-
3312-/*
3313-** CAPI3REF: Obtain Values For URI Parameters
3314-**
3315-** These are utility routines, useful to VFS implementations, that check
3316-** to see if a database file was a URI that contained a specific query
3317-** parameter, and if so obtains the value of that query parameter.
3318-**
3319-** If F is the database filename pointer passed into the xOpen() method of
3320-** a VFS implementation when the flags parameter to xOpen() has one or
3321-** more of the [SQLITE_OPEN_URI] or [SQLITE_OPEN_MAIN_DB] bits set and
3322-** P is the name of the query parameter, then
3323-** sqlite3_uri_parameter(F,P) returns the value of the P
3324-** parameter if it exists or a NULL pointer if P does not appear as a
3325-** query parameter on F. If P is a query parameter of F
3326-** has no explicit value, then sqlite3_uri_parameter(F,P) returns
3327-** a pointer to an empty string.
3328-**
3329-** The sqlite3_uri_boolean(F,P,B) routine assumes that P is a boolean
3330-** parameter and returns true (1) or false (0) according to the value
3331-** of P. The sqlite3_uri_boolean(F,P,B) routine returns true (1) if the
3332-** value of query parameter P is one of "yes", "true", or "on" in any
3333-** case or if the value begins with a non-zero number. The
3334-** sqlite3_uri_boolean(F,P,B) routines returns false (0) if the value of
3335-** query parameter P is one of "no", "false", or "off" in any case or
3336-** if the value begins with a numeric zero. If P is not a query
3337-** parameter on F or if the value of P is does not match any of the
3338-** above, then sqlite3_uri_boolean(F,P,B) returns (B!=0).
3339-**
3340-** The sqlite3_uri_int64(F,P,D) routine converts the value of P into a
3341-** 64-bit signed integer and returns that integer, or D if P does not
3342-** exist. If the value of P is something other than an integer, then
3343-** zero is returned.
3344-**
3345-** If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL and
3346-** sqlite3_uri_boolean(F,P,B) returns B. If F is not a NULL pointer and
3347-** is not a database file pathname pointer that SQLite passed into the xOpen
3348-** VFS method, then the behavior of this routine is undefined and probably
3349-** undesirable.
3350-*/
3351-SQLITE_API const char *sqlite3_uri_parameter(const char *zFilename, const char *zParam);
3352-SQLITE_API int sqlite3_uri_boolean(const char *zFile, const char *zParam, int bDefault);
3353-SQLITE_API sqlite3_int64 sqlite3_uri_int64(const char*, const char*, sqlite3_int64);
3354-
3355-
3356-/*
3357-** CAPI3REF: Error Codes And Messages
3358-**
3359-** ^The sqlite3_errcode() interface returns the numeric [result code] or
3360-** [extended result code] for the most recent failed sqlite3_* API call
3361-** associated with a [database connection]. If a prior API call failed
3362-** but the most recent API call succeeded, the return value from
3363-** sqlite3_errcode() is undefined. ^The sqlite3_extended_errcode()
3364-** interface is the same except that it always returns the
3365-** [extended result code] even when extended result codes are
3366-** disabled.
3367-**
3368-** ^The sqlite3_errmsg() and sqlite3_errmsg16() return English-language
3369-** text that describes the error, as either UTF-8 or UTF-16 respectively.
3370-** ^(Memory to hold the error message string is managed internally.
3371-** The application does not need to worry about freeing the result.
3372-** However, the error string might be overwritten or deallocated by
3373-** subsequent calls to other SQLite interface functions.)^
3374-**
3375-** ^The sqlite3_errstr() interface returns the English-language text
3376-** that describes the [result code], as UTF-8.
3377-** ^(Memory to hold the error message string is managed internally
3378-** and must not be freed by the application)^.
3379-**
3380-** When the serialized [threading mode] is in use, it might be the
3381-** case that a second error occurs on a separate thread in between
3382-** the time of the first error and the call to these interfaces.
3383-** When that happens, the second error will be reported since these
3384-** interfaces always report the most recent result. To avoid
3385-** this, each thread can obtain exclusive use of the [database connection] D
3386-** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
3387-** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
3388-** all calls to the interfaces listed here are completed.
3389-**
3390-** If an interface fails with SQLITE_MISUSE, that means the interface
3391-** was invoked incorrectly by the application. In that case, the
3392-** error code and message may or may not be set.
3393-*/
3394-SQLITE_API int sqlite3_errcode(sqlite3 *db);
3395-SQLITE_API int sqlite3_extended_errcode(sqlite3 *db);
3396-SQLITE_API const char *sqlite3_errmsg(sqlite3*);
3397-SQLITE_API const void *sqlite3_errmsg16(sqlite3*);
3398-SQLITE_API const char *sqlite3_errstr(int);
3399-
3400-/*
3401-** CAPI3REF: SQL Statement Object
3402-** KEYWORDS: {prepared statement} {prepared statements}
3403-**
3404-** An instance of this object represents a single SQL statement.
3405-** This object is variously known as a "prepared statement" or a
3406-** "compiled SQL statement" or simply as a "statement".
3407-**
3408-** The life of a statement object goes something like this:
3409-**
3410-** <ol>
3411-** <li> Create the object using [sqlite3_prepare_v2()] or a related
3412-** function.
3413-** <li> Bind values to [host parameters] using the sqlite3_bind_*()
3414-** interfaces.
3415-** <li> Run the SQL by calling [sqlite3_step()] one or more times.
3416-** <li> Reset the statement using [sqlite3_reset()] then go back
3417-** to step 2. Do this zero or more times.
3418-** <li> Destroy the object using [sqlite3_finalize()].
3419-** </ol>
3420-**
3421-** Refer to documentation on individual methods above for additional
3422-** information.
3423-*/
3424-typedef struct sqlite3_stmt sqlite3_stmt;
3425-
3426-/*
3427-** CAPI3REF: Run-time Limits
3428-**
3429-** ^(This interface allows the size of various constructs to be limited
3430-** on a connection by connection basis. The first parameter is the
3431-** [database connection] whose limit is to be set or queried. The
3432-** second parameter is one of the [limit categories] that define a
3433-** class of constructs to be size limited. The third parameter is the
3434-** new limit for that construct.)^
3435-**
3436-** ^If the new limit is a negative number, the limit is unchanged.
3437-** ^(For each limit category SQLITE_LIMIT_<i>NAME</i> there is a
3438-** [limits | hard upper bound]
3439-** set at compile-time by a C preprocessor macro called
3440-** [limits | SQLITE_MAX_<i>NAME</i>].
3441-** (The "_LIMIT_" in the name is changed to "_MAX_".))^
3442-** ^Attempts to increase a limit above its hard upper bound are
3443-** silently truncated to the hard upper bound.
3444-**
3445-** ^Regardless of whether or not the limit was changed, the
3446-** [sqlite3_limit()] interface returns the prior value of the limit.
3447-** ^Hence, to find the current value of a limit without changing it,
3448-** simply invoke this interface with the third parameter set to -1.
3449-**
3450-** Run-time limits are intended for use in applications that manage
3451-** both their own internal database and also databases that are controlled
3452-** by untrusted external sources. An example application might be a
3453-** web browser that has its own databases for storing history and
3454-** separate databases controlled by JavaScript applications downloaded
3455-** off the Internet. The internal databases can be given the
3456-** large, default limits. Databases managed by external sources can
3457-** be given much smaller limits designed to prevent a denial of service
3458-** attack. Developers might also want to use the [sqlite3_set_authorizer()]
3459-** interface to further control untrusted SQL. The size of the database
3460-** created by an untrusted script can be contained using the
3461-** [max_page_count] [PRAGMA].
3462-**
3463-** New run-time limit categories may be added in future releases.
3464-*/
3465-SQLITE_API int sqlite3_limit(sqlite3*, int id, int newVal);
3466-
3467-/*
3468-** CAPI3REF: Run-Time Limit Categories
3469-** KEYWORDS: {limit category} {*limit categories}
3470-**
3471-** These constants define various performance limits
3472-** that can be lowered at run-time using [sqlite3_limit()].
3473-** The synopsis of the meanings of the various limits is shown below.
3474-** Additional information is available at [limits | Limits in SQLite].
3475-**
3476-** <dl>
3477-** [[SQLITE_LIMIT_LENGTH]] ^(<dt>SQLITE_LIMIT_LENGTH</dt>
3478-** <dd>The maximum size of any string or BLOB or table row, in bytes.<dd>)^
3479-**
3480-** [[SQLITE_LIMIT_SQL_LENGTH]] ^(<dt>SQLITE_LIMIT_SQL_LENGTH</dt>
3481-** <dd>The maximum length of an SQL statement, in bytes.</dd>)^
3482-**
3483-** [[SQLITE_LIMIT_COLUMN]] ^(<dt>SQLITE_LIMIT_COLUMN</dt>
3484-** <dd>The maximum number of columns in a table definition or in the
3485-** result set of a [SELECT] or the maximum number of columns in an index
3486-** or in an ORDER BY or GROUP BY clause.</dd>)^
3487-**
3488-** [[SQLITE_LIMIT_EXPR_DEPTH]] ^(<dt>SQLITE_LIMIT_EXPR_DEPTH</dt>
3489-** <dd>The maximum depth of the parse tree on any expression.</dd>)^
3490-**
3491-** [[SQLITE_LIMIT_COMPOUND_SELECT]] ^(<dt>SQLITE_LIMIT_COMPOUND_SELECT</dt>
3492-** <dd>The maximum number of terms in a compound SELECT statement.</dd>)^
3493-**
3494-** [[SQLITE_LIMIT_VDBE_OP]] ^(<dt>SQLITE_LIMIT_VDBE_OP</dt>
3495-** <dd>The maximum number of instructions in a virtual machine program
3496-** used to implement an SQL statement. This limit is not currently
3497-** enforced, though that might be added in some future release of
3498-** SQLite.</dd>)^
3499-**
3500-** [[SQLITE_LIMIT_FUNCTION_ARG]] ^(<dt>SQLITE_LIMIT_FUNCTION_ARG</dt>
3501-** <dd>The maximum number of arguments on a function.</dd>)^
3502-**
3503-** [[SQLITE_LIMIT_ATTACHED]] ^(<dt>SQLITE_LIMIT_ATTACHED</dt>
3504-** <dd>The maximum number of [ATTACH | attached databases].)^</dd>
3505-**
3506-** [[SQLITE_LIMIT_LIKE_PATTERN_LENGTH]]
3507-** ^(<dt>SQLITE_LIMIT_LIKE_PATTERN_LENGTH</dt>
3508-** <dd>The maximum length of the pattern argument to the [LIKE] or
3509-** [GLOB] operators.</dd>)^
3510-**
3511-** [[SQLITE_LIMIT_VARIABLE_NUMBER]]
3512-** ^(<dt>SQLITE_LIMIT_VARIABLE_NUMBER</dt>
3513-** <dd>The maximum index number of any [parameter] in an SQL statement.)^
3514-**
3515-** [[SQLITE_LIMIT_TRIGGER_DEPTH]] ^(<dt>SQLITE_LIMIT_TRIGGER_DEPTH</dt>
3516-** <dd>The maximum depth of recursion for triggers.</dd>)^
3517-** </dl>
3518-*/
3519-#define SQLITE_LIMIT_LENGTH 0
3520-#define SQLITE_LIMIT_SQL_LENGTH 1
3521-#define SQLITE_LIMIT_COLUMN 2
3522-#define SQLITE_LIMIT_EXPR_DEPTH 3
3523-#define SQLITE_LIMIT_COMPOUND_SELECT 4
3524-#define SQLITE_LIMIT_VDBE_OP 5
3525-#define SQLITE_LIMIT_FUNCTION_ARG 6
3526-#define SQLITE_LIMIT_ATTACHED 7
3527-#define SQLITE_LIMIT_LIKE_PATTERN_LENGTH 8
3528-#define SQLITE_LIMIT_VARIABLE_NUMBER 9
3529-#define SQLITE_LIMIT_TRIGGER_DEPTH 10
3530-
3531-/*
3532-** CAPI3REF: Compiling An SQL Statement
3533-** KEYWORDS: {SQL statement compiler}
3534-**
3535-** To execute an SQL query, it must first be compiled into a byte-code
3536-** program using one of these routines.
3537-**
3538-** The first argument, "db", is a [database connection] obtained from a
3539-** prior successful call to [sqlite3_open()], [sqlite3_open_v2()] or
3540-** [sqlite3_open16()]. The database connection must not have been closed.
3541-**
3542-** The second argument, "zSql", is the statement to be compiled, encoded
3543-** as either UTF-8 or UTF-16. The sqlite3_prepare() and sqlite3_prepare_v2()
3544-** interfaces use UTF-8, and sqlite3_prepare16() and sqlite3_prepare16_v2()
3545-** use UTF-16.
3546-**
3547-** ^If the nByte argument is less than zero, then zSql is read up to the
3548-** first zero terminator. ^If nByte is non-negative, then it is the maximum
3549-** number of bytes read from zSql. ^When nByte is non-negative, the
3550-** zSql string ends at either the first '\000' or '\u0000' character or
3551-** the nByte-th byte, whichever comes first. If the caller knows
3552-** that the supplied string is nul-terminated, then there is a small
3553-** performance advantage to be gained by passing an nByte parameter that
3554-** is equal to the number of bytes in the input string <i>including</i>
3555-** the nul-terminator bytes as this saves SQLite from having to
3556-** make a copy of the input string.
3557-**
3558-** ^If pzTail is not NULL then *pzTail is made to point to the first byte
3559-** past the end of the first SQL statement in zSql. These routines only
3560-** compile the first statement in zSql, so *pzTail is left pointing to
3561-** what remains uncompiled.
3562-**
3563-** ^*ppStmt is left pointing to a compiled [prepared statement] that can be
3564-** executed using [sqlite3_step()]. ^If there is an error, *ppStmt is set
3565-** to NULL. ^If the input text contains no SQL (if the input is an empty
3566-** string or a comment) then *ppStmt is set to NULL.
3567-** The calling procedure is responsible for deleting the compiled
3568-** SQL statement using [sqlite3_finalize()] after it has finished with it.
3569-** ppStmt may not be NULL.
3570-**
3571-** ^On success, the sqlite3_prepare() family of routines return [SQLITE_OK];
3572-** otherwise an [error code] is returned.
3573-**
3574-** The sqlite3_prepare_v2() and sqlite3_prepare16_v2() interfaces are
3575-** recommended for all new programs. The two older interfaces are retained
3576-** for backwards compatibility, but their use is discouraged.
3577-** ^In the "v2" interfaces, the prepared statement
3578-** that is returned (the [sqlite3_stmt] object) contains a copy of the
3579-** original SQL text. This causes the [sqlite3_step()] interface to
3580-** behave differently in three ways:
3581-**
3582-** <ol>
3583-** <li>
3584-** ^If the database schema changes, instead of returning [SQLITE_SCHEMA] as it
3585-** always used to do, [sqlite3_step()] will automatically recompile the SQL
3586-** statement and try to run it again.
3587-** </li>
3588-**
3589-** <li>
3590-** ^When an error occurs, [sqlite3_step()] will return one of the detailed
3591-** [error codes] or [extended error codes]. ^The legacy behavior was that
3592-** [sqlite3_step()] would only return a generic [SQLITE_ERROR] result code
3593-** and the application would have to make a second call to [sqlite3_reset()]
3594-** in order to find the underlying cause of the problem. With the "v2" prepare
3595-** interfaces, the underlying reason for the error is returned immediately.
3596-** </li>
3597-**
3598-** <li>
3599-** ^If the specific value bound to [parameter | host parameter] in the
3600-** WHERE clause might influence the choice of query plan for a statement,
3601-** then the statement will be automatically recompiled, as if there had been
3602-** a schema change, on the first [sqlite3_step()] call following any change
3603-** to the [sqlite3_bind_text | bindings] of that [parameter].
3604-** ^The specific value of WHERE-clause [parameter] might influence the
3605-** choice of query plan if the parameter is the left-hand side of a [LIKE]
3606-** or [GLOB] operator or if the parameter is compared to an indexed column
3607-** and the [SQLITE_ENABLE_STAT3] compile-time option is enabled.
3608-** the
3609-** </li>
3610-** </ol>
3611-*/
3612-SQLITE_API int sqlite3_prepare(
3613- sqlite3 *db, /* Database handle */
3614- const char *zSql, /* SQL statement, UTF-8 encoded */
3615- int nByte, /* Maximum length of zSql in bytes. */
3616- sqlite3_stmt **ppStmt, /* OUT: Statement handle */
3617- const char **pzTail /* OUT: Pointer to unused portion of zSql */
3618-);
3619-SQLITE_API int sqlite3_prepare_v2(
3620- sqlite3 *db, /* Database handle */
3621- const char *zSql, /* SQL statement, UTF-8 encoded */
3622- int nByte, /* Maximum length of zSql in bytes. */
3623- sqlite3_stmt **ppStmt, /* OUT: Statement handle */
3624- const char **pzTail /* OUT: Pointer to unused portion of zSql */
3625-);
3626-SQLITE_API int sqlite3_prepare16(
3627- sqlite3 *db, /* Database handle */
3628- const void *zSql, /* SQL statement, UTF-16 encoded */
3629- int nByte, /* Maximum length of zSql in bytes. */
3630- sqlite3_stmt **ppStmt, /* OUT: Statement handle */
3631- const void **pzTail /* OUT: Pointer to unused portion of zSql */
3632-);
3633-SQLITE_API int sqlite3_prepare16_v2(
3634- sqlite3 *db, /* Database handle */
3635- const void *zSql, /* SQL statement, UTF-16 encoded */
3636- int nByte, /* Maximum length of zSql in bytes. */
3637- sqlite3_stmt **ppStmt, /* OUT: Statement handle */
3638- const void **pzTail /* OUT: Pointer to unused portion of zSql */
3639-);
3640-
3641-/*
3642-** CAPI3REF: Retrieving Statement SQL
3643-**
3644-** ^This interface can be used to retrieve a saved copy of the original
3645-** SQL text used to create a [prepared statement] if that statement was
3646-** compiled using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()].
3647-*/
3648-SQLITE_API const char *sqlite3_sql(sqlite3_stmt *pStmt);
3649-
3650-/*
3651-** CAPI3REF: Determine If An SQL Statement Writes The Database
3652-**
3653-** ^The sqlite3_stmt_readonly(X) interface returns true (non-zero) if
3654-** and only if the [prepared statement] X makes no direct changes to
3655-** the content of the database file.
3656-**
3657-** Note that [application-defined SQL functions] or
3658-** [virtual tables] might change the database indirectly as a side effect.
3659-** ^(For example, if an application defines a function "eval()" that
3660-** calls [sqlite3_exec()], then the following SQL statement would
3661-** change the database file through side-effects:
3662-**
3663-** <blockquote><pre>
3664-** SELECT eval('DELETE FROM t1') FROM t2;
3665-** </pre></blockquote>
3666-**
3667-** But because the [SELECT] statement does not change the database file
3668-** directly, sqlite3_stmt_readonly() would still return true.)^
3669-**
3670-** ^Transaction control statements such as [BEGIN], [COMMIT], [ROLLBACK],
3671-** [SAVEPOINT], and [RELEASE] cause sqlite3_stmt_readonly() to return true,
3672-** since the statements themselves do not actually modify the database but
3673-** rather they control the timing of when other statements modify the
3674-** database. ^The [ATTACH] and [DETACH] statements also cause
3675-** sqlite3_stmt_readonly() to return true since, while those statements
3676-** change the configuration of a database connection, they do not make
3677-** changes to the content of the database files on disk.
3678-*/
3679-SQLITE_API int sqlite3_stmt_readonly(sqlite3_stmt *pStmt);
3680-
3681-/*
3682-** CAPI3REF: Determine If A Prepared Statement Has Been Reset
3683-**
3684-** ^The sqlite3_stmt_busy(S) interface returns true (non-zero) if the
3685-** [prepared statement] S has been stepped at least once using
3686-** [sqlite3_step(S)] but has not run to completion and/or has not
3687-** been reset using [sqlite3_reset(S)]. ^The sqlite3_stmt_busy(S)
3688-** interface returns false if S is a NULL pointer. If S is not a
3689-** NULL pointer and is not a pointer to a valid [prepared statement]
3690-** object, then the behavior is undefined and probably undesirable.
3691-**
3692-** This interface can be used in combination [sqlite3_next_stmt()]
3693-** to locate all prepared statements associated with a database
3694-** connection that are in need of being reset. This can be used,
3695-** for example, in diagnostic routines to search for prepared
3696-** statements that are holding a transaction open.
3697-*/
3698-SQLITE_API int sqlite3_stmt_busy(sqlite3_stmt*);
3699-
3700-/*
3701-** CAPI3REF: Dynamically Typed Value Object
3702-** KEYWORDS: {protected sqlite3_value} {unprotected sqlite3_value}
3703-**
3704-** SQLite uses the sqlite3_value object to represent all values
3705-** that can be stored in a database table. SQLite uses dynamic typing
3706-** for the values it stores. ^Values stored in sqlite3_value objects
3707-** can be integers, floating point values, strings, BLOBs, or NULL.
3708-**
3709-** An sqlite3_value object may be either "protected" or "unprotected".
3710-** Some interfaces require a protected sqlite3_value. Other interfaces
3711-** will accept either a protected or an unprotected sqlite3_value.
3712-** Every interface that accepts sqlite3_value arguments specifies
3713-** whether or not it requires a protected sqlite3_value.
3714-**
3715-** The terms "protected" and "unprotected" refer to whether or not
3716-** a mutex is held. An internal mutex is held for a protected
3717-** sqlite3_value object but no mutex is held for an unprotected
3718-** sqlite3_value object. If SQLite is compiled to be single-threaded
3719-** (with [SQLITE_THREADSAFE=0] and with [sqlite3_threadsafe()] returning 0)
3720-** or if SQLite is run in one of reduced mutex modes
3721-** [SQLITE_CONFIG_SINGLETHREAD] or [SQLITE_CONFIG_MULTITHREAD]
3722-** then there is no distinction between protected and unprotected
3723-** sqlite3_value objects and they can be used interchangeably. However,
3724-** for maximum code portability it is recommended that applications
3725-** still make the distinction between protected and unprotected
3726-** sqlite3_value objects even when not strictly required.
3727-**
3728-** ^The sqlite3_value objects that are passed as parameters into the
3729-** implementation of [application-defined SQL functions] are protected.
3730-** ^The sqlite3_value object returned by
3731-** [sqlite3_column_value()] is unprotected.
3732-** Unprotected sqlite3_value objects may only be used with
3733-** [sqlite3_result_value()] and [sqlite3_bind_value()].
3734-** The [sqlite3_value_blob | sqlite3_value_type()] family of
3735-** interfaces require protected sqlite3_value objects.
3736-*/
3737-typedef struct Mem sqlite3_value;
3738-
3739-/*
3740-** CAPI3REF: SQL Function Context Object
3741-**
3742-** The context in which an SQL function executes is stored in an
3743-** sqlite3_context object. ^A pointer to an sqlite3_context object
3744-** is always first parameter to [application-defined SQL functions].
3745-** The application-defined SQL function implementation will pass this
3746-** pointer through into calls to [sqlite3_result_int | sqlite3_result()],
3747-** [sqlite3_aggregate_context()], [sqlite3_user_data()],
3748-** [sqlite3_context_db_handle()], [sqlite3_get_auxdata()],
3749-** and/or [sqlite3_set_auxdata()].
3750-*/
3751-typedef struct sqlite3_context sqlite3_context;
3752-
3753-/*
3754-** CAPI3REF: Binding Values To Prepared Statements
3755-** KEYWORDS: {host parameter} {host parameters} {host parameter name}
3756-** KEYWORDS: {SQL parameter} {SQL parameters} {parameter binding}
3757-**
3758-** ^(In the SQL statement text input to [sqlite3_prepare_v2()] and its variants,
3759-** literals may be replaced by a [parameter] that matches one of following
3760-** templates:
3761-**
3762-** <ul>
3763-** <li> ?
3764-** <li> ?NNN
3765-** <li> :VVV
3766-** <li> @VVV
3767-** <li> $VVV
3768-** </ul>
3769-**
3770-** In the templates above, NNN represents an integer literal,
3771-** and VVV represents an alphanumeric identifier.)^ ^The values of these
3772-** parameters (also called "host parameter names" or "SQL parameters")
3773-** can be set using the sqlite3_bind_*() routines defined here.
3774-**
3775-** ^The first argument to the sqlite3_bind_*() routines is always
3776-** a pointer to the [sqlite3_stmt] object returned from
3777-** [sqlite3_prepare_v2()] or its variants.
3778-**
3779-** ^The second argument is the index of the SQL parameter to be set.
3780-** ^The leftmost SQL parameter has an index of 1. ^When the same named
3781-** SQL parameter is used more than once, second and subsequent
3782-** occurrences have the same index as the first occurrence.
3783-** ^The index for named parameters can be looked up using the
3784-** [sqlite3_bind_parameter_index()] API if desired. ^The index
3785-** for "?NNN" parameters is the value of NNN.
3786-** ^The NNN value must be between 1 and the [sqlite3_limit()]
3787-** parameter [SQLITE_LIMIT_VARIABLE_NUMBER] (default value: 999).
3788-**
3789-** ^The third argument is the value to bind to the parameter.
3790-**
3791-** ^(In those routines that have a fourth argument, its value is the
3792-** number of bytes in the parameter. To be clear: the value is the
3793-** number of <u>bytes</u> in the value, not the number of characters.)^
3794-** ^If the fourth parameter to sqlite3_bind_text() or sqlite3_bind_text16()
3795-** is negative, then the length of the string is
3796-** the number of bytes up to the first zero terminator.
3797-** If the fourth parameter to sqlite3_bind_blob() is negative, then
3798-** the behavior is undefined.
3799-** If a non-negative fourth parameter is provided to sqlite3_bind_text()
3800-** or sqlite3_bind_text16() then that parameter must be the byte offset
3801-** where the NUL terminator would occur assuming the string were NUL
3802-** terminated. If any NUL characters occur at byte offsets less than
3803-** the value of the fourth parameter then the resulting string value will
3804-** contain embedded NULs. The result of expressions involving strings
3805-** with embedded NULs is undefined.
3806-**
3807-** ^The fifth argument to sqlite3_bind_blob(), sqlite3_bind_text(), and
3808-** sqlite3_bind_text16() is a destructor used to dispose of the BLOB or
3809-** string after SQLite has finished with it. ^The destructor is called
3810-** to dispose of the BLOB or string even if the call to sqlite3_bind_blob(),
3811-** sqlite3_bind_text(), or sqlite3_bind_text16() fails.
3812-** ^If the fifth argument is
3813-** the special value [SQLITE_STATIC], then SQLite assumes that the
3814-** information is in static, unmanaged space and does not need to be freed.
3815-** ^If the fifth argument has the value [SQLITE_TRANSIENT], then
3816-** SQLite makes its own private copy of the data immediately, before
3817-** the sqlite3_bind_*() routine returns.
3818-**
3819-** ^The sqlite3_bind_zeroblob() routine binds a BLOB of length N that
3820-** is filled with zeroes. ^A zeroblob uses a fixed amount of memory
3821-** (just an integer to hold its size) while it is being processed.
3822-** Zeroblobs are intended to serve as placeholders for BLOBs whose
3823-** content is later written using
3824-** [sqlite3_blob_open | incremental BLOB I/O] routines.
3825-** ^A negative value for the zeroblob results in a zero-length BLOB.
3826-**
3827-** ^If any of the sqlite3_bind_*() routines are called with a NULL pointer
3828-** for the [prepared statement] or with a prepared statement for which
3829-** [sqlite3_step()] has been called more recently than [sqlite3_reset()],
3830-** then the call will return [SQLITE_MISUSE]. If any sqlite3_bind_()
3831-** routine is passed a [prepared statement] that has been finalized, the
3832-** result is undefined and probably harmful.
3833-**
3834-** ^Bindings are not cleared by the [sqlite3_reset()] routine.
3835-** ^Unbound parameters are interpreted as NULL.
3836-**
3837-** ^The sqlite3_bind_* routines return [SQLITE_OK] on success or an
3838-** [error code] if anything goes wrong.
3839-** ^[SQLITE_RANGE] is returned if the parameter
3840-** index is out of range. ^[SQLITE_NOMEM] is returned if malloc() fails.
3841-**
3842-** See also: [sqlite3_bind_parameter_count()],
3843-** [sqlite3_bind_parameter_name()], and [sqlite3_bind_parameter_index()].
3844-*/
3845-SQLITE_API int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
3846-SQLITE_API int sqlite3_bind_double(sqlite3_stmt*, int, double);
3847-SQLITE_API int sqlite3_bind_int(sqlite3_stmt*, int, int);
3848-SQLITE_API int sqlite3_bind_int64(sqlite3_stmt*, int, sqlite3_int64);
3849-SQLITE_API int sqlite3_bind_null(sqlite3_stmt*, int);
3850-SQLITE_API int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
3851-SQLITE_API int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int, void(*)(void*));
3852-SQLITE_API int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
3853-SQLITE_API int sqlite3_bind_zeroblob(sqlite3_stmt*, int, int n);
3854-
3855-/*
3856-** CAPI3REF: Number Of SQL Parameters
3857-**
3858-** ^This routine can be used to find the number of [SQL parameters]
3859-** in a [prepared statement]. SQL parameters are tokens of the
3860-** form "?", "?NNN", ":AAA", "$AAA", or "@AAA" that serve as
3861-** placeholders for values that are [sqlite3_bind_blob | bound]
3862-** to the parameters at a later time.
3863-**
3864-** ^(This routine actually returns the index of the largest (rightmost)
3865-** parameter. For all forms except ?NNN, this will correspond to the
3866-** number of unique parameters. If parameters of the ?NNN form are used,
3867-** there may be gaps in the list.)^
3868-**
3869-** See also: [sqlite3_bind_blob|sqlite3_bind()],
3870-** [sqlite3_bind_parameter_name()], and
3871-** [sqlite3_bind_parameter_index()].
3872-*/
3873-SQLITE_API int sqlite3_bind_parameter_count(sqlite3_stmt*);
3874-
3875-/*
3876-** CAPI3REF: Name Of A Host Parameter
3877-**
3878-** ^The sqlite3_bind_parameter_name(P,N) interface returns
3879-** the name of the N-th [SQL parameter] in the [prepared statement] P.
3880-** ^(SQL parameters of the form "?NNN" or ":AAA" or "@AAA" or "$AAA"
3881-** have a name which is the string "?NNN" or ":AAA" or "@AAA" or "$AAA"
3882-** respectively.
3883-** In other words, the initial ":" or "$" or "@" or "?"
3884-** is included as part of the name.)^
3885-** ^Parameters of the form "?" without a following integer have no name
3886-** and are referred to as "nameless" or "anonymous parameters".
3887-**
3888-** ^The first host parameter has an index of 1, not 0.
3889-**
3890-** ^If the value N is out of range or if the N-th parameter is
3891-** nameless, then NULL is returned. ^The returned string is
3892-** always in UTF-8 encoding even if the named parameter was
3893-** originally specified as UTF-16 in [sqlite3_prepare16()] or
3894-** [sqlite3_prepare16_v2()].
3895-**
3896-** See also: [sqlite3_bind_blob|sqlite3_bind()],
3897-** [sqlite3_bind_parameter_count()], and
3898-** [sqlite3_bind_parameter_index()].
3899-*/
3900-SQLITE_API const char *sqlite3_bind_parameter_name(sqlite3_stmt*, int);
3901-
3902-/*
3903-** CAPI3REF: Index Of A Parameter With A Given Name
3904-**
3905-** ^Return the index of an SQL parameter given its name. ^The
3906-** index value returned is suitable for use as the second
3907-** parameter to [sqlite3_bind_blob|sqlite3_bind()]. ^A zero
3908-** is returned if no matching parameter is found. ^The parameter
3909-** name must be given in UTF-8 even if the original statement
3910-** was prepared from UTF-16 text using [sqlite3_prepare16_v2()].
3911-**
3912-** See also: [sqlite3_bind_blob|sqlite3_bind()],
3913-** [sqlite3_bind_parameter_count()], and
3914-** [sqlite3_bind_parameter_index()].
3915-*/
3916-SQLITE_API int sqlite3_bind_parameter_index(sqlite3_stmt*, const char *zName);
3917-
3918-/*
3919-** CAPI3REF: Reset All Bindings On A Prepared Statement
3920-**
3921-** ^Contrary to the intuition of many, [sqlite3_reset()] does not reset
3922-** the [sqlite3_bind_blob | bindings] on a [prepared statement].
3923-** ^Use this routine to reset all host parameters to NULL.
3924-*/
3925-SQLITE_API int sqlite3_clear_bindings(sqlite3_stmt*);
3926-
3927-/*
3928-** CAPI3REF: Number Of Columns In A Result Set
3929-**
3930-** ^Return the number of columns in the result set returned by the
3931-** [prepared statement]. ^This routine returns 0 if pStmt is an SQL
3932-** statement that does not return data (for example an [UPDATE]).
3933-**
3934-** See also: [sqlite3_data_count()]
3935-*/
3936-SQLITE_API int sqlite3_column_count(sqlite3_stmt *pStmt);
3937-
3938-/*
3939-** CAPI3REF: Column Names In A Result Set
3940-**
3941-** ^These routines return the name assigned to a particular column
3942-** in the result set of a [SELECT] statement. ^The sqlite3_column_name()
3943-** interface returns a pointer to a zero-terminated UTF-8 string
3944-** and sqlite3_column_name16() returns a pointer to a zero-terminated
3945-** UTF-16 string. ^The first parameter is the [prepared statement]
3946-** that implements the [SELECT] statement. ^The second parameter is the
3947-** column number. ^The leftmost column is number 0.
3948-**
3949-** ^The returned string pointer is valid until either the [prepared statement]
3950-** is destroyed by [sqlite3_finalize()] or until the statement is automatically
3951-** reprepared by the first call to [sqlite3_step()] for a particular run
3952-** or until the next call to
3953-** sqlite3_column_name() or sqlite3_column_name16() on the same column.
3954-**
3955-** ^If sqlite3_malloc() fails during the processing of either routine
3956-** (for example during a conversion from UTF-8 to UTF-16) then a
3957-** NULL pointer is returned.
3958-**
3959-** ^The name of a result column is the value of the "AS" clause for
3960-** that column, if there is an AS clause. If there is no AS clause
3961-** then the name of the column is unspecified and may change from
3962-** one release of SQLite to the next.
3963-*/
3964-SQLITE_API const char *sqlite3_column_name(sqlite3_stmt*, int N);
3965-SQLITE_API const void *sqlite3_column_name16(sqlite3_stmt*, int N);
3966-
3967-/*
3968-** CAPI3REF: Source Of Data In A Query Result
3969-**
3970-** ^These routines provide a means to determine the database, table, and
3971-** table column that is the origin of a particular result column in
3972-** [SELECT] statement.
3973-** ^The name of the database or table or column can be returned as
3974-** either a UTF-8 or UTF-16 string. ^The _database_ routines return
3975-** the database name, the _table_ routines return the table name, and
3976-** the origin_ routines return the column name.
3977-** ^The returned string is valid until the [prepared statement] is destroyed
3978-** using [sqlite3_finalize()] or until the statement is automatically
3979-** reprepared by the first call to [sqlite3_step()] for a particular run
3980-** or until the same information is requested
3981-** again in a different encoding.
3982-**
3983-** ^The names returned are the original un-aliased names of the
3984-** database, table, and column.
3985-**
3986-** ^The first argument to these interfaces is a [prepared statement].
3987-** ^These functions return information about the Nth result column returned by
3988-** the statement, where N is the second function argument.
3989-** ^The left-most column is column 0 for these routines.
3990-**
3991-** ^If the Nth column returned by the statement is an expression or
3992-** subquery and is not a column value, then all of these functions return
3993-** NULL. ^These routine might also return NULL if a memory allocation error
3994-** occurs. ^Otherwise, they return the name of the attached database, table,
3995-** or column that query result column was extracted from.
3996-**
3997-** ^As with all other SQLite APIs, those whose names end with "16" return
3998-** UTF-16 encoded strings and the other functions return UTF-8.
3999-**
4000-** ^These APIs are only available if the library was compiled with the
4001-** [SQLITE_ENABLE_COLUMN_METADATA] C-preprocessor symbol.
4002-**
4003-** If two or more threads call one or more of these routines against the same
4004-** prepared statement and column at the same time then the results are
4005-** undefined.
4006-**
4007-** If two or more threads call one or more
4008-** [sqlite3_column_database_name | column metadata interfaces]
4009-** for the same [prepared statement] and result column
4010-** at the same time then the results are undefined.
4011-*/
4012-SQLITE_API const char *sqlite3_column_database_name(sqlite3_stmt*,int);
4013-SQLITE_API const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
4014-SQLITE_API const char *sqlite3_column_table_name(sqlite3_stmt*,int);
4015-SQLITE_API const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
4016-SQLITE_API const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
4017-SQLITE_API const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
4018-
4019-/*
4020-** CAPI3REF: Declared Datatype Of A Query Result
4021-**
4022-** ^(The first parameter is a [prepared statement].
4023-** If this statement is a [SELECT] statement and the Nth column of the
4024-** returned result set of that [SELECT] is a table column (not an
4025-** expression or subquery) then the declared type of the table
4026-** column is returned.)^ ^If the Nth column of the result set is an
4027-** expression or subquery, then a NULL pointer is returned.
4028-** ^The returned string is always UTF-8 encoded.
4029-**
4030-** ^(For example, given the database schema:
4031-**
4032-** CREATE TABLE t1(c1 VARIANT);
4033-**
4034-** and the following statement to be compiled:
4035-**
4036-** SELECT c1 + 1, c1 FROM t1;
4037-**
4038-** this routine would return the string "VARIANT" for the second result
4039-** column (i==1), and a NULL pointer for the first result column (i==0).)^
4040-**
4041-** ^SQLite uses dynamic run-time typing. ^So just because a column
4042-** is declared to contain a particular type does not mean that the
4043-** data stored in that column is of the declared type. SQLite is
4044-** strongly typed, but the typing is dynamic not static. ^Type
4045-** is associated with individual values, not with the containers
4046-** used to hold those values.
4047-*/
4048-SQLITE_API const char *sqlite3_column_decltype(sqlite3_stmt*,int);
4049-SQLITE_API const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
4050-
4051-/*
4052-** CAPI3REF: Evaluate An SQL Statement
4053-**
4054-** After a [prepared statement] has been prepared using either
4055-** [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or one of the legacy
4056-** interfaces [sqlite3_prepare()] or [sqlite3_prepare16()], this function
4057-** must be called one or more times to evaluate the statement.
4058-**
4059-** The details of the behavior of the sqlite3_step() interface depend
4060-** on whether the statement was prepared using the newer "v2" interface
4061-** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
4062-** interface [sqlite3_prepare()] and [sqlite3_prepare16()]. The use of the
4063-** new "v2" interface is recommended for new applications but the legacy
4064-** interface will continue to be supported.
4065-**
4066-** ^In the legacy interface, the return value will be either [SQLITE_BUSY],
4067-** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
4068-** ^With the "v2" interface, any of the other [result codes] or
4069-** [extended result codes] might be returned as well.
4070-**
4071-** ^[SQLITE_BUSY] means that the database engine was unable to acquire the
4072-** database locks it needs to do its job. ^If the statement is a [COMMIT]
4073-** or occurs outside of an explicit transaction, then you can retry the
4074-** statement. If the statement is not a [COMMIT] and occurs within an
4075-** explicit transaction then you should rollback the transaction before
4076-** continuing.
4077-**
4078-** ^[SQLITE_DONE] means that the statement has finished executing
4079-** successfully. sqlite3_step() should not be called again on this virtual
4080-** machine without first calling [sqlite3_reset()] to reset the virtual
4081-** machine back to its initial state.
4082-**
4083-** ^If the SQL statement being executed returns any data, then [SQLITE_ROW]
4084-** is returned each time a new row of data is ready for processing by the
4085-** caller. The values may be accessed using the [column access functions].
4086-** sqlite3_step() is called again to retrieve the next row of data.
4087-**
4088-** ^[SQLITE_ERROR] means that a run-time error (such as a constraint
4089-** violation) has occurred. sqlite3_step() should not be called again on
4090-** the VM. More information may be found by calling [sqlite3_errmsg()].
4091-** ^With the legacy interface, a more specific error code (for example,
4092-** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
4093-** can be obtained by calling [sqlite3_reset()] on the
4094-** [prepared statement]. ^In the "v2" interface,
4095-** the more specific error code is returned directly by sqlite3_step().
4096-**
4097-** [SQLITE_MISUSE] means that the this routine was called inappropriately.
4098-** Perhaps it was called on a [prepared statement] that has
4099-** already been [sqlite3_finalize | finalized] or on one that had
4100-** previously returned [SQLITE_ERROR] or [SQLITE_DONE]. Or it could
4101-** be the case that the same database connection is being used by two or
4102-** more threads at the same moment in time.
4103-**
4104-** For all versions of SQLite up to and including 3.6.23.1, a call to
4105-** [sqlite3_reset()] was required after sqlite3_step() returned anything
4106-** other than [SQLITE_ROW] before any subsequent invocation of
4107-** sqlite3_step(). Failure to reset the prepared statement using
4108-** [sqlite3_reset()] would result in an [SQLITE_MISUSE] return from
4109-** sqlite3_step(). But after version 3.6.23.1, sqlite3_step() began
4110-** calling [sqlite3_reset()] automatically in this circumstance rather
4111-** than returning [SQLITE_MISUSE]. This is not considered a compatibility
4112-** break because any application that ever receives an SQLITE_MISUSE error
4113-** is broken by definition. The [SQLITE_OMIT_AUTORESET] compile-time option
4114-** can be used to restore the legacy behavior.
4115-**
4116-** <b>Goofy Interface Alert:</b> In the legacy interface, the sqlite3_step()
4117-** API always returns a generic error code, [SQLITE_ERROR], following any
4118-** error other than [SQLITE_BUSY] and [SQLITE_MISUSE]. You must call
4119-** [sqlite3_reset()] or [sqlite3_finalize()] in order to find one of the
4120-** specific [error codes] that better describes the error.
4121-** We admit that this is a goofy design. The problem has been fixed
4122-** with the "v2" interface. If you prepare all of your SQL statements
4123-** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
4124-** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()] interfaces,
4125-** then the more specific [error codes] are returned directly
4126-** by sqlite3_step(). The use of the "v2" interface is recommended.
4127-*/
4128-SQLITE_API int sqlite3_step(sqlite3_stmt*);
4129-
4130-/*
4131-** CAPI3REF: Number of columns in a result set
4132-**
4133-** ^The sqlite3_data_count(P) interface returns the number of columns in the
4134-** current row of the result set of [prepared statement] P.
4135-** ^If prepared statement P does not have results ready to return
4136-** (via calls to the [sqlite3_column_int | sqlite3_column_*()] of
4137-** interfaces) then sqlite3_data_count(P) returns 0.
4138-** ^The sqlite3_data_count(P) routine also returns 0 if P is a NULL pointer.
4139-** ^The sqlite3_data_count(P) routine returns 0 if the previous call to
4140-** [sqlite3_step](P) returned [SQLITE_DONE]. ^The sqlite3_data_count(P)
4141-** will return non-zero if previous call to [sqlite3_step](P) returned
4142-** [SQLITE_ROW], except in the case of the [PRAGMA incremental_vacuum]
4143-** where it always returns zero since each step of that multi-step
4144-** pragma returns 0 columns of data.
4145-**
4146-** See also: [sqlite3_column_count()]
4147-*/
4148-SQLITE_API int sqlite3_data_count(sqlite3_stmt *pStmt);
4149-
4150-/*
4151-** CAPI3REF: Fundamental Datatypes
4152-** KEYWORDS: SQLITE_TEXT
4153-**
4154-** ^(Every value in SQLite has one of five fundamental datatypes:
4155-**
4156-** <ul>
4157-** <li> 64-bit signed integer
4158-** <li> 64-bit IEEE floating point number
4159-** <li> string
4160-** <li> BLOB
4161-** <li> NULL
4162-** </ul>)^
4163-**
4164-** These constants are codes for each of those types.
4165-**
4166-** Note that the SQLITE_TEXT constant was also used in SQLite version 2
4167-** for a completely different meaning. Software that links against both
4168-** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT, not
4169-** SQLITE_TEXT.
4170-*/
4171-#define SQLITE_INTEGER 1
4172-#define SQLITE_FLOAT 2
4173-#define SQLITE_BLOB 4
4174-#define SQLITE_NULL 5
4175-#ifdef SQLITE_TEXT
4176-# undef SQLITE_TEXT
4177-#else
4178-# define SQLITE_TEXT 3
4179-#endif
4180-#define SQLITE3_TEXT 3
4181-
4182-/*
4183-** CAPI3REF: Result Values From A Query
4184-** KEYWORDS: {column access functions}
4185-**
4186-** These routines form the "result set" interface.
4187-**
4188-** ^These routines return information about a single column of the current
4189-** result row of a query. ^In every case the first argument is a pointer
4190-** to the [prepared statement] that is being evaluated (the [sqlite3_stmt*]
4191-** that was returned from [sqlite3_prepare_v2()] or one of its variants)
4192-** and the second argument is the index of the column for which information
4193-** should be returned. ^The leftmost column of the result set has the index 0.
4194-** ^The number of columns in the result can be determined using
4195-** [sqlite3_column_count()].
4196-**
4197-** If the SQL statement does not currently point to a valid row, or if the
4198-** column index is out of range, the result is undefined.
4199-** These routines may only be called when the most recent call to
4200-** [sqlite3_step()] has returned [SQLITE_ROW] and neither
4201-** [sqlite3_reset()] nor [sqlite3_finalize()] have been called subsequently.
4202-** If any of these routines are called after [sqlite3_reset()] or
4203-** [sqlite3_finalize()] or after [sqlite3_step()] has returned
4204-** something other than [SQLITE_ROW], the results are undefined.
4205-** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
4206-** are called from a different thread while any of these routines
4207-** are pending, then the results are undefined.
4208-**
4209-** ^The sqlite3_column_type() routine returns the
4210-** [SQLITE_INTEGER | datatype code] for the initial data type
4211-** of the result column. ^The returned value is one of [SQLITE_INTEGER],
4212-** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL]. The value
4213-** returned by sqlite3_column_type() is only meaningful if no type
4214-** conversions have occurred as described below. After a type conversion,
4215-** the value returned by sqlite3_column_type() is undefined. Future
4216-** versions of SQLite may change the behavior of sqlite3_column_type()
4217-** following a type conversion.
4218-**
4219-** ^If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()
4220-** routine returns the number of bytes in that BLOB or string.
4221-** ^If the result is a UTF-16 string, then sqlite3_column_bytes() converts
4222-** the string to UTF-8 and then returns the number of bytes.
4223-** ^If the result is a numeric value then sqlite3_column_bytes() uses
4224-** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
4225-** the number of bytes in that string.
4226-** ^If the result is NULL, then sqlite3_column_bytes() returns zero.
4227-**
4228-** ^If the result is a BLOB or UTF-16 string then the sqlite3_column_bytes16()
4229-** routine returns the number of bytes in that BLOB or string.
4230-** ^If the result is a UTF-8 string, then sqlite3_column_bytes16() converts
4231-** the string to UTF-16 and then returns the number of bytes.
4232-** ^If the result is a numeric value then sqlite3_column_bytes16() uses
4233-** [sqlite3_snprintf()] to convert that value to a UTF-16 string and returns
4234-** the number of bytes in that string.
4235-** ^If the result is NULL, then sqlite3_column_bytes16() returns zero.
4236-**
4237-** ^The values returned by [sqlite3_column_bytes()] and
4238-** [sqlite3_column_bytes16()] do not include the zero terminators at the end
4239-** of the string. ^For clarity: the values returned by
4240-** [sqlite3_column_bytes()] and [sqlite3_column_bytes16()] are the number of
4241-** bytes in the string, not the number of characters.
4242-**
4243-** ^Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
4244-** even empty strings, are always zero-terminated. ^The return
4245-** value from sqlite3_column_blob() for a zero-length BLOB is a NULL pointer.
4246-**
4247-** ^The object returned by [sqlite3_column_value()] is an
4248-** [unprotected sqlite3_value] object. An unprotected sqlite3_value object
4249-** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
4250-** If the [unprotected sqlite3_value] object returned by
4251-** [sqlite3_column_value()] is used in any other way, including calls
4252-** to routines like [sqlite3_value_int()], [sqlite3_value_text()],
4253-** or [sqlite3_value_bytes()], then the behavior is undefined.
4254-**
4255-** These routines attempt to convert the value where appropriate. ^For
4256-** example, if the internal representation is FLOAT and a text result
4257-** is requested, [sqlite3_snprintf()] is used internally to perform the
4258-** conversion automatically. ^(The following table details the conversions
4259-** that are applied:
4260-**
4261-** <blockquote>
4262-** <table border="1">
4263-** <tr><th> Internal<br>Type <th> Requested<br>Type <th> Conversion
4264-**
4265-** <tr><td> NULL <td> INTEGER <td> Result is 0
4266-** <tr><td> NULL <td> FLOAT <td> Result is 0.0
4267-** <tr><td> NULL <td> TEXT <td> Result is NULL pointer
4268-** <tr><td> NULL <td> BLOB <td> Result is NULL pointer
4269-** <tr><td> INTEGER <td> FLOAT <td> Convert from integer to float
4270-** <tr><td> INTEGER <td> TEXT <td> ASCII rendering of the integer
4271-** <tr><td> INTEGER <td> BLOB <td> Same as INTEGER->TEXT
4272-** <tr><td> FLOAT <td> INTEGER <td> Convert from float to integer
4273-** <tr><td> FLOAT <td> TEXT <td> ASCII rendering of the float
4274-** <tr><td> FLOAT <td> BLOB <td> Same as FLOAT->TEXT
4275-** <tr><td> TEXT <td> INTEGER <td> Use atoi()
4276-** <tr><td> TEXT <td> FLOAT <td> Use atof()
4277-** <tr><td> TEXT <td> BLOB <td> No change
4278-** <tr><td> BLOB <td> INTEGER <td> Convert to TEXT then use atoi()
4279-** <tr><td> BLOB <td> FLOAT <td> Convert to TEXT then use atof()
4280-** <tr><td> BLOB <td> TEXT <td> Add a zero terminator if needed
4281-** </table>
4282-** </blockquote>)^
4283-**
4284-** The table above makes reference to standard C library functions atoi()
4285-** and atof(). SQLite does not really use these functions. It has its
4286-** own equivalent internal routines. The atoi() and atof() names are
4287-** used in the table for brevity and because they are familiar to most
4288-** C programmers.
4289-**
4290-** Note that when type conversions occur, pointers returned by prior
4291-** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
4292-** sqlite3_column_text16() may be invalidated.
4293-** Type conversions and pointer invalidations might occur
4294-** in the following cases:
4295-**
4296-** <ul>
4297-** <li> The initial content is a BLOB and sqlite3_column_text() or
4298-** sqlite3_column_text16() is called. A zero-terminator might
4299-** need to be added to the string.</li>
4300-** <li> The initial content is UTF-8 text and sqlite3_column_bytes16() or
4301-** sqlite3_column_text16() is called. The content must be converted
4302-** to UTF-16.</li>
4303-** <li> The initial content is UTF-16 text and sqlite3_column_bytes() or
4304-** sqlite3_column_text() is called. The content must be converted
4305-** to UTF-8.</li>
4306-** </ul>
4307-**
4308-** ^Conversions between UTF-16be and UTF-16le are always done in place and do
4309-** not invalidate a prior pointer, though of course the content of the buffer
4310-** that the prior pointer references will have been modified. Other kinds
4311-** of conversion are done in place when it is possible, but sometimes they
4312-** are not possible and in those cases prior pointers are invalidated.
4313-**
4314-** The safest and easiest to remember policy is to invoke these routines
4315-** in one of the following ways:
4316-**
4317-** <ul>
4318-** <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
4319-** <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
4320-** <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
4321-** </ul>
4322-**
4323-** In other words, you should call sqlite3_column_text(),
4324-** sqlite3_column_blob(), or sqlite3_column_text16() first to force the result
4325-** into the desired format, then invoke sqlite3_column_bytes() or
4326-** sqlite3_column_bytes16() to find the size of the result. Do not mix calls
4327-** to sqlite3_column_text() or sqlite3_column_blob() with calls to
4328-** sqlite3_column_bytes16(), and do not mix calls to sqlite3_column_text16()
4329-** with calls to sqlite3_column_bytes().
4330-**
4331-** ^The pointers returned are valid until a type conversion occurs as
4332-** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
4333-** [sqlite3_finalize()] is called. ^The memory space used to hold strings
4334-** and BLOBs is freed automatically. Do <b>not</b> pass the pointers returned
4335-** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into
4336-** [sqlite3_free()].
4337-**
4338-** ^(If a memory allocation error occurs during the evaluation of any
4339-** of these routines, a default value is returned. The default value
4340-** is either the integer 0, the floating point number 0.0, or a NULL
4341-** pointer. Subsequent calls to [sqlite3_errcode()] will return
4342-** [SQLITE_NOMEM].)^
4343-*/
4344-SQLITE_API const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
4345-SQLITE_API int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
4346-SQLITE_API int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
4347-SQLITE_API double sqlite3_column_double(sqlite3_stmt*, int iCol);
4348-SQLITE_API int sqlite3_column_int(sqlite3_stmt*, int iCol);
4349-SQLITE_API sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
4350-SQLITE_API const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
4351-SQLITE_API const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
4352-SQLITE_API int sqlite3_column_type(sqlite3_stmt*, int iCol);
4353-SQLITE_API sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
4354-
4355-/*
4356-** CAPI3REF: Destroy A Prepared Statement Object
4357-**
4358-** ^The sqlite3_finalize() function is called to delete a [prepared statement].
4359-** ^If the most recent evaluation of the statement encountered no errors
4360-** or if the statement is never been evaluated, then sqlite3_finalize() returns
4361-** SQLITE_OK. ^If the most recent evaluation of statement S failed, then
4362-** sqlite3_finalize(S) returns the appropriate [error code] or
4363-** [extended error code].
4364-**
4365-** ^The sqlite3_finalize(S) routine can be called at any point during
4366-** the life cycle of [prepared statement] S:
4367-** before statement S is ever evaluated, after
4368-** one or more calls to [sqlite3_reset()], or after any call
4369-** to [sqlite3_step()] regardless of whether or not the statement has
4370-** completed execution.
4371-**
4372-** ^Invoking sqlite3_finalize() on a NULL pointer is a harmless no-op.
4373-**
4374-** The application must finalize every [prepared statement] in order to avoid
4375-** resource leaks. It is a grievous error for the application to try to use
4376-** a prepared statement after it has been finalized. Any use of a prepared
4377-** statement after it has been finalized can result in undefined and
4378-** undesirable behavior such as segfaults and heap corruption.
4379-*/
4380-SQLITE_API int sqlite3_finalize(sqlite3_stmt *pStmt);
4381-
4382-/*
4383-** CAPI3REF: Reset A Prepared Statement Object
4384-**
4385-** The sqlite3_reset() function is called to reset a [prepared statement]
4386-** object back to its initial state, ready to be re-executed.
4387-** ^Any SQL statement variables that had values bound to them using
4388-** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
4389-** Use [sqlite3_clear_bindings()] to reset the bindings.
4390-**
4391-** ^The [sqlite3_reset(S)] interface resets the [prepared statement] S
4392-** back to the beginning of its program.
4393-**
4394-** ^If the most recent call to [sqlite3_step(S)] for the
4395-** [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
4396-** or if [sqlite3_step(S)] has never before been called on S,
4397-** then [sqlite3_reset(S)] returns [SQLITE_OK].
4398-**
4399-** ^If the most recent call to [sqlite3_step(S)] for the
4400-** [prepared statement] S indicated an error, then
4401-** [sqlite3_reset(S)] returns an appropriate [error code].
4402-**
4403-** ^The [sqlite3_reset(S)] interface does not change the values
4404-** of any [sqlite3_bind_blob|bindings] on the [prepared statement] S.
4405-*/
4406-SQLITE_API int sqlite3_reset(sqlite3_stmt *pStmt);
4407-
4408-/*
4409-** CAPI3REF: Create Or Redefine SQL Functions
4410-** KEYWORDS: {function creation routines}
4411-** KEYWORDS: {application-defined SQL function}
4412-** KEYWORDS: {application-defined SQL functions}
4413-**
4414-** ^These functions (collectively known as "function creation routines")
4415-** are used to add SQL functions or aggregates or to redefine the behavior
4416-** of existing SQL functions or aggregates. The only differences between
4417-** these routines are the text encoding expected for
4418-** the second parameter (the name of the function being created)
4419-** and the presence or absence of a destructor callback for
4420-** the application data pointer.
4421-**
4422-** ^The first parameter is the [database connection] to which the SQL
4423-** function is to be added. ^If an application uses more than one database
4424-** connection then application-defined SQL functions must be added
4425-** to each database connection separately.
4426-**
4427-** ^The second parameter is the name of the SQL function to be created or
4428-** redefined. ^The length of the name is limited to 255 bytes in a UTF-8
4429-** representation, exclusive of the zero-terminator. ^Note that the name
4430-** length limit is in UTF-8 bytes, not characters nor UTF-16 bytes.
4431-** ^Any attempt to create a function with a longer name
4432-** will result in [SQLITE_MISUSE] being returned.
4433-**
4434-** ^The third parameter (nArg)
4435-** is the number of arguments that the SQL function or
4436-** aggregate takes. ^If this parameter is -1, then the SQL function or
4437-** aggregate may take any number of arguments between 0 and the limit
4438-** set by [sqlite3_limit]([SQLITE_LIMIT_FUNCTION_ARG]). If the third
4439-** parameter is less than -1 or greater than 127 then the behavior is
4440-** undefined.
4441-**
4442-** ^The fourth parameter, eTextRep, specifies what
4443-** [SQLITE_UTF8 | text encoding] this SQL function prefers for
4444-** its parameters. Every SQL function implementation must be able to work
4445-** with UTF-8, UTF-16le, or UTF-16be. But some implementations may be
4446-** more efficient with one encoding than another. ^An application may
4447-** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
4448-** times with the same function but with different values of eTextRep.
4449-** ^When multiple implementations of the same function are available, SQLite
4450-** will pick the one that involves the least amount of data conversion.
4451-** If there is only a single implementation which does not care what text
4452-** encoding is used, then the fourth argument should be [SQLITE_ANY].
4453-**
4454-** ^(The fifth parameter is an arbitrary pointer. The implementation of the
4455-** function can gain access to this pointer using [sqlite3_user_data()].)^
4456-**
4457-** ^The sixth, seventh and eighth parameters, xFunc, xStep and xFinal, are
4458-** pointers to C-language functions that implement the SQL function or
4459-** aggregate. ^A scalar SQL function requires an implementation of the xFunc
4460-** callback only; NULL pointers must be passed as the xStep and xFinal
4461-** parameters. ^An aggregate SQL function requires an implementation of xStep
4462-** and xFinal and NULL pointer must be passed for xFunc. ^To delete an existing
4463-** SQL function or aggregate, pass NULL pointers for all three function
4464-** callbacks.
4465-**
4466-** ^(If the ninth parameter to sqlite3_create_function_v2() is not NULL,
4467-** then it is destructor for the application data pointer.
4468-** The destructor is invoked when the function is deleted, either by being
4469-** overloaded or when the database connection closes.)^
4470-** ^The destructor is also invoked if the call to
4471-** sqlite3_create_function_v2() fails.
4472-** ^When the destructor callback of the tenth parameter is invoked, it
4473-** is passed a single argument which is a copy of the application data
4474-** pointer which was the fifth parameter to sqlite3_create_function_v2().
4475-**
4476-** ^It is permitted to register multiple implementations of the same
4477-** functions with the same name but with either differing numbers of
4478-** arguments or differing preferred text encodings. ^SQLite will use
4479-** the implementation that most closely matches the way in which the
4480-** SQL function is used. ^A function implementation with a non-negative
4481-** nArg parameter is a better match than a function implementation with
4482-** a negative nArg. ^A function where the preferred text encoding
4483-** matches the database encoding is a better
4484-** match than a function where the encoding is different.
4485-** ^A function where the encoding difference is between UTF16le and UTF16be
4486-** is a closer match than a function where the encoding difference is
4487-** between UTF8 and UTF16.
4488-**
4489-** ^Built-in functions may be overloaded by new application-defined functions.
4490-**
4491-** ^An application-defined function is permitted to call other
4492-** SQLite interfaces. However, such calls must not
4493-** close the database connection nor finalize or reset the prepared
4494-** statement in which the function is running.
4495-*/
4496-SQLITE_API int sqlite3_create_function(
4497- sqlite3 *db,
4498- const char *zFunctionName,
4499- int nArg,
4500- int eTextRep,
4501- void *pApp,
4502- void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
4503- void (*xStep)(sqlite3_context*,int,sqlite3_value**),
4504- void (*xFinal)(sqlite3_context*)
4505-);
4506-SQLITE_API int sqlite3_create_function16(
4507- sqlite3 *db,
4508- const void *zFunctionName,
4509- int nArg,
4510- int eTextRep,
4511- void *pApp,
4512- void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
4513- void (*xStep)(sqlite3_context*,int,sqlite3_value**),
4514- void (*xFinal)(sqlite3_context*)
4515-);
4516-SQLITE_API int sqlite3_create_function_v2(
4517- sqlite3 *db,
4518- const char *zFunctionName,
4519- int nArg,
4520- int eTextRep,
4521- void *pApp,
4522- void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
4523- void (*xStep)(sqlite3_context*,int,sqlite3_value**),
4524- void (*xFinal)(sqlite3_context*),
4525- void(*xDestroy)(void*)
4526-);
4527-
4528-/*
4529-** CAPI3REF: Text Encodings
4530-**
4531-** These constant define integer codes that represent the various
4532-** text encodings supported by SQLite.
4533-*/
4534-#define SQLITE_UTF8 1
4535-#define SQLITE_UTF16LE 2
4536-#define SQLITE_UTF16BE 3
4537-#define SQLITE_UTF16 4 /* Use native byte order */
4538-#define SQLITE_ANY 5 /* sqlite3_create_function only */
4539-#define SQLITE_UTF16_ALIGNED 8 /* sqlite3_create_collation only */
4540-
4541-/*
4542-** CAPI3REF: Deprecated Functions
4543-** DEPRECATED
4544-**
4545-** These functions are [deprecated]. In order to maintain
4546-** backwards compatibility with older code, these functions continue
4547-** to be supported. However, new applications should avoid
4548-** the use of these functions. To help encourage people to avoid
4549-** using these functions, we are not going to tell you what they do.
4550-*/
4551-#ifndef SQLITE_OMIT_DEPRECATED
4552-SQLITE_API SQLITE_DEPRECATED int sqlite3_aggregate_count(sqlite3_context*);
4553-SQLITE_API SQLITE_DEPRECATED int sqlite3_expired(sqlite3_stmt*);
4554-SQLITE_API SQLITE_DEPRECATED int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
4555-SQLITE_API SQLITE_DEPRECATED int sqlite3_global_recover(void);
4556-SQLITE_API SQLITE_DEPRECATED void sqlite3_thread_cleanup(void);
4557-SQLITE_API SQLITE_DEPRECATED int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
4558-#endif
4559-
4560-/*
4561-** CAPI3REF: Obtaining SQL Function Parameter Values
4562-**
4563-** The C-language implementation of SQL functions and aggregates uses
4564-** this set of interface routines to access the parameter values on
4565-** the function or aggregate.
4566-**
4567-** The xFunc (for scalar functions) or xStep (for aggregates) parameters
4568-** to [sqlite3_create_function()] and [sqlite3_create_function16()]
4569-** define callbacks that implement the SQL functions and aggregates.
4570-** The 3rd parameter to these callbacks is an array of pointers to
4571-** [protected sqlite3_value] objects. There is one [sqlite3_value] object for
4572-** each parameter to the SQL function. These routines are used to
4573-** extract values from the [sqlite3_value] objects.
4574-**
4575-** These routines work only with [protected sqlite3_value] objects.
4576-** Any attempt to use these routines on an [unprotected sqlite3_value]
4577-** object results in undefined behavior.
4578-**
4579-** ^These routines work just like the corresponding [column access functions]
4580-** except that these routines take a single [protected sqlite3_value] object
4581-** pointer instead of a [sqlite3_stmt*] pointer and an integer column number.
4582-**
4583-** ^The sqlite3_value_text16() interface extracts a UTF-16 string
4584-** in the native byte-order of the host machine. ^The
4585-** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
4586-** extract UTF-16 strings as big-endian and little-endian respectively.
4587-**
4588-** ^(The sqlite3_value_numeric_type() interface attempts to apply
4589-** numeric affinity to the value. This means that an attempt is
4590-** made to convert the value to an integer or floating point. If
4591-** such a conversion is possible without loss of information (in other
4592-** words, if the value is a string that looks like a number)
4593-** then the conversion is performed. Otherwise no conversion occurs.
4594-** The [SQLITE_INTEGER | datatype] after conversion is returned.)^
4595-**
4596-** Please pay particular attention to the fact that the pointer returned
4597-** from [sqlite3_value_blob()], [sqlite3_value_text()], or
4598-** [sqlite3_value_text16()] can be invalidated by a subsequent call to
4599-** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
4600-** or [sqlite3_value_text16()].
4601-**
4602-** These routines must be called from the same thread as
4603-** the SQL function that supplied the [sqlite3_value*] parameters.
4604-*/
4605-SQLITE_API const void *sqlite3_value_blob(sqlite3_value*);
4606-SQLITE_API int sqlite3_value_bytes(sqlite3_value*);
4607-SQLITE_API int sqlite3_value_bytes16(sqlite3_value*);
4608-SQLITE_API double sqlite3_value_double(sqlite3_value*);
4609-SQLITE_API int sqlite3_value_int(sqlite3_value*);
4610-SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
4611-SQLITE_API const unsigned char *sqlite3_value_text(sqlite3_value*);
4612-SQLITE_API const void *sqlite3_value_text16(sqlite3_value*);
4613-SQLITE_API const void *sqlite3_value_text16le(sqlite3_value*);
4614-SQLITE_API const void *sqlite3_value_text16be(sqlite3_value*);
4615-SQLITE_API int sqlite3_value_type(sqlite3_value*);
4616-SQLITE_API int sqlite3_value_numeric_type(sqlite3_value*);
4617-
4618-/*
4619-** CAPI3REF: Obtain Aggregate Function Context
4620-**
4621-** Implementations of aggregate SQL functions use this
4622-** routine to allocate memory for storing their state.
4623-**
4624-** ^The first time the sqlite3_aggregate_context(C,N) routine is called
4625-** for a particular aggregate function, SQLite
4626-** allocates N of memory, zeroes out that memory, and returns a pointer
4627-** to the new memory. ^On second and subsequent calls to
4628-** sqlite3_aggregate_context() for the same aggregate function instance,
4629-** the same buffer is returned. Sqlite3_aggregate_context() is normally
4630-** called once for each invocation of the xStep callback and then one
4631-** last time when the xFinal callback is invoked. ^(When no rows match
4632-** an aggregate query, the xStep() callback of the aggregate function
4633-** implementation is never called and xFinal() is called exactly once.
4634-** In those cases, sqlite3_aggregate_context() might be called for the
4635-** first time from within xFinal().)^