0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 ** This file is
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20 an amalgamation
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65 of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20 C source files
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76 from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 32 35 2e 33 2e 20 20 ersion 3.25.3.
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20 the individual
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74 C code files int
00e0: 6f 20 74 68 69 73 0a 2a 2a 20 73 69 6e 67 6c 65 o this.** single
00f0: 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 65 large file, the
0100: 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 6e entire code can
0110: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 20 be compiled as
0120: 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c 61 a single transla
0130: 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 54 tion.** unit. T
0140: 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 20 his allows many
0150: 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f 20 compilers to do
0160: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 68 optimizations th
0170: 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 0a at would not be.
0180: 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 74 ** possible if t
0190: 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 6f he files were co
01a0: 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 6c mpiled separatel
01b0: 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 20 y. Performance
01c0: 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a 20 improvements.**
01d0: 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 72 of 5% or more ar
01e0: 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e 20 e commonly seen
01f0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
0200: 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 6e ompiled as a sin
0210: 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 69 gle.** translati
0220: 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 54 on unit..**.** T
0230: 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c 20 his file is all
0240: 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d 70 you need to comp
0250: 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f 20 ile SQLite. To
0260: 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f 74 use SQLite in ot
0270: 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 2c her.** programs,
0280: 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 66 you need this f
0290: 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 6c ile and the "sql
02a0: 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 66 ite3.h" header f
02b0: 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 73 ile that defines
02c0: 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d 6d .** the programm
02d0: 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 6f ing interface to
02e0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 the SQLite libr
02f0: 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 6f ary. (If you do
0300: 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 74 68 65 not have.** the
0310: 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 65 61 "sqlite3.h" hea
0320: 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 6e 64 der file at hand
0330: 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e 64 20 , you will find
0340: 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 64 20 a copy embedded
0350: 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 74 65 within.** the te
0360: 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c 65 2e xt of this file.
0370: 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 42 65 Search for "Be
0380: 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 33 gin file sqlite3
0390: 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 65 20 .h" to find the
03a0: 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20 start.** of the
03b0: 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 65 33 embedded sqlite3
03c0: 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 2e 29 .h header file.)
03d0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f 64 65 Additional code
03e0: 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 6e 65 files may be ne
03f0: 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 20 77 eded.** if you w
0400: 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 74 6f ant a wrapper to
0410: 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c 69 74 interface SQLit
0420: 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 6f 69 e with your choi
0430: 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d 69 6e ce of programmin
0440: 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e 20 54 g.** language. T
0450: 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65 20 he code for the
0460: 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d 61 6e "sqlite3" comman
0470: 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 73 20 d-line shell is
0480: 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 65 70 also in a.** sep
0490: 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 69 73 arate file. This
04a0: 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 6f file contains o
04b0: 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 68 65 nly code for the
04c0: 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c 69 62 core SQLite lib
04d0: 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 rary..*/.#define
04e0: 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 0a 23 SQLITE_CORE 1.#
04f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4d define SQLITE_AM
0500: 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 69 66 ALGAMATION 1.#if
0510: 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 49 56 ndef SQLITE_PRIV
0520: 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51 4c ATE.# define SQL
0530: 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 61 74 ITE_PRIVATE stat
0540: 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a ic.#endif./*****
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 ********* Begin
0560: 66 69 6c 65 20 63 74 69 6d 65 2e 63 20 2a 2a 2a file ctime.c ***
0570: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 ********/./*.**
05a0: 32 30 31 30 20 46 65 62 72 75 61 72 79 20 32 33 2010 February 23
05b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f .**.** The autho
05c0: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 r disclaims copy
05d0: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f right to this so
05e0: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 urce code. In p
05f0: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 lace of.** a leg
0600: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 al notice, here
0610: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a is a blessing:.*
0620: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 *.** May you
0630: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 do good and not
0640: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 evil..** May
0650: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65 you find forgive
0660: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c ness for yoursel
0670: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 f and forgive ot
0680: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 hers..** May
0690: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79 you share freely
06a0: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d , never taking m
06b0: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76 ore than you giv
06c0: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a e..**.**********
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
0710: 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 **.** This file
0720: 69 6d 70 6c 65 6d 65 6e 74 73 20 72 6f 75 74 69 implements routi
0730: 6e 65 73 20 75 73 65 64 20 74 6f 20 72 65 70 6f nes used to repo
0740: 72 74 20 77 68 61 74 20 63 6f 6d 70 69 6c 65 2d rt what compile-
0750: 74 69 6d 65 20 6f 70 74 69 6f 6e 73 0a 2a 2a 20 time options.**
0760: 53 51 4c 69 74 65 20 77 61 73 20 62 75 69 6c 74 SQLite was built
0770: 20 77 69 74 68 2e 0a 2a 2f 0a 0a 23 69 66 6e 64 with..*/..#ifnd
0780: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 ef SQLITE_OMIT_C
0790: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 OMPILEOPTION_DIA
07a0: 47 53 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 GS../*.** Includ
07b0: 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 e the configurat
07c0: 69 6f 6e 20 68 65 61 64 65 72 20 6f 75 74 70 75 ion header outpu
07d0: 74 20 62 79 20 27 63 6f 6e 66 69 67 75 72 65 27 t by 'configure'
07e0: 20 69 66 20 77 65 27 72 65 20 75 73 69 6e 67 20 if we're using
07f0: 74 68 65 0a 2a 2a 20 61 75 74 6f 63 6f 6e 66 2d the.** autoconf-
0800: 62 61 73 65 64 20 62 75 69 6c 64 0a 2a 2f 0a 23 based build.*/.#
0810: 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41 56 45 if defined(_HAVE
0820: 5f 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 _SQLITE_CONFIG_H
0830: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 53 51 ) && !defined(SQ
0840: 4c 49 54 45 43 4f 4e 46 49 47 5f 48 29 0a 23 69 LITECONFIG_H).#i
0850: 6e 63 6c 75 64 65 20 22 63 6f 6e 66 69 67 2e 68 nclude "config.h
0860: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ".#define SQLITE
0870: 43 4f 4e 46 49 47 5f 48 20 31 0a 23 65 6e 64 69 CONFIG_H 1.#endi
0880: 66 0a 0a 2f 2a 20 54 68 65 73 65 20 6d 61 63 72 f../* These macr
0890: 6f 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 20 os are provided
08a0: 74 6f 20 22 73 74 72 69 6e 67 69 66 79 22 20 74 to "stringify" t
08b0: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
08c0: 64 65 66 69 6e 65 0a 2a 2a 20 66 6f 72 20 74 68 define.** for th
08d0: 6f 73 65 20 6f 70 74 69 6f 6e 73 20 69 6e 20 77 ose options in w
08e0: 68 69 63 68 20 74 68 65 20 76 61 6c 75 65 20 69 hich the value i
08f0: 73 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 20 2a 2f s meaningful. */
0900: 0a 23 64 65 66 69 6e 65 20 43 54 49 4d 45 4f 50 .#define CTIMEOP
0910: 54 5f 56 41 4c 5f 28 6f 70 74 29 20 23 6f 70 74 T_VAL_(opt) #opt
0920: 0a 23 64 65 66 69 6e 65 20 43 54 49 4d 45 4f 50 .#define CTIMEOP
0930: 54 5f 56 41 4c 28 6f 70 74 29 20 43 54 49 4d 45 T_VAL(opt) CTIME
0940: 4f 50 54 5f 56 41 4c 5f 28 6f 70 74 29 0a 0a 2f OPT_VAL_(opt)../
0950: 2a 20 4c 69 6b 65 20 43 54 49 4d 45 4f 50 54 5f * Like CTIMEOPT_
0960: 56 41 4c 2c 20 62 75 74 20 65 73 70 65 63 69 61 VAL, but especia
0970: 6c 6c 79 20 66 6f 72 20 53 51 4c 49 54 45 5f 44 lly for SQLITE_D
0980: 45 46 41 55 4c 54 5f 4c 4f 4f 4b 41 53 49 44 45 EFAULT_LOOKASIDE
0990: 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e . This.** option
09a0: 20 72 65 71 75 69 72 65 73 20 61 20 73 65 70 61 requires a sepa
09b0: 72 61 74 65 20 6d 61 63 72 6f 20 62 65 63 61 75 rate macro becau
09c0: 73 65 20 6c 65 67 61 6c 20 76 61 6c 75 65 73 20 se legal values
09d0: 63 6f 6e 74 61 69 6e 20 61 20 73 69 6e 67 6c 65 contain a single
09e0: 0a 2a 2a 20 63 6f 6d 6d 61 2e 20 65 2e 67 2e 20 .** comma. e.g.
09f0: 28 2d 44 53 51 4c 49 54 45 5f 44 45 46 41 55 4c (-DSQLITE_DEFAUL
0a00: 54 5f 4c 4f 4f 4b 41 53 49 44 45 3d 22 31 30 30 T_LOOKASIDE="100
0a10: 2c 31 30 30 22 29 20 2a 2f 0a 23 64 65 66 69 6e ,100") */.#defin
0a20: 65 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 32 5f e CTIMEOPT_VAL2_
0a30: 28 6f 70 74 31 2c 6f 70 74 32 29 20 23 6f 70 74 (opt1,opt2) #opt
0a40: 31 20 22 2c 22 20 23 6f 70 74 32 0a 23 64 65 66 1 "," #opt2.#def
0a50: 69 6e 65 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c ine CTIMEOPT_VAL
0a60: 32 28 6f 70 74 29 20 43 54 49 4d 45 4f 50 54 5f 2(opt) CTIMEOPT_
0a70: 56 41 4c 32 5f 28 6f 70 74 29 0a 0a 2f 2a 0a 2a VAL2_(opt)../*.*
0a80: 2a 20 41 6e 20 61 72 72 61 79 20 6f 66 20 6e 61 * An array of na
0a90: 6d 65 73 20 6f 66 20 61 6c 6c 20 63 6f 6d 70 69 mes of all compi
0aa0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 73 2e le-time options.
0ab0: 20 20 54 68 69 73 20 61 72 72 61 79 20 73 68 6f This array sho
0ac0: 75 6c 64 20 0a 2a 2a 20 62 65 20 73 6f 72 74 65 uld .** be sorte
0ad0: 64 20 41 2d 5a 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 d A-Z..**.** Thi
0ae0: 73 20 61 72 72 61 79 20 6c 6f 6f 6b 73 20 6c 61 s array looks la
0af0: 72 67 65 2c 20 62 75 74 20 69 6e 20 61 20 74 79 rge, but in a ty
0b00: 70 69 63 61 6c 20 69 6e 73 74 61 6c 6c 61 74 69 pical installati
0b10: 6f 6e 20 61 63 74 75 61 6c 6c 79 20 75 73 65 73 on actually uses
0b20: 0a 2a 2a 20 6f 6e 6c 79 20 61 20 68 61 6e 64 66 .** only a handf
0b30: 75 6c 20 6f 66 20 63 6f 6d 70 69 6c 65 2d 74 69 ul of compile-ti
0b40: 6d 65 20 6f 70 74 69 6f 6e 73 2c 20 73 6f 20 6d me options, so m
0b50: 6f 73 74 20 74 69 6d 65 73 20 74 68 69 73 20 61 ost times this a
0b60: 72 72 61 79 20 69 73 20 75 73 75 61 6c 6c 79 0a rray is usually.
0b70: 2a 2a 20 72 61 74 68 65 72 20 73 68 6f 72 74 20 ** rather short
0b80: 61 6e 64 20 75 73 65 73 20 6c 69 74 74 6c 65 20 and uses little
0b90: 6d 65 6d 6f 72 79 20 73 70 61 63 65 2e 0a 2a 2f memory space..*/
0ba0: 0a 73 74 61 74 69 63 20 63 6f 6e 73 74 20 63 68 .static const ch
0bb0: 61 72 20 2a 20 63 6f 6e 73 74 20 73 71 6c 69 74 ar * const sqlit
0bc0: 65 33 61 7a 43 6f 6d 70 69 6c 65 4f 70 74 5b 5d e3azCompileOpt[]
0bd0: 20 3d 20 7b 0a 0a 2f 2a 20 0a 2a 2a 20 42 45 47 = {../* .** BEG
0be0: 49 4e 20 43 4f 44 45 20 47 45 4e 45 52 41 54 45 IN CODE GENERATE
0bf0: 44 20 42 59 20 74 6f 6f 6c 2f 6d 6b 63 74 69 6d D BY tool/mkctim
0c00: 65 2e 74 63 6c 20 0a 2a 2f 0a 23 69 66 20 53 51 e.tcl .*/.#if SQ
0c10: 4c 49 54 45 5f 33 32 42 49 54 5f 52 4f 57 49 44 LITE_32BIT_ROWID
0c20: 0a 20 20 22 33 32 42 49 54 5f 52 4f 57 49 44 22 . "32BIT_ROWID"
0c30: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
0c40: 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e ITE_4_BYTE_ALIGN
0c50: 45 44 5f 4d 41 4c 4c 4f 43 0a 20 20 22 34 5f 42 ED_MALLOC. "4_B
0c60: 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c YTE_ALIGNED_MALL
0c70: 4f 43 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 OC",.#endif.#if
0c80: 53 51 4c 49 54 45 5f 36 34 42 49 54 5f 53 54 41 SQLITE_64BIT_STA
0c90: 54 53 0a 20 20 22 36 34 42 49 54 5f 53 54 41 54 TS. "64BIT_STAT
0ca0: 53 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 S",.#endif.#if S
0cb0: 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 QLITE_ALLOW_COVE
0cc0: 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a RING_INDEX_SCAN.
0cd0: 20 20 22 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e "ALLOW_COVERIN
0ce0: 47 5f 49 4e 44 45 58 5f 53 43 41 4e 22 2c 0a 23 G_INDEX_SCAN",.#
0cf0: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
0d00: 5f 41 4c 4c 4f 57 5f 55 52 49 5f 41 55 54 48 4f _ALLOW_URI_AUTHO
0d10: 52 49 54 59 0a 20 20 22 41 4c 4c 4f 57 5f 55 52 RITY. "ALLOW_UR
0d20: 49 5f 41 55 54 48 4f 52 49 54 59 22 2c 0a 23 65 I_AUTHORITY",.#e
0d30: 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 ndif.#ifdef SQLI
0d40: 54 45 5f 42 49 54 4d 41 53 4b 5f 54 59 50 45 0a TE_BITMASK_TYPE.
0d50: 20 20 22 42 49 54 4d 41 53 4b 5f 54 59 50 45 3d "BITMASK_TYPE=
0d60: 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 " CTIMEOPT_VAL(S
0d70: 51 4c 49 54 45 5f 42 49 54 4d 41 53 4b 5f 54 59 QLITE_BITMASK_TY
0d80: 50 45 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 PE),.#endif.#if
0d90: 53 51 4c 49 54 45 5f 42 55 47 5f 43 4f 4d 50 41 SQLITE_BUG_COMPA
0da0: 54 49 42 4c 45 5f 32 30 31 36 30 38 31 39 0a 20 TIBLE_20160819.
0db0: 20 22 42 55 47 5f 43 4f 4d 50 41 54 49 42 4c 45 "BUG_COMPATIBLE
0dc0: 5f 32 30 31 36 30 38 31 39 22 2c 0a 23 65 6e 64 _20160819",.#end
0dd0: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 43 41 if.#if SQLITE_CA
0de0: 53 45 5f 53 45 4e 53 49 54 49 56 45 5f 4c 49 4b SE_SENSITIVE_LIK
0df0: 45 0a 20 20 22 43 41 53 45 5f 53 45 4e 53 49 54 E. "CASE_SENSIT
0e00: 49 56 45 5f 4c 49 4b 45 22 2c 0a 23 65 6e 64 69 IVE_LIKE",.#endi
0e10: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 43 48 45 f.#if SQLITE_CHE
0e20: 43 4b 5f 50 41 47 45 53 0a 20 20 22 43 48 45 43 CK_PAGES. "CHEC
0e30: 4b 5f 50 41 47 45 53 22 2c 0a 23 65 6e 64 69 66 K_PAGES",.#endif
0e40: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 63 .#if defined(__c
0e50: 6c 61 6e 67 5f 5f 29 20 26 26 20 64 65 66 69 6e lang__) && defin
0e60: 65 64 28 5f 5f 63 6c 61 6e 67 5f 6d 61 6a 6f 72 ed(__clang_major
0e70: 5f 5f 29 0a 20 20 22 43 4f 4d 50 49 4c 45 52 3d __). "COMPILER=
0e80: 63 6c 61 6e 67 2d 22 20 43 54 49 4d 45 4f 50 54 clang-" CTIMEOPT
0e90: 5f 56 41 4c 28 5f 5f 63 6c 61 6e 67 5f 6d 61 6a _VAL(__clang_maj
0ea0: 6f 72 5f 5f 29 20 22 2e 22 0a 20 20 20 20 20 20 or__) ".".
0eb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 43 54 CT
0ec0: 49 4d 45 4f 50 54 5f 56 41 4c 28 5f 5f 63 6c 61 IMEOPT_VAL(__cla
0ed0: 6e 67 5f 6d 69 6e 6f 72 5f 5f 29 20 22 2e 22 0a ng_minor__) ".".
0ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
0ef0: 20 20 20 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c CTIMEOPT_VAL
0f00: 28 5f 5f 63 6c 61 6e 67 5f 70 61 74 63 68 6c 65 (__clang_patchle
0f10: 76 65 6c 5f 5f 29 2c 0a 23 65 6c 69 66 20 64 65 vel__),.#elif de
0f20: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 0a fined(_MSC_VER).
0f30: 20 20 22 43 4f 4d 50 49 4c 45 52 3d 6d 73 76 63 "COMPILER=msvc
0f40: 2d 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 -" CTIMEOPT_VAL(
0f50: 5f 4d 53 43 5f 56 45 52 29 2c 0a 23 65 6c 69 66 _MSC_VER),.#elif
0f60: 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55 43 5f defined(__GNUC_
0f70: 5f 29 20 26 26 20 64 65 66 69 6e 65 64 28 5f 5f _) && defined(__
0f80: 56 45 52 53 49 4f 4e 5f 5f 29 0a 20 20 22 43 4f VERSION__). "CO
0f90: 4d 50 49 4c 45 52 3d 67 63 63 2d 22 20 5f 5f 56 MPILER=gcc-" __V
0fa0: 45 52 53 49 4f 4e 5f 5f 2c 0a 23 65 6e 64 69 66 ERSION__,.#endif
0fb0: 0a 23 69 66 20 53 51 4c 49 54 45 5f 43 4f 56 45 .#if SQLITE_COVE
0fc0: 52 41 47 45 5f 54 45 53 54 0a 20 20 22 43 4f 56 RAGE_TEST. "COV
0fd0: 45 52 41 47 45 5f 54 45 53 54 22 2c 0a 23 65 6e ERAGE_TEST",.#en
0fe0: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 44 dif.#if SQLITE_D
0ff0: 45 42 55 47 0a 20 20 22 44 45 42 55 47 22 2c 0a EBUG. "DEBUG",.
1000: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
1010: 45 5f 44 45 46 41 55 4c 54 5f 41 55 54 4f 4d 41 E_DEFAULT_AUTOMA
1020: 54 49 43 5f 49 4e 44 45 58 0a 20 20 22 44 45 46 TIC_INDEX. "DEF
1030: 41 55 4c 54 5f 41 55 54 4f 4d 41 54 49 43 5f 49 AULT_AUTOMATIC_I
1040: 4e 44 45 58 22 2c 0a 23 65 6e 64 69 66 0a 23 69 NDEX",.#endif.#i
1050: 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 f SQLITE_DEFAULT
1060: 5f 41 55 54 4f 56 41 43 55 55 4d 0a 20 20 22 44 _AUTOVACUUM. "D
1070: 45 46 41 55 4c 54 5f 41 55 54 4f 56 41 43 55 55 EFAULT_AUTOVACUU
1080: 4d 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 M",.#endif.#ifde
1090: 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 f SQLITE_DEFAULT
10a0: 5f 43 41 43 48 45 5f 53 49 5a 45 0a 20 20 22 44 _CACHE_SIZE. "D
10b0: 45 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a EFAULT_CACHE_SIZ
10c0: 45 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c E=" CTIMEOPT_VAL
10d0: 28 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f (SQLITE_DEFAULT_
10e0: 43 41 43 48 45 5f 53 49 5a 45 29 2c 0a 23 65 6e CACHE_SIZE),.#en
10f0: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 44 dif.#if SQLITE_D
1100: 45 46 41 55 4c 54 5f 43 4b 50 54 46 55 4c 4c 46 EFAULT_CKPTFULLF
1110: 53 59 4e 43 0a 20 20 22 44 45 46 41 55 4c 54 5f SYNC. "DEFAULT_
1120: 43 4b 50 54 46 55 4c 4c 46 53 59 4e 43 22 2c 0a CKPTFULLFSYNC",.
1130: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 #endif.#ifdef SQ
1140: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 46 49 4c LITE_DEFAULT_FIL
1150: 45 5f 46 4f 52 4d 41 54 0a 20 20 22 44 45 46 41 E_FORMAT. "DEFA
1160: 55 4c 54 5f 46 49 4c 45 5f 46 4f 52 4d 41 54 3d ULT_FILE_FORMAT=
1170: 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 " CTIMEOPT_VAL(S
1180: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 46 49 QLITE_DEFAULT_FI
1190: 4c 45 5f 46 4f 52 4d 41 54 29 2c 0a 23 65 6e 64 LE_FORMAT),.#end
11a0: 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 if.#ifdef SQLITE
11b0: 5f 44 45 46 41 55 4c 54 5f 46 49 4c 45 5f 50 45 _DEFAULT_FILE_PE
11c0: 52 4d 49 53 53 49 4f 4e 53 0a 20 20 22 44 45 46 RMISSIONS. "DEF
11d0: 41 55 4c 54 5f 46 49 4c 45 5f 50 45 52 4d 49 53 AULT_FILE_PERMIS
11e0: 53 49 4f 4e 53 3d 22 20 43 54 49 4d 45 4f 50 54 SIONS=" CTIMEOPT
11f0: 5f 56 41 4c 28 53 51 4c 49 54 45 5f 44 45 46 41 _VAL(SQLITE_DEFA
1200: 55 4c 54 5f 46 49 4c 45 5f 50 45 52 4d 49 53 53 ULT_FILE_PERMISS
1210: 49 4f 4e 53 29 2c 0a 23 65 6e 64 69 66 0a 23 69 IONS),.#endif.#i
1220: 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 f SQLITE_DEFAULT
1230: 5f 46 4f 52 45 49 47 4e 5f 4b 45 59 53 0a 20 20 _FOREIGN_KEYS.
1240: 22 44 45 46 41 55 4c 54 5f 46 4f 52 45 49 47 4e "DEFAULT_FOREIGN
1250: 5f 4b 45 59 53 22 2c 0a 23 65 6e 64 69 66 0a 23 _KEYS",.#endif.#
1260: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 ifdef SQLITE_DEF
1270: 41 55 4c 54 5f 4a 4f 55 52 4e 41 4c 5f 53 49 5a AULT_JOURNAL_SIZ
1280: 45 5f 4c 49 4d 49 54 0a 20 20 22 44 45 46 41 55 E_LIMIT. "DEFAU
1290: 4c 54 5f 4a 4f 55 52 4e 41 4c 5f 53 49 5a 45 5f LT_JOURNAL_SIZE_
12a0: 4c 49 4d 49 54 3d 22 20 43 54 49 4d 45 4f 50 54 LIMIT=" CTIMEOPT
12b0: 5f 56 41 4c 28 53 51 4c 49 54 45 5f 44 45 46 41 _VAL(SQLITE_DEFA
12c0: 55 4c 54 5f 4a 4f 55 52 4e 41 4c 5f 53 49 5a 45 ULT_JOURNAL_SIZE
12d0: 5f 4c 49 4d 49 54 29 2c 0a 23 65 6e 64 69 66 0a _LIMIT),.#endif.
12e0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 44 45 #ifdef SQLITE_DE
12f0: 46 41 55 4c 54 5f 4c 4f 43 4b 49 4e 47 5f 4d 4f FAULT_LOCKING_MO
1300: 44 45 0a 20 20 22 44 45 46 41 55 4c 54 5f 4c 4f DE. "DEFAULT_LO
1310: 43 4b 49 4e 47 5f 4d 4f 44 45 3d 22 20 43 54 49 CKING_MODE=" CTI
1320: 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 MEOPT_VAL(SQLITE
1330: 5f 44 45 46 41 55 4c 54 5f 4c 4f 43 4b 49 4e 47 _DEFAULT_LOCKING
1340: 5f 4d 4f 44 45 29 2c 0a 23 65 6e 64 69 66 0a 23 _MODE),.#endif.#
1350: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 ifdef SQLITE_DEF
1360: 41 55 4c 54 5f 4c 4f 4f 4b 41 53 49 44 45 0a 20 AULT_LOOKASIDE.
1370: 20 22 44 45 46 41 55 4c 54 5f 4c 4f 4f 4b 41 53 "DEFAULT_LOOKAS
1380: 49 44 45 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 IDE=" CTIMEOPT_V
1390: 41 4c 32 28 53 51 4c 49 54 45 5f 44 45 46 41 55 AL2(SQLITE_DEFAU
13a0: 4c 54 5f 4c 4f 4f 4b 41 53 49 44 45 29 2c 0a 23 LT_LOOKASIDE),.#
13b0: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
13c0: 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 _DEFAULT_MEMSTAT
13d0: 55 53 0a 20 20 22 44 45 46 41 55 4c 54 5f 4d 45 US. "DEFAULT_ME
13e0: 4d 53 54 41 54 55 53 22 2c 0a 23 65 6e 64 69 66 MSTATUS",.#endif
13f0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 44 .#ifdef SQLITE_D
1400: 45 46 41 55 4c 54 5f 4d 4d 41 50 5f 53 49 5a 45 EFAULT_MMAP_SIZE
1410: 0a 20 20 22 44 45 46 41 55 4c 54 5f 4d 4d 41 50 . "DEFAULT_MMAP
1420: 5f 53 49 5a 45 3d 22 20 43 54 49 4d 45 4f 50 54 _SIZE=" CTIMEOPT
1430: 5f 56 41 4c 28 53 51 4c 49 54 45 5f 44 45 46 41 _VAL(SQLITE_DEFA
1440: 55 4c 54 5f 4d 4d 41 50 5f 53 49 5a 45 29 2c 0a ULT_MMAP_SIZE),.
1450: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 #endif.#ifdef SQ
1460: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47 LITE_DEFAULT_PAG
1470: 45 5f 53 49 5a 45 0a 20 20 22 44 45 46 41 55 4c E_SIZE. "DEFAUL
1480: 54 5f 50 41 47 45 5f 53 49 5a 45 3d 22 20 43 54 T_PAGE_SIZE=" CT
1490: 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 IMEOPT_VAL(SQLIT
14a0: 45 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f 53 E_DEFAULT_PAGE_S
14b0: 49 5a 45 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 IZE),.#endif.#if
14c0: 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 def SQLITE_DEFAU
14d0: 4c 54 5f 50 43 41 43 48 45 5f 49 4e 49 54 53 5a LT_PCACHE_INITSZ
14e0: 0a 20 20 22 44 45 46 41 55 4c 54 5f 50 43 41 43 . "DEFAULT_PCAC
14f0: 48 45 5f 49 4e 49 54 53 5a 3d 22 20 43 54 49 4d HE_INITSZ=" CTIM
1500: 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f EOPT_VAL(SQLITE_
1510: 44 45 46 41 55 4c 54 5f 50 43 41 43 48 45 5f 49 DEFAULT_PCACHE_I
1520: 4e 49 54 53 5a 29 2c 0a 23 65 6e 64 69 66 0a 23 NITSZ),.#endif.#
1530: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 ifdef SQLITE_DEF
1540: 41 55 4c 54 5f 50 52 4f 58 59 44 49 52 5f 50 45 AULT_PROXYDIR_PE
1550: 52 4d 49 53 53 49 4f 4e 53 0a 20 20 22 44 45 46 RMISSIONS. "DEF
1560: 41 55 4c 54 5f 50 52 4f 58 59 44 49 52 5f 50 45 AULT_PROXYDIR_PE
1570: 52 4d 49 53 53 49 4f 4e 53 3d 22 20 43 54 49 4d RMISSIONS=" CTIM
1580: 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f EOPT_VAL(SQLITE_
1590: 44 45 46 41 55 4c 54 5f 50 52 4f 58 59 44 49 52 DEFAULT_PROXYDIR
15a0: 5f 50 45 52 4d 49 53 53 49 4f 4e 53 29 2c 0a 23 _PERMISSIONS),.#
15b0: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
15c0: 5f 44 45 46 41 55 4c 54 5f 52 45 43 55 52 53 49 _DEFAULT_RECURSI
15d0: 56 45 5f 54 52 49 47 47 45 52 53 0a 20 20 22 44 VE_TRIGGERS. "D
15e0: 45 46 41 55 4c 54 5f 52 45 43 55 52 53 49 56 45 EFAULT_RECURSIVE
15f0: 5f 54 52 49 47 47 45 52 53 22 2c 0a 23 65 6e 64 _TRIGGERS",.#end
1600: 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 if.#ifdef SQLITE
1610: 5f 44 45 46 41 55 4c 54 5f 52 4f 57 45 53 54 0a _DEFAULT_ROWEST.
1620: 20 20 22 44 45 46 41 55 4c 54 5f 52 4f 57 45 53 "DEFAULT_ROWES
1630: 54 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c T=" CTIMEOPT_VAL
1640: 28 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f (SQLITE_DEFAULT_
1650: 52 4f 57 45 53 54 29 2c 0a 23 65 6e 64 69 66 0a ROWEST),.#endif.
1660: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 44 45 #ifdef SQLITE_DE
1670: 46 41 55 4c 54 5f 53 45 43 54 4f 52 5f 53 49 5a FAULT_SECTOR_SIZ
1680: 45 0a 20 20 22 44 45 46 41 55 4c 54 5f 53 45 43 E. "DEFAULT_SEC
1690: 54 4f 52 5f 53 49 5a 45 3d 22 20 43 54 49 4d 45 TOR_SIZE=" CTIME
16a0: 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 44 OPT_VAL(SQLITE_D
16b0: 45 46 41 55 4c 54 5f 53 45 43 54 4f 52 5f 53 49 EFAULT_SECTOR_SI
16c0: 5a 45 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 ZE),.#endif.#ifd
16d0: 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c ef SQLITE_DEFAUL
16e0: 54 5f 53 59 4e 43 48 52 4f 4e 4f 55 53 0a 20 20 T_SYNCHRONOUS.
16f0: 22 44 45 46 41 55 4c 54 5f 53 59 4e 43 48 52 4f "DEFAULT_SYNCHRO
1700: 4e 4f 55 53 3d 22 20 43 54 49 4d 45 4f 50 54 5f NOUS=" CTIMEOPT_
1710: 56 41 4c 28 53 51 4c 49 54 45 5f 44 45 46 41 55 VAL(SQLITE_DEFAU
1720: 4c 54 5f 53 59 4e 43 48 52 4f 4e 4f 55 53 29 2c LT_SYNCHRONOUS),
1730: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 .#endif.#ifdef S
1740: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 41 QLITE_DEFAULT_WA
1750: 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54 L_AUTOCHECKPOINT
1760: 0a 20 20 22 44 45 46 41 55 4c 54 5f 57 41 4c 5f . "DEFAULT_WAL_
1770: 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54 3d 22 AUTOCHECKPOINT="
1780: 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 CTIMEOPT_VAL(SQ
1790: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c LITE_DEFAULT_WAL
17a0: 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54 29 _AUTOCHECKPOINT)
17b0: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 ,.#endif.#ifdef
17c0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 SQLITE_DEFAULT_W
17d0: 41 4c 5f 53 59 4e 43 48 52 4f 4e 4f 55 53 0a 20 AL_SYNCHRONOUS.
17e0: 20 22 44 45 46 41 55 4c 54 5f 57 41 4c 5f 53 59 "DEFAULT_WAL_SY
17f0: 4e 43 48 52 4f 4e 4f 55 53 3d 22 20 43 54 49 4d NCHRONOUS=" CTIM
1800: 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f EOPT_VAL(SQLITE_
1810: 44 45 46 41 55 4c 54 5f 57 41 4c 5f 53 59 4e 43 DEFAULT_WAL_SYNC
1820: 48 52 4f 4e 4f 55 53 29 2c 0a 23 65 6e 64 69 66 HRONOUS),.#endif
1830: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 44 .#ifdef SQLITE_D
1840: 45 46 41 55 4c 54 5f 57 4f 52 4b 45 52 5f 54 48 EFAULT_WORKER_TH
1850: 52 45 41 44 53 0a 20 20 22 44 45 46 41 55 4c 54 READS. "DEFAULT
1860: 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3d _WORKER_THREADS=
1870: 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 " CTIMEOPT_VAL(S
1880: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 4f QLITE_DEFAULT_WO
1890: 52 4b 45 52 5f 54 48 52 45 41 44 53 29 2c 0a 23 RKER_THREADS),.#
18a0: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
18b0: 5f 44 49 52 45 43 54 5f 4f 56 45 52 46 4c 4f 57 _DIRECT_OVERFLOW
18c0: 5f 52 45 41 44 0a 20 20 22 44 49 52 45 43 54 5f _READ. "DIRECT_
18d0: 4f 56 45 52 46 4c 4f 57 5f 52 45 41 44 22 2c 0a OVERFLOW_READ",.
18e0: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
18f0: 45 5f 44 49 53 41 42 4c 45 5f 44 49 52 53 59 4e E_DISABLE_DIRSYN
1900: 43 0a 20 20 22 44 49 53 41 42 4c 45 5f 44 49 52 C. "DISABLE_DIR
1910: 53 59 4e 43 22 2c 0a 23 65 6e 64 69 66 0a 23 69 SYNC",.#endif.#i
1920: 66 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 f SQLITE_DISABLE
1930: 5f 46 54 53 33 5f 55 4e 49 43 4f 44 45 0a 20 20 _FTS3_UNICODE.
1940: 22 44 49 53 41 42 4c 45 5f 46 54 53 33 5f 55 4e "DISABLE_FTS3_UN
1950: 49 43 4f 44 45 22 2c 0a 23 65 6e 64 69 66 0a 23 ICODE",.#endif.#
1960: 69 66 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c if SQLITE_DISABL
1970: 45 5f 46 54 53 34 5f 44 45 46 45 52 52 45 44 0a E_FTS4_DEFERRED.
1980: 20 20 22 44 49 53 41 42 4c 45 5f 46 54 53 34 5f "DISABLE_FTS4_
1990: 44 45 46 45 52 52 45 44 22 2c 0a 23 65 6e 64 69 DEFERRED",.#endi
19a0: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 44 49 53 f.#if SQLITE_DIS
19b0: 41 42 4c 45 5f 49 4e 54 52 49 4e 53 49 43 0a 20 ABLE_INTRINSIC.
19c0: 20 22 44 49 53 41 42 4c 45 5f 49 4e 54 52 49 4e "DISABLE_INTRIN
19d0: 53 49 43 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 SIC",.#endif.#if
19e0: 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f SQLITE_DISABLE_
19f0: 4c 46 53 0a 20 20 22 44 49 53 41 42 4c 45 5f 4c LFS. "DISABLE_L
1a00: 46 53 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 FS",.#endif.#if
1a10: 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f 50 SQLITE_DISABLE_P
1a20: 41 47 45 43 41 43 48 45 5f 4f 56 45 52 46 4c 4f AGECACHE_OVERFLO
1a30: 57 5f 53 54 41 54 53 0a 20 20 22 44 49 53 41 42 W_STATS. "DISAB
1a40: 4c 45 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 LE_PAGECACHE_OVE
1a50: 52 46 4c 4f 57 5f 53 54 41 54 53 22 2c 0a 23 65 RFLOW_STATS",.#e
1a60: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
1a70: 44 49 53 41 42 4c 45 5f 53 4b 49 50 41 48 45 41 DISABLE_SKIPAHEA
1a80: 44 5f 44 49 53 54 49 4e 43 54 0a 20 20 22 44 49 D_DISTINCT. "DI
1a90: 53 41 42 4c 45 5f 53 4b 49 50 41 48 45 41 44 5f SABLE_SKIPAHEAD_
1aa0: 44 49 53 54 49 4e 43 54 22 2c 0a 23 65 6e 64 69 DISTINCT",.#endi
1ab0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
1ac0: 45 4e 41 42 4c 45 5f 38 5f 33 5f 4e 41 4d 45 53 ENABLE_8_3_NAMES
1ad0: 0a 20 20 22 45 4e 41 42 4c 45 5f 38 5f 33 5f 4e . "ENABLE_8_3_N
1ae0: 41 4d 45 53 3d 22 20 43 54 49 4d 45 4f 50 54 5f AMES=" CTIMEOPT_
1af0: 56 41 4c 28 53 51 4c 49 54 45 5f 45 4e 41 42 4c VAL(SQLITE_ENABL
1b00: 45 5f 38 5f 33 5f 4e 41 4d 45 53 29 2c 0a 23 65 E_8_3_NAMES),.#e
1b10: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
1b20: 45 4e 41 42 4c 45 5f 41 50 49 5f 41 52 4d 4f 52 ENABLE_API_ARMOR
1b30: 0a 20 20 22 45 4e 41 42 4c 45 5f 41 50 49 5f 41 . "ENABLE_API_A
1b40: 52 4d 4f 52 22 2c 0a 23 65 6e 64 69 66 0a 23 69 RMOR",.#endif.#i
1b50: 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f f SQLITE_ENABLE_
1b60: 41 54 4f 4d 49 43 5f 57 52 49 54 45 0a 20 20 22 ATOMIC_WRITE. "
1b70: 45 4e 41 42 4c 45 5f 41 54 4f 4d 49 43 5f 57 52 ENABLE_ATOMIC_WR
1b80: 49 54 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 ITE",.#endif.#if
1b90: 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 42 SQLITE_ENABLE_B
1ba0: 41 54 43 48 5f 41 54 4f 4d 49 43 5f 57 52 49 54 ATCH_ATOMIC_WRIT
1bb0: 45 0a 20 20 22 45 4e 41 42 4c 45 5f 42 41 54 43 E. "ENABLE_BATC
1bc0: 48 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 22 2c H_ATOMIC_WRITE",
1bd0: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
1be0: 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a TE_ENABLE_CEROD.
1bf0: 20 20 22 45 4e 41 42 4c 45 5f 43 45 52 4f 44 3d "ENABLE_CEROD=
1c00: 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 " CTIMEOPT_VAL(S
1c10: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 QLITE_ENABLE_CER
1c20: 4f 44 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 OD),.#endif.#if
1c30: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f SQLITE_ENABLE_CO
1c40: 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 0a 20 20 LUMN_METADATA.
1c50: 22 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d "ENABLE_COLUMN_M
1c60: 45 54 41 44 41 54 41 22 2c 0a 23 65 6e 64 69 66 ETADATA",.#endif
1c70: 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 .#if SQLITE_ENAB
1c80: 4c 45 5f 43 4f 4c 55 4d 4e 5f 55 53 45 44 5f 4d LE_COLUMN_USED_M
1c90: 41 53 4b 0a 20 20 22 45 4e 41 42 4c 45 5f 43 4f ASK. "ENABLE_CO
1ca0: 4c 55 4d 4e 5f 55 53 45 44 5f 4d 41 53 4b 22 2c LUMN_USED_MASK",
1cb0: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
1cc0: 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 53 54 4d 55 TE_ENABLE_COSTMU
1cd0: 4c 54 0a 20 20 22 45 4e 41 42 4c 45 5f 43 4f 53 LT. "ENABLE_COS
1ce0: 54 4d 55 4c 54 22 2c 0a 23 65 6e 64 69 66 0a 23 TMULT",.#endif.#
1cf0: 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 if SQLITE_ENABLE
1d00: 5f 43 55 52 53 4f 52 5f 48 49 4e 54 53 0a 20 20 _CURSOR_HINTS.
1d10: 22 45 4e 41 42 4c 45 5f 43 55 52 53 4f 52 5f 48 "ENABLE_CURSOR_H
1d20: 49 4e 54 53 22 2c 0a 23 65 6e 64 69 66 0a 23 69 INTS",.#endif.#i
1d30: 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f f SQLITE_ENABLE_
1d40: 44 42 53 54 41 54 5f 56 54 41 42 0a 20 20 22 45 DBSTAT_VTAB. "E
1d50: 4e 41 42 4c 45 5f 44 42 53 54 41 54 5f 56 54 41 NABLE_DBSTAT_VTA
1d60: 42 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 B",.#endif.#if S
1d70: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 45 58 50 QLITE_ENABLE_EXP
1d80: 45 4e 53 49 56 45 5f 41 53 53 45 52 54 0a 20 20 ENSIVE_ASSERT.
1d90: 22 45 4e 41 42 4c 45 5f 45 58 50 45 4e 53 49 56 "ENABLE_EXPENSIV
1da0: 45 5f 41 53 53 45 52 54 22 2c 0a 23 65 6e 64 69 E_ASSERT",.#endi
1db0: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 f.#if SQLITE_ENA
1dc0: 42 4c 45 5f 46 54 53 31 0a 20 20 22 45 4e 41 42 BLE_FTS1. "ENAB
1dd0: 4c 45 5f 46 54 53 31 22 2c 0a 23 65 6e 64 69 66 LE_FTS1",.#endif
1de0: 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 .#if SQLITE_ENAB
1df0: 4c 45 5f 46 54 53 32 0a 20 20 22 45 4e 41 42 4c LE_FTS2. "ENABL
1e00: 45 5f 46 54 53 32 22 2c 0a 23 65 6e 64 69 66 0a E_FTS2",.#endif.
1e10: 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c #if SQLITE_ENABL
1e20: 45 5f 46 54 53 33 0a 20 20 22 45 4e 41 42 4c 45 E_FTS3. "ENABLE
1e30: 5f 46 54 53 33 22 2c 0a 23 65 6e 64 69 66 0a 23 _FTS3",.#endif.#
1e40: 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 if SQLITE_ENABLE
1e50: 5f 46 54 53 33 5f 50 41 52 45 4e 54 48 45 53 49 _FTS3_PARENTHESI
1e60: 53 0a 20 20 22 45 4e 41 42 4c 45 5f 46 54 53 33 S. "ENABLE_FTS3
1e70: 5f 50 41 52 45 4e 54 48 45 53 49 53 22 2c 0a 23 _PARENTHESIS",.#
1e80: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
1e90: 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b _ENABLE_FTS3_TOK
1ea0: 45 4e 49 5a 45 52 0a 20 20 22 45 4e 41 42 4c 45 ENIZER. "ENABLE
1eb0: 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 22 _FTS3_TOKENIZER"
1ec0: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
1ed0: 49 54 45 5f 45 4e 41 42 4c 45 5f 46 54 53 34 0a ITE_ENABLE_FTS4.
1ee0: 20 20 22 45 4e 41 42 4c 45 5f 46 54 53 34 22 2c "ENABLE_FTS4",
1ef0: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
1f00: 54 45 5f 45 4e 41 42 4c 45 5f 46 54 53 35 0a 20 TE_ENABLE_FTS5.
1f10: 20 22 45 4e 41 42 4c 45 5f 46 54 53 35 22 2c 0a "ENABLE_FTS5",.
1f20: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
1f30: 45 5f 45 4e 41 42 4c 45 5f 48 49 44 44 45 4e 5f E_ENABLE_HIDDEN_
1f40: 43 4f 4c 55 4d 4e 53 0a 20 20 22 45 4e 41 42 4c COLUMNS. "ENABL
1f50: 45 5f 48 49 44 44 45 4e 5f 43 4f 4c 55 4d 4e 53 E_HIDDEN_COLUMNS
1f60: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
1f70: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 49 43 55 0a LITE_ENABLE_ICU.
1f80: 20 20 22 45 4e 41 42 4c 45 5f 49 43 55 22 2c 0a "ENABLE_ICU",.
1f90: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
1fa0: 45 5f 45 4e 41 42 4c 45 5f 49 4f 54 52 41 43 45 E_ENABLE_IOTRACE
1fb0: 0a 20 20 22 45 4e 41 42 4c 45 5f 49 4f 54 52 41 . "ENABLE_IOTRA
1fc0: 43 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 CE",.#endif.#if
1fd0: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4a 53 SQLITE_ENABLE_JS
1fe0: 4f 4e 31 0a 20 20 22 45 4e 41 42 4c 45 5f 4a 53 ON1. "ENABLE_JS
1ff0: 4f 4e 31 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 ON1",.#endif.#if
2000: 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c SQLITE_ENABLE_L
2010: 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 0a 20 20 OAD_EXTENSION.
2020: 22 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 "ENABLE_LOAD_EXT
2030: 45 4e 53 49 4f 4e 22 2c 0a 23 65 6e 64 69 66 0a ENSION",.#endif.
2040: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e #ifdef SQLITE_EN
2050: 41 42 4c 45 5f 4c 4f 43 4b 49 4e 47 5f 53 54 59 ABLE_LOCKING_STY
2060: 4c 45 0a 20 20 22 45 4e 41 42 4c 45 5f 4c 4f 43 LE. "ENABLE_LOC
2070: 4b 49 4e 47 5f 53 54 59 4c 45 3d 22 20 43 54 49 KING_STYLE=" CTI
2080: 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 MEOPT_VAL(SQLITE
2090: 5f 45 4e 41 42 4c 45 5f 4c 4f 43 4b 49 4e 47 5f _ENABLE_LOCKING_
20a0: 53 54 59 4c 45 29 2c 0a 23 65 6e 64 69 66 0a 23 STYLE),.#endif.#
20b0: 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 if SQLITE_ENABLE
20c0: 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 _MEMORY_MANAGEME
20d0: 4e 54 0a 20 20 22 45 4e 41 42 4c 45 5f 4d 45 4d NT. "ENABLE_MEM
20e0: 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 22 2c ORY_MANAGEMENT",
20f0: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
2100: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 TE_ENABLE_MEMSYS
2110: 33 0a 20 20 22 45 4e 41 42 4c 45 5f 4d 45 4d 53 3. "ENABLE_MEMS
2120: 59 53 33 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 YS3",.#endif.#if
2130: 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d SQLITE_ENABLE_M
2140: 45 4d 53 59 53 35 0a 20 20 22 45 4e 41 42 4c 45 EMSYS5. "ENABLE
2150: 5f 4d 45 4d 53 59 53 35 22 2c 0a 23 65 6e 64 69 _MEMSYS5",.#endi
2160: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 f.#if SQLITE_ENA
2170: 42 4c 45 5f 4d 55 4c 54 49 50 4c 45 58 0a 20 20 BLE_MULTIPLEX.
2180: 22 45 4e 41 42 4c 45 5f 4d 55 4c 54 49 50 4c 45 "ENABLE_MULTIPLE
2190: 58 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 X",.#endif.#if S
21a0: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4e 55 4c QLITE_ENABLE_NUL
21b0: 4c 5f 54 52 49 4d 0a 20 20 22 45 4e 41 42 4c 45 L_TRIM. "ENABLE
21c0: 5f 4e 55 4c 4c 5f 54 52 49 4d 22 2c 0a 23 65 6e _NULL_TRIM",.#en
21d0: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 dif.#if SQLITE_E
21e0: 4e 41 42 4c 45 5f 4f 56 45 52 53 49 5a 45 5f 43 NABLE_OVERSIZE_C
21f0: 45 4c 4c 5f 43 48 45 43 4b 0a 20 20 22 45 4e 41 ELL_CHECK. "ENA
2200: 42 4c 45 5f 4f 56 45 52 53 49 5a 45 5f 43 45 4c BLE_OVERSIZE_CEL
2210: 4c 5f 43 48 45 43 4b 22 2c 0a 23 65 6e 64 69 66 L_CHECK",.#endif
2220: 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 .#if SQLITE_ENAB
2230: 4c 45 5f 50 52 45 55 50 44 41 54 45 5f 48 4f 4f LE_PREUPDATE_HOO
2240: 4b 0a 20 20 22 45 4e 41 42 4c 45 5f 50 52 45 55 K. "ENABLE_PREU
2250: 50 44 41 54 45 5f 48 4f 4f 4b 22 2c 0a 23 65 6e PDATE_HOOK",.#en
2260: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 dif.#if SQLITE_E
2270: 4e 41 42 4c 45 5f 51 50 53 47 0a 20 20 22 45 4e NABLE_QPSG. "EN
2280: 41 42 4c 45 5f 51 50 53 47 22 2c 0a 23 65 6e 64 ABLE_QPSG",.#end
2290: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e if.#if SQLITE_EN
22a0: 41 42 4c 45 5f 52 42 55 0a 20 20 22 45 4e 41 42 ABLE_RBU. "ENAB
22b0: 4c 45 5f 52 42 55 22 2c 0a 23 65 6e 64 69 66 0a LE_RBU",.#endif.
22c0: 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c #if SQLITE_ENABL
22d0: 45 5f 52 54 52 45 45 0a 20 20 22 45 4e 41 42 4c E_RTREE. "ENABL
22e0: 45 5f 52 54 52 45 45 22 2c 0a 23 65 6e 64 69 66 E_RTREE",.#endif
22f0: 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 .#if SQLITE_ENAB
2300: 4c 45 5f 53 45 4c 45 43 54 54 52 41 43 45 0a 20 LE_SELECTTRACE.
2310: 20 22 45 4e 41 42 4c 45 5f 53 45 4c 45 43 54 54 "ENABLE_SELECTT
2320: 52 41 43 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 RACE",.#endif.#i
2330: 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f f SQLITE_ENABLE_
2340: 53 45 53 53 49 4f 4e 0a 20 20 22 45 4e 41 42 4c SESSION. "ENABL
2350: 45 5f 53 45 53 53 49 4f 4e 22 2c 0a 23 65 6e 64 E_SESSION",.#end
2360: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e if.#if SQLITE_EN
2370: 41 42 4c 45 5f 53 4e 41 50 53 48 4f 54 0a 20 20 ABLE_SNAPSHOT.
2380: 22 45 4e 41 42 4c 45 5f 53 4e 41 50 53 48 4f 54 "ENABLE_SNAPSHOT
2390: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
23a0: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 4f 52 54 LITE_ENABLE_SORT
23b0: 45 52 5f 52 45 46 45 52 45 4e 43 45 53 0a 20 20 ER_REFERENCES.
23c0: 22 45 4e 41 42 4c 45 5f 53 4f 52 54 45 52 5f 52 "ENABLE_SORTER_R
23d0: 45 46 45 52 45 4e 43 45 53 22 2c 0a 23 65 6e 64 EFERENCES",.#end
23e0: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e if.#if SQLITE_EN
23f0: 41 42 4c 45 5f 53 51 4c 4c 4f 47 0a 20 20 22 45 ABLE_SQLLOG. "E
2400: 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 22 2c 0a 23 NABLE_SQLLOG",.#
2410: 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69 6e 65 endif.#if define
2420: 64 28 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f d(SQLITE_ENABLE_
2430: 53 54 41 54 34 29 0a 20 20 22 45 4e 41 42 4c 45 STAT4). "ENABLE
2440: 5f 53 54 41 54 34 22 2c 0a 23 65 6c 69 66 20 64 _STAT4",.#elif d
2450: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 45 4e efined(SQLITE_EN
2460: 41 42 4c 45 5f 53 54 41 54 33 29 0a 20 20 22 45 ABLE_STAT3). "E
2470: 4e 41 42 4c 45 5f 53 54 41 54 33 22 2c 0a 23 65 NABLE_STAT3",.#e
2480: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
2490: 45 4e 41 42 4c 45 5f 53 54 4d 54 56 54 41 42 0a ENABLE_STMTVTAB.
24a0: 20 20 22 45 4e 41 42 4c 45 5f 53 54 4d 54 56 54 "ENABLE_STMTVT
24b0: 41 42 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 AB",.#endif.#if
24c0: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 SQLITE_ENABLE_ST
24d0: 4d 54 5f 53 43 41 4e 53 54 41 54 55 53 0a 20 20 MT_SCANSTATUS.
24e0: 22 45 4e 41 42 4c 45 5f 53 54 4d 54 5f 53 43 41 "ENABLE_STMT_SCA
24f0: 4e 53 54 41 54 55 53 22 2c 0a 23 65 6e 64 69 66 NSTATUS",.#endif
2500: 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 .#if SQLITE_ENAB
2510: 4c 45 5f 55 4e 4b 4e 4f 57 4e 5f 53 51 4c 5f 46 LE_UNKNOWN_SQL_F
2520: 55 4e 43 54 49 4f 4e 0a 20 20 22 45 4e 41 42 4c UNCTION. "ENABL
2530: 45 5f 55 4e 4b 4e 4f 57 4e 5f 53 51 4c 5f 46 55 E_UNKNOWN_SQL_FU
2540: 4e 43 54 49 4f 4e 22 2c 0a 23 65 6e 64 69 66 0a NCTION",.#endif.
2550: 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c #if SQLITE_ENABL
2560: 45 5f 55 4e 4c 4f 43 4b 5f 4e 4f 54 49 46 59 0a E_UNLOCK_NOTIFY.
2570: 20 20 22 45 4e 41 42 4c 45 5f 55 4e 4c 4f 43 4b "ENABLE_UNLOCK
2580: 5f 4e 4f 54 49 46 59 22 2c 0a 23 65 6e 64 69 66 _NOTIFY",.#endif
2590: 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 .#if SQLITE_ENAB
25a0: 4c 45 5f 55 50 44 41 54 45 5f 44 45 4c 45 54 45 LE_UPDATE_DELETE
25b0: 5f 4c 49 4d 49 54 0a 20 20 22 45 4e 41 42 4c 45 _LIMIT. "ENABLE
25c0: 5f 55 50 44 41 54 45 5f 44 45 4c 45 54 45 5f 4c _UPDATE_DELETE_L
25d0: 49 4d 49 54 22 2c 0a 23 65 6e 64 69 66 0a 23 69 IMIT",.#endif.#i
25e0: 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f f SQLITE_ENABLE_
25f0: 55 52 49 5f 30 30 5f 45 52 52 4f 52 0a 20 20 22 URI_00_ERROR. "
2600: 45 4e 41 42 4c 45 5f 55 52 49 5f 30 30 5f 45 52 ENABLE_URI_00_ER
2610: 52 4f 52 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 ROR",.#endif.#if
2620: 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 56 SQLITE_ENABLE_V
2630: 46 53 54 52 41 43 45 0a 20 20 22 45 4e 41 42 4c FSTRACE. "ENABL
2640: 45 5f 56 46 53 54 52 41 43 45 22 2c 0a 23 65 6e E_VFSTRACE",.#en
2650: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 dif.#if SQLITE_E
2660: 4e 41 42 4c 45 5f 57 48 45 52 45 54 52 41 43 45 NABLE_WHERETRACE
2670: 0a 20 20 22 45 4e 41 42 4c 45 5f 57 48 45 52 45 . "ENABLE_WHERE
2680: 54 52 41 43 45 22 2c 0a 23 65 6e 64 69 66 0a 23 TRACE",.#endif.#
2690: 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 if SQLITE_ENABLE
26a0: 5f 5a 49 50 56 46 53 0a 20 20 22 45 4e 41 42 4c _ZIPVFS. "ENABL
26b0: 45 5f 5a 49 50 56 46 53 22 2c 0a 23 65 6e 64 69 E_ZIPVFS",.#endi
26c0: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 58 50 f.#if SQLITE_EXP
26d0: 4c 41 49 4e 5f 45 53 54 49 4d 41 54 45 44 5f 52 LAIN_ESTIMATED_R
26e0: 4f 57 53 0a 20 20 22 45 58 50 4c 41 49 4e 5f 45 OWS. "EXPLAIN_E
26f0: 53 54 49 4d 41 54 45 44 5f 52 4f 57 53 22 2c 0a STIMATED_ROWS",.
2700: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
2710: 45 5f 45 58 54 52 41 5f 49 46 4e 55 4c 4c 52 4f E_EXTRA_IFNULLRO
2720: 57 0a 20 20 22 45 58 54 52 41 5f 49 46 4e 55 4c W. "EXTRA_IFNUL
2730: 4c 52 4f 57 22 2c 0a 23 65 6e 64 69 66 0a 23 69 LROW",.#endif.#i
2740: 66 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54 52 fdef SQLITE_EXTR
2750: 41 5f 49 4e 49 54 0a 20 20 22 45 58 54 52 41 5f A_INIT. "EXTRA_
2760: 49 4e 49 54 3d 22 20 43 54 49 4d 45 4f 50 54 5f INIT=" CTIMEOPT_
2770: 56 41 4c 28 53 51 4c 49 54 45 5f 45 58 54 52 41 VAL(SQLITE_EXTRA
2780: 5f 49 4e 49 54 29 2c 0a 23 65 6e 64 69 66 0a 23 _INIT),.#endif.#
2790: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54 ifdef SQLITE_EXT
27a0: 52 41 5f 53 48 55 54 44 4f 57 4e 0a 20 20 22 45 RA_SHUTDOWN. "E
27b0: 58 54 52 41 5f 53 48 55 54 44 4f 57 4e 3d 22 20 XTRA_SHUTDOWN="
27c0: 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c CTIMEOPT_VAL(SQL
27d0: 49 54 45 5f 45 58 54 52 41 5f 53 48 55 54 44 4f ITE_EXTRA_SHUTDO
27e0: 57 4e 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 WN),.#endif.#ifd
27f0: 65 66 20 53 51 4c 49 54 45 5f 46 54 53 33 5f 4d ef SQLITE_FTS3_M
2800: 41 58 5f 45 58 50 52 5f 44 45 50 54 48 0a 20 20 AX_EXPR_DEPTH.
2810: 22 46 54 53 33 5f 4d 41 58 5f 45 58 50 52 5f 44 "FTS3_MAX_EXPR_D
2820: 45 50 54 48 3d 22 20 43 54 49 4d 45 4f 50 54 5f EPTH=" CTIMEOPT_
2830: 56 41 4c 28 53 51 4c 49 54 45 5f 46 54 53 33 5f VAL(SQLITE_FTS3_
2840: 4d 41 58 5f 45 58 50 52 5f 44 45 50 54 48 29 2c MAX_EXPR_DEPTH),
2850: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
2860: 54 45 5f 46 54 53 35 5f 45 4e 41 42 4c 45 5f 54 TE_FTS5_ENABLE_T
2870: 45 53 54 5f 4d 49 0a 20 20 22 46 54 53 35 5f 45 EST_MI. "FTS5_E
2880: 4e 41 42 4c 45 5f 54 45 53 54 5f 4d 49 22 2c 0a NABLE_TEST_MI",.
2890: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
28a0: 45 5f 46 54 53 35 5f 4e 4f 5f 57 49 54 48 4f 55 E_FTS5_NO_WITHOU
28b0: 54 5f 52 4f 57 49 44 0a 20 20 22 46 54 53 35 5f T_ROWID. "FTS5_
28c0: 4e 4f 5f 57 49 54 48 4f 55 54 5f 52 4f 57 49 44 NO_WITHOUT_ROWID
28d0: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
28e0: 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 20 LITE_HAS_CODEC.
28f0: 20 22 48 41 53 5f 43 4f 44 45 43 22 2c 0a 23 65 "HAS_CODEC",.#e
2900: 6e 64 69 66 0a 23 69 66 20 48 41 56 45 5f 49 53 ndif.#if HAVE_IS
2910: 4e 41 4e 20 7c 7c 20 53 51 4c 49 54 45 5f 48 41 NAN || SQLITE_HA
2920: 56 45 5f 49 53 4e 41 4e 0a 20 20 22 48 41 56 45 VE_ISNAN. "HAVE
2930: 5f 49 53 4e 41 4e 22 2c 0a 23 65 6e 64 69 66 0a _ISNAN",.#endif.
2940: 23 69 66 20 53 51 4c 49 54 45 5f 48 4f 4d 45 47 #if SQLITE_HOMEG
2950: 52 4f 57 4e 5f 52 45 43 55 52 53 49 56 45 5f 4d ROWN_RECURSIVE_M
2960: 55 54 45 58 0a 20 20 22 48 4f 4d 45 47 52 4f 57 UTEX. "HOMEGROW
2970: 4e 5f 52 45 43 55 52 53 49 56 45 5f 4d 55 54 45 N_RECURSIVE_MUTE
2980: 58 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 X",.#endif.#if S
2990: 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5f 41 46 50 QLITE_IGNORE_AFP
29a0: 5f 4c 4f 43 4b 5f 45 52 52 4f 52 53 0a 20 20 22 _LOCK_ERRORS. "
29b0: 49 47 4e 4f 52 45 5f 41 46 50 5f 4c 4f 43 4b 5f IGNORE_AFP_LOCK_
29c0: 45 52 52 4f 52 53 22 2c 0a 23 65 6e 64 69 66 0a ERRORS",.#endif.
29d0: 23 69 66 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 #if SQLITE_IGNOR
29e0: 45 5f 46 4c 4f 43 4b 5f 4c 4f 43 4b 5f 45 52 52 E_FLOCK_LOCK_ERR
29f0: 4f 52 53 0a 20 20 22 49 47 4e 4f 52 45 5f 46 4c ORS. "IGNORE_FL
2a00: 4f 43 4b 5f 4c 4f 43 4b 5f 45 52 52 4f 52 53 22 OCK_LOCK_ERRORS"
2a10: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
2a20: 49 54 45 5f 49 4e 4c 49 4e 45 5f 4d 45 4d 43 50 ITE_INLINE_MEMCP
2a30: 59 0a 20 20 22 49 4e 4c 49 4e 45 5f 4d 45 4d 43 Y. "INLINE_MEMC
2a40: 50 59 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 PY",.#endif.#if
2a50: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 SQLITE_INT64_TYP
2a60: 45 0a 20 20 22 49 4e 54 36 34 5f 54 59 50 45 22 E. "INT64_TYPE"
2a70: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 ,.#endif.#ifdef
2a80: 53 51 4c 49 54 45 5f 49 4e 54 45 47 52 49 54 59 SQLITE_INTEGRITY
2a90: 5f 43 48 45 43 4b 5f 45 52 52 4f 52 5f 4d 41 58 _CHECK_ERROR_MAX
2aa0: 0a 20 20 22 49 4e 54 45 47 52 49 54 59 5f 43 48 . "INTEGRITY_CH
2ab0: 45 43 4b 5f 45 52 52 4f 52 5f 4d 41 58 3d 22 20 ECK_ERROR_MAX="
2ac0: 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c CTIMEOPT_VAL(SQL
2ad0: 49 54 45 5f 49 4e 54 45 47 52 49 54 59 5f 43 48 ITE_INTEGRITY_CH
2ae0: 45 43 4b 5f 45 52 52 4f 52 5f 4d 41 58 29 2c 0a ECK_ERROR_MAX),.
2af0: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
2b00: 45 5f 4c 49 4b 45 5f 44 4f 45 53 4e 54 5f 4d 41 E_LIKE_DOESNT_MA
2b10: 54 43 48 5f 42 4c 4f 42 53 0a 20 20 22 4c 49 4b TCH_BLOBS. "LIK
2b20: 45 5f 44 4f 45 53 4e 54 5f 4d 41 54 43 48 5f 42 E_DOESNT_MATCH_B
2b30: 4c 4f 42 53 22 2c 0a 23 65 6e 64 69 66 0a 23 69 LOBS",.#endif.#i
2b40: 66 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 54 52 f SQLITE_LOCK_TR
2b50: 41 43 45 0a 20 20 22 4c 4f 43 4b 5f 54 52 41 43 ACE. "LOCK_TRAC
2b60: 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 E",.#endif.#if S
2b70: 51 4c 49 54 45 5f 4c 4f 47 5f 43 41 43 48 45 5f QLITE_LOG_CACHE_
2b80: 53 50 49 4c 4c 0a 20 20 22 4c 4f 47 5f 43 41 43 SPILL. "LOG_CAC
2b90: 48 45 5f 53 50 49 4c 4c 22 2c 0a 23 65 6e 64 69 HE_SPILL",.#endi
2ba0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
2bb0: 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49 MALLOC_SOFT_LIMI
2bc0: 54 0a 20 20 22 4d 41 4c 4c 4f 43 5f 53 4f 46 54 T. "MALLOC_SOFT
2bd0: 5f 4c 49 4d 49 54 3d 22 20 43 54 49 4d 45 4f 50 _LIMIT=" CTIMEOP
2be0: 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 4d 41 4c T_VAL(SQLITE_MAL
2bf0: 4c 4f 43 5f 53 4f 46 54 5f 4c 49 4d 49 54 29 2c LOC_SOFT_LIMIT),
2c00: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 .#endif.#ifdef S
2c10: 51 4c 49 54 45 5f 4d 41 58 5f 41 54 54 41 43 48 QLITE_MAX_ATTACH
2c20: 45 44 0a 20 20 22 4d 41 58 5f 41 54 54 41 43 48 ED. "MAX_ATTACH
2c30: 45 44 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 ED=" CTIMEOPT_VA
2c40: 4c 28 53 51 4c 49 54 45 5f 4d 41 58 5f 41 54 54 L(SQLITE_MAX_ATT
2c50: 41 43 48 45 44 29 2c 0a 23 65 6e 64 69 66 0a 23 ACHED),.#endif.#
2c60: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 ifdef SQLITE_MAX
2c70: 5f 43 4f 4c 55 4d 4e 0a 20 20 22 4d 41 58 5f 43 _COLUMN. "MAX_C
2c80: 4f 4c 55 4d 4e 3d 22 20 43 54 49 4d 45 4f 50 54 OLUMN=" CTIMEOPT
2c90: 5f 56 41 4c 28 53 51 4c 49 54 45 5f 4d 41 58 5f _VAL(SQLITE_MAX_
2ca0: 43 4f 4c 55 4d 4e 29 2c 0a 23 65 6e 64 69 66 0a COLUMN),.#endif.
2cb0: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 #ifdef SQLITE_MA
2cc0: 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 X_COMPOUND_SELEC
2cd0: 54 0a 20 20 22 4d 41 58 5f 43 4f 4d 50 4f 55 4e T. "MAX_COMPOUN
2ce0: 44 5f 53 45 4c 45 43 54 3d 22 20 43 54 49 4d 45 D_SELECT=" CTIME
2cf0: 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 4d OPT_VAL(SQLITE_M
2d00: 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 AX_COMPOUND_SELE
2d10: 43 54 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 CT),.#endif.#ifd
2d20: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 ef SQLITE_MAX_DE
2d30: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a FAULT_PAGE_SIZE.
2d40: 20 20 22 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 "MAX_DEFAULT_P
2d50: 41 47 45 5f 53 49 5a 45 3d 22 20 43 54 49 4d 45 AGE_SIZE=" CTIME
2d60: 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 4d OPT_VAL(SQLITE_M
2d70: 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f AX_DEFAULT_PAGE_
2d80: 53 49 5a 45 29 2c 0a 23 65 6e 64 69 66 0a 23 69 SIZE),.#endif.#i
2d90: 66 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f fdef SQLITE_MAX_
2da0: 45 58 50 52 5f 44 45 50 54 48 0a 20 20 22 4d 41 EXPR_DEPTH. "MA
2db0: 58 5f 45 58 50 52 5f 44 45 50 54 48 3d 22 20 43 X_EXPR_DEPTH=" C
2dc0: 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 TIMEOPT_VAL(SQLI
2dd0: 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54 TE_MAX_EXPR_DEPT
2de0: 48 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 H),.#endif.#ifde
2df0: 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e f SQLITE_MAX_FUN
2e00: 43 54 49 4f 4e 5f 41 52 47 0a 20 20 22 4d 41 58 CTION_ARG. "MAX
2e10: 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3d 22 20 _FUNCTION_ARG="
2e20: 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c CTIMEOPT_VAL(SQL
2e30: 49 54 45 5f 4d 41 58 5f 46 55 4e 43 54 49 4f 4e ITE_MAX_FUNCTION
2e40: 5f 41 52 47 29 2c 0a 23 65 6e 64 69 66 0a 23 69 _ARG),.#endif.#i
2e50: 66 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f fdef SQLITE_MAX_
2e60: 4c 45 4e 47 54 48 0a 20 20 22 4d 41 58 5f 4c 45 LENGTH. "MAX_LE
2e70: 4e 47 54 48 3d 22 20 43 54 49 4d 45 4f 50 54 5f NGTH=" CTIMEOPT_
2e80: 56 41 4c 28 53 51 4c 49 54 45 5f 4d 41 58 5f 4c VAL(SQLITE_MAX_L
2e90: 45 4e 47 54 48 29 2c 0a 23 65 6e 64 69 66 0a 23 ENGTH),.#endif.#
2ea0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 ifdef SQLITE_MAX
2eb0: 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
2ec0: 4e 47 54 48 0a 20 20 22 4d 41 58 5f 4c 49 4b 45 NGTH. "MAX_LIKE
2ed0: 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3d _PATTERN_LENGTH=
2ee0: 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 " CTIMEOPT_VAL(S
2ef0: 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b 45 5f 50 QLITE_MAX_LIKE_P
2f00: 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 29 2c 0a ATTERN_LENGTH),.
2f10: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 #endif.#ifdef SQ
2f20: 4c 49 54 45 5f 4d 41 58 5f 4d 45 4d 4f 52 59 0a LITE_MAX_MEMORY.
2f30: 20 20 22 4d 41 58 5f 4d 45 4d 4f 52 59 3d 22 20 "MAX_MEMORY="
2f40: 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c CTIMEOPT_VAL(SQL
2f50: 49 54 45 5f 4d 41 58 5f 4d 45 4d 4f 52 59 29 2c ITE_MAX_MEMORY),
2f60: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 .#endif.#ifdef S
2f70: 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 QLITE_MAX_MMAP_S
2f80: 49 5a 45 0a 20 20 22 4d 41 58 5f 4d 4d 41 50 5f IZE. "MAX_MMAP_
2f90: 53 49 5a 45 3d 22 20 43 54 49 4d 45 4f 50 54 5f SIZE=" CTIMEOPT_
2fa0: 56 41 4c 28 53 51 4c 49 54 45 5f 4d 41 58 5f 4d VAL(SQLITE_MAX_M
2fb0: 4d 41 50 5f 53 49 5a 45 29 2c 0a 23 65 6e 64 69 MAP_SIZE),.#endi
2fc0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
2fd0: 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5f 0a 20 MAX_MMAP_SIZE_.
2fe0: 20 22 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5f "MAX_MMAP_SIZE_
2ff0: 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 =" CTIMEOPT_VAL(
3000: 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f SQLITE_MAX_MMAP_
3010: 53 49 5a 45 5f 29 2c 0a 23 65 6e 64 69 66 0a 23 SIZE_),.#endif.#
3020: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 ifdef SQLITE_MAX
3030: 5f 50 41 47 45 5f 43 4f 55 4e 54 0a 20 20 22 4d _PAGE_COUNT. "M
3040: 41 58 5f 50 41 47 45 5f 43 4f 55 4e 54 3d 22 20 AX_PAGE_COUNT="
3050: 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c CTIMEOPT_VAL(SQL
3060: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43 4f 55 ITE_MAX_PAGE_COU
3070: 4e 54 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 NT),.#endif.#ifd
3080: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 ef SQLITE_MAX_PA
3090: 47 45 5f 53 49 5a 45 0a 20 20 22 4d 41 58 5f 50 GE_SIZE. "MAX_P
30a0: 41 47 45 5f 53 49 5a 45 3d 22 20 43 54 49 4d 45 AGE_SIZE=" CTIME
30b0: 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 4d OPT_VAL(SQLITE_M
30c0: 41 58 5f 50 41 47 45 5f 53 49 5a 45 29 2c 0a 23 AX_PAGE_SIZE),.#
30d0: 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c endif.#ifdef SQL
30e0: 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 ITE_MAX_SCHEMA_R
30f0: 45 54 52 59 0a 20 20 22 4d 41 58 5f 53 43 48 45 ETRY. "MAX_SCHE
3100: 4d 41 5f 52 45 54 52 59 3d 22 20 43 54 49 4d 45 MA_RETRY=" CTIME
3110: 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 4d OPT_VAL(SQLITE_M
3120: 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 29 AX_SCHEMA_RETRY)
3130: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 ,.#endif.#ifdef
3140: 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 4c 5f 4c SQLITE_MAX_SQL_L
3150: 45 4e 47 54 48 0a 20 20 22 4d 41 58 5f 53 51 4c ENGTH. "MAX_SQL
3160: 5f 4c 45 4e 47 54 48 3d 22 20 43 54 49 4d 45 4f _LENGTH=" CTIMEO
3170: 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 4d 41 PT_VAL(SQLITE_MA
3180: 58 5f 53 51 4c 5f 4c 45 4e 47 54 48 29 2c 0a 23 X_SQL_LENGTH),.#
3190: 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c endif.#ifdef SQL
31a0: 49 54 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f ITE_MAX_TRIGGER_
31b0: 44 45 50 54 48 0a 20 20 22 4d 41 58 5f 54 52 49 DEPTH. "MAX_TRI
31c0: 47 47 45 52 5f 44 45 50 54 48 3d 22 20 43 54 49 GGER_DEPTH=" CTI
31d0: 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 MEOPT_VAL(SQLITE
31e0: 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 _MAX_TRIGGER_DEP
31f0: 54 48 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 TH),.#endif.#ifd
3200: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 56 41 ef SQLITE_MAX_VA
3210: 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 0a 20 20 RIABLE_NUMBER.
3220: 22 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 "MAX_VARIABLE_NU
3230: 4d 42 45 52 3d 22 20 43 54 49 4d 45 4f 50 54 5f MBER=" CTIMEOPT_
3240: 56 41 4c 28 53 51 4c 49 54 45 5f 4d 41 58 5f 56 VAL(SQLITE_MAX_V
3250: 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 29 2c ARIABLE_NUMBER),
3260: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 .#endif.#ifdef S
3270: 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f QLITE_MAX_VDBE_O
3280: 50 0a 20 20 22 4d 41 58 5f 56 44 42 45 5f 4f 50 P. "MAX_VDBE_OP
3290: 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 =" CTIMEOPT_VAL(
32a0: 53 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f SQLITE_MAX_VDBE_
32b0: 4f 50 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 OP),.#endif.#ifd
32c0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 57 4f ef SQLITE_MAX_WO
32d0: 52 4b 45 52 5f 54 48 52 45 41 44 53 0a 20 20 22 RKER_THREADS. "
32e0: 4d 41 58 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 MAX_WORKER_THREA
32f0: 44 53 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 DS=" CTIMEOPT_VA
3300: 4c 28 53 51 4c 49 54 45 5f 4d 41 58 5f 57 4f 52 L(SQLITE_MAX_WOR
3310: 4b 45 52 5f 54 48 52 45 41 44 53 29 2c 0a 23 65 KER_THREADS),.#e
3320: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
3330: 4d 45 4d 44 45 42 55 47 0a 20 20 22 4d 45 4d 44 MEMDEBUG. "MEMD
3340: 45 42 55 47 22 2c 0a 23 65 6e 64 69 66 0a 23 69 EBUG",.#endif.#i
3350: 66 20 53 51 4c 49 54 45 5f 4d 49 58 45 44 5f 45 f SQLITE_MIXED_E
3360: 4e 44 49 41 4e 5f 36 34 42 49 54 5f 46 4c 4f 41 NDIAN_64BIT_FLOA
3370: 54 0a 20 20 22 4d 49 58 45 44 5f 45 4e 44 49 41 T. "MIXED_ENDIA
3380: 4e 5f 36 34 42 49 54 5f 46 4c 4f 41 54 22 2c 0a N_64BIT_FLOAT",.
3390: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
33a0: 45 5f 4d 4d 41 50 5f 52 45 41 44 57 52 49 54 45 E_MMAP_READWRITE
33b0: 0a 20 20 22 4d 4d 41 50 5f 52 45 41 44 57 52 49 . "MMAP_READWRI
33c0: 54 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 TE",.#endif.#if
33d0: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4e 4f 4f SQLITE_MUTEX_NOO
33e0: 50 0a 20 20 22 4d 55 54 45 58 5f 4e 4f 4f 50 22 P. "MUTEX_NOOP"
33f0: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
3400: 49 54 45 5f 4d 55 54 45 58 5f 4e 52 45 46 0a 20 ITE_MUTEX_NREF.
3410: 20 22 4d 55 54 45 58 5f 4e 52 45 46 22 2c 0a 23 "MUTEX_NREF",.#
3420: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
3430: 5f 4d 55 54 45 58 5f 4f 4d 49 54 0a 20 20 22 4d _MUTEX_OMIT. "M
3440: 55 54 45 58 5f 4f 4d 49 54 22 2c 0a 23 65 6e 64 UTEX_OMIT",.#end
3450: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4d 55 if.#if SQLITE_MU
3460: 54 45 58 5f 50 54 48 52 45 41 44 53 0a 20 20 22 TEX_PTHREADS. "
3470: 4d 55 54 45 58 5f 50 54 48 52 45 41 44 53 22 2c MUTEX_PTHREADS",
3480: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
3490: 54 45 5f 4d 55 54 45 58 5f 57 33 32 0a 20 20 22 TE_MUTEX_W32. "
34a0: 4d 55 54 45 58 5f 57 33 32 22 2c 0a 23 65 6e 64 MUTEX_W32",.#end
34b0: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4e 45 if.#if SQLITE_NE
34c0: 45 44 5f 45 52 52 5f 4e 41 4d 45 0a 20 20 22 4e ED_ERR_NAME. "N
34d0: 45 45 44 5f 45 52 52 5f 4e 41 4d 45 22 2c 0a 23 EED_ERR_NAME",.#
34e0: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
34f0: 5f 4e 4f 49 4e 4c 49 4e 45 0a 20 20 22 4e 4f 49 _NOINLINE. "NOI
3500: 4e 4c 49 4e 45 22 2c 0a 23 65 6e 64 69 66 0a 23 NLINE",.#endif.#
3510: 69 66 20 53 51 4c 49 54 45 5f 4e 4f 5f 53 59 4e if SQLITE_NO_SYN
3520: 43 0a 20 20 22 4e 4f 5f 53 59 4e 43 22 2c 0a 23 C. "NO_SYNC",.#
3530: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
3540: 5f 4f 4d 49 54 5f 41 4c 54 45 52 54 41 42 4c 45 _OMIT_ALTERTABLE
3550: 0a 20 20 22 4f 4d 49 54 5f 41 4c 54 45 52 54 41 . "OMIT_ALTERTA
3560: 42 4c 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 BLE",.#endif.#if
3570: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 4e 41 SQLITE_OMIT_ANA
3580: 4c 59 5a 45 0a 20 20 22 4f 4d 49 54 5f 41 4e 41 LYZE. "OMIT_ANA
3590: 4c 59 5a 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 LYZE",.#endif.#i
35a0: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 54 f SQLITE_OMIT_AT
35b0: 54 41 43 48 0a 20 20 22 4f 4d 49 54 5f 41 54 54 TACH. "OMIT_ATT
35c0: 41 43 48 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 ACH",.#endif.#if
35d0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 SQLITE_OMIT_AUT
35e0: 48 4f 52 49 5a 41 54 49 4f 4e 0a 20 20 22 4f 4d HORIZATION. "OM
35f0: 49 54 5f 41 55 54 48 4f 52 49 5a 41 54 49 4f 4e IT_AUTHORIZATION
3600: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
3610: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e LITE_OMIT_AUTOIN
3620: 43 52 45 4d 45 4e 54 0a 20 20 22 4f 4d 49 54 5f CREMENT. "OMIT_
3630: 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 22 2c 0a AUTOINCREMENT",.
3640: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
3650: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 0a E_OMIT_AUTOINIT.
3660: 20 20 22 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 "OMIT_AUTOINIT
3670: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
3680: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 4d 41 LITE_OMIT_AUTOMA
3690: 54 49 43 5f 49 4e 44 45 58 0a 20 20 22 4f 4d 49 TIC_INDEX. "OMI
36a0: 54 5f 41 55 54 4f 4d 41 54 49 43 5f 49 4e 44 45 T_AUTOMATIC_INDE
36b0: 58 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 X",.#endif.#if S
36c0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 QLITE_OMIT_AUTOR
36d0: 45 53 45 54 0a 20 20 22 4f 4d 49 54 5f 41 55 54 ESET. "OMIT_AUT
36e0: 4f 52 45 53 45 54 22 2c 0a 23 65 6e 64 69 66 0a ORESET",.#endif.
36f0: 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f #if SQLITE_OMIT_
3700: 41 55 54 4f 56 41 43 55 55 4d 0a 20 20 22 4f 4d AUTOVACUUM. "OM
3710: 49 54 5f 41 55 54 4f 56 41 43 55 55 4d 22 2c 0a IT_AUTOVACUUM",.
3720: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
3730: 45 5f 4f 4d 49 54 5f 42 45 54 57 45 45 4e 5f 4f E_OMIT_BETWEEN_O
3740: 50 54 49 4d 49 5a 41 54 49 4f 4e 0a 20 20 22 4f PTIMIZATION. "O
3750: 4d 49 54 5f 42 45 54 57 45 45 4e 5f 4f 50 54 49 MIT_BETWEEN_OPTI
3760: 4d 49 5a 41 54 49 4f 4e 22 2c 0a 23 65 6e 64 69 MIZATION",.#endi
3770: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 f.#if SQLITE_OMI
3780: 54 5f 42 4c 4f 42 5f 4c 49 54 45 52 41 4c 0a 20 T_BLOB_LITERAL.
3790: 20 22 4f 4d 49 54 5f 42 4c 4f 42 5f 4c 49 54 45 "OMIT_BLOB_LITE
37a0: 52 41 4c 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 RAL",.#endif.#if
37b0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 42 54 52 SQLITE_OMIT_BTR
37c0: 45 45 43 4f 55 4e 54 0a 20 20 22 4f 4d 49 54 5f EECOUNT. "OMIT_
37d0: 42 54 52 45 45 43 4f 55 4e 54 22 2c 0a 23 65 6e BTREECOUNT",.#en
37e0: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f dif.#if SQLITE_O
37f0: 4d 49 54 5f 43 41 53 54 0a 20 20 22 4f 4d 49 54 MIT_CAST. "OMIT
3800: 5f 43 41 53 54 22 2c 0a 23 65 6e 64 69 66 0a 23 _CAST",.#endif.#
3810: 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 if SQLITE_OMIT_C
3820: 48 45 43 4b 0a 20 20 22 4f 4d 49 54 5f 43 48 45 HECK. "OMIT_CHE
3830: 43 4b 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 CK",.#endif.#if
3840: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 SQLITE_OMIT_COMP
3850: 4c 45 54 45 0a 20 20 22 4f 4d 49 54 5f 43 4f 4d LETE. "OMIT_COM
3860: 50 4c 45 54 45 22 2c 0a 23 65 6e 64 69 66 0a 23 PLETE",.#endif.#
3870: 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 if SQLITE_OMIT_C
3880: 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 0a 20 OMPOUND_SELECT.
3890: 20 22 4f 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f "OMIT_COMPOUND_
38a0: 53 45 4c 45 43 54 22 2c 0a 23 65 6e 64 69 66 0a SELECT",.#endif.
38b0: 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f #if SQLITE_OMIT_
38c0: 43 4f 4e 46 4c 49 43 54 5f 43 4c 41 55 53 45 0a CONFLICT_CLAUSE.
38d0: 20 20 22 4f 4d 49 54 5f 43 4f 4e 46 4c 49 43 54 "OMIT_CONFLICT
38e0: 5f 43 4c 41 55 53 45 22 2c 0a 23 65 6e 64 69 66 _CLAUSE",.#endif
38f0: 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 .#if SQLITE_OMIT
3900: 5f 43 54 45 0a 20 20 22 4f 4d 49 54 5f 43 54 45 _CTE. "OMIT_CTE
3910: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
3920: 4c 49 54 45 5f 4f 4d 49 54 5f 44 41 54 45 54 49 LITE_OMIT_DATETI
3930: 4d 45 5f 46 55 4e 43 53 0a 20 20 22 4f 4d 49 54 ME_FUNCS. "OMIT
3940: 5f 44 41 54 45 54 49 4d 45 5f 46 55 4e 43 53 22 _DATETIME_FUNCS"
3950: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
3960: 49 54 45 5f 4f 4d 49 54 5f 44 45 43 4c 54 59 50 ITE_OMIT_DECLTYP
3970: 45 0a 20 20 22 4f 4d 49 54 5f 44 45 43 4c 54 59 E. "OMIT_DECLTY
3980: 50 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 PE",.#endif.#if
3990: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 SQLITE_OMIT_DEPR
39a0: 45 43 41 54 45 44 0a 20 20 22 4f 4d 49 54 5f 44 ECATED. "OMIT_D
39b0: 45 50 52 45 43 41 54 45 44 22 2c 0a 23 65 6e 64 EPRECATED",.#end
39c0: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d if.#if SQLITE_OM
39d0: 49 54 5f 44 49 53 4b 49 4f 0a 20 20 22 4f 4d 49 IT_DISKIO. "OMI
39e0: 54 5f 44 49 53 4b 49 4f 22 2c 0a 23 65 6e 64 69 T_DISKIO",.#endi
39f0: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 f.#if SQLITE_OMI
3a00: 54 5f 45 58 50 4c 41 49 4e 0a 20 20 22 4f 4d 49 T_EXPLAIN. "OMI
3a10: 54 5f 45 58 50 4c 41 49 4e 22 2c 0a 23 65 6e 64 T_EXPLAIN",.#end
3a20: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d if.#if SQLITE_OM
3a30: 49 54 5f 46 4c 41 47 5f 50 52 41 47 4d 41 53 0a IT_FLAG_PRAGMAS.
3a40: 20 20 22 4f 4d 49 54 5f 46 4c 41 47 5f 50 52 41 "OMIT_FLAG_PRA
3a50: 47 4d 41 53 22 2c 0a 23 65 6e 64 69 66 0a 23 69 GMAS",.#endif.#i
3a60: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c f SQLITE_OMIT_FL
3a70: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 20 20 22 OATING_POINT. "
3a80: 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f OMIT_FLOATING_PO
3a90: 49 4e 54 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 INT",.#endif.#if
3aa0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4f 52 SQLITE_OMIT_FOR
3ab0: 45 49 47 4e 5f 4b 45 59 0a 20 20 22 4f 4d 49 54 EIGN_KEY. "OMIT
3ac0: 5f 46 4f 52 45 49 47 4e 5f 4b 45 59 22 2c 0a 23 _FOREIGN_KEY",.#
3ad0: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
3ae0: 5f 4f 4d 49 54 5f 47 45 54 5f 54 41 42 4c 45 0a _OMIT_GET_TABLE.
3af0: 20 20 22 4f 4d 49 54 5f 47 45 54 5f 54 41 42 4c "OMIT_GET_TABL
3b00: 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 E",.#endif.#if S
3b10: 51 4c 49 54 45 5f 4f 4d 49 54 5f 48 45 58 5f 49 QLITE_OMIT_HEX_I
3b20: 4e 54 45 47 45 52 0a 20 20 22 4f 4d 49 54 5f 48 NTEGER. "OMIT_H
3b30: 45 58 5f 49 4e 54 45 47 45 52 22 2c 0a 23 65 6e EX_INTEGER",.#en
3b40: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f dif.#if SQLITE_O
3b50: 4d 49 54 5f 49 4e 43 52 42 4c 4f 42 0a 20 20 22 MIT_INCRBLOB. "
3b60: 4f 4d 49 54 5f 49 4e 43 52 42 4c 4f 42 22 2c 0a OMIT_INCRBLOB",.
3b70: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
3b80: 45 5f 4f 4d 49 54 5f 49 4e 54 45 47 52 49 54 59 E_OMIT_INTEGRITY
3b90: 5f 43 48 45 43 4b 0a 20 20 22 4f 4d 49 54 5f 49 _CHECK. "OMIT_I
3ba0: 4e 54 45 47 52 49 54 59 5f 43 48 45 43 4b 22 2c NTEGRITY_CHECK",
3bb0: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
3bc0: 54 45 5f 4f 4d 49 54 5f 4c 49 4b 45 5f 4f 50 54 TE_OMIT_LIKE_OPT
3bd0: 49 4d 49 5a 41 54 49 4f 4e 0a 20 20 22 4f 4d 49 IMIZATION. "OMI
3be0: 54 5f 4c 49 4b 45 5f 4f 50 54 49 4d 49 5a 41 54 T_LIKE_OPTIMIZAT
3bf0: 49 4f 4e 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 ION",.#endif.#if
3c00: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4c 4f 41 SQLITE_OMIT_LOA
3c10: 44 5f 45 58 54 45 4e 53 49 4f 4e 0a 20 20 22 4f D_EXTENSION. "O
3c20: 4d 49 54 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 MIT_LOAD_EXTENSI
3c30: 4f 4e 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 ON",.#endif.#if
3c40: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4c 4f 43 41 SQLITE_OMIT_LOCA
3c50: 4c 54 49 4d 45 0a 20 20 22 4f 4d 49 54 5f 4c 4f LTIME. "OMIT_LO
3c60: 43 41 4c 54 49 4d 45 22 2c 0a 23 65 6e 64 69 66 CALTIME",.#endif
3c70: 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 .#if SQLITE_OMIT
3c80: 5f 4c 4f 4f 4b 41 53 49 44 45 0a 20 20 22 4f 4d _LOOKASIDE. "OM
3c90: 49 54 5f 4c 4f 4f 4b 41 53 49 44 45 22 2c 0a 23 IT_LOOKASIDE",.#
3ca0: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
3cb0: 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 44 42 0a 20 _OMIT_MEMORYDB.
3cc0: 20 22 4f 4d 49 54 5f 4d 45 4d 4f 52 59 44 42 22 "OMIT_MEMORYDB"
3cd0: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
3ce0: 49 54 45 5f 4f 4d 49 54 5f 4f 52 5f 4f 50 54 49 ITE_OMIT_OR_OPTI
3cf0: 4d 49 5a 41 54 49 4f 4e 0a 20 20 22 4f 4d 49 54 MIZATION. "OMIT
3d00: 5f 4f 52 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e _OR_OPTIMIZATION
3d10: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
3d20: 4c 49 54 45 5f 4f 4d 49 54 5f 50 41 47 45 52 5f LITE_OMIT_PAGER_
3d30: 50 52 41 47 4d 41 53 0a 20 20 22 4f 4d 49 54 5f PRAGMAS. "OMIT_
3d40: 50 41 47 45 52 5f 50 52 41 47 4d 41 53 22 2c 0a PAGER_PRAGMAS",.
3d50: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
3d60: 45 5f 4f 4d 49 54 5f 50 41 52 53 45 52 5f 54 52 E_OMIT_PARSER_TR
3d70: 41 43 45 0a 20 20 22 4f 4d 49 54 5f 50 41 52 53 ACE. "OMIT_PARS
3d80: 45 52 5f 54 52 41 43 45 22 2c 0a 23 65 6e 64 69 ER_TRACE",.#endi
3d90: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 f.#if SQLITE_OMI
3da0: 54 5f 50 4f 50 45 4e 0a 20 20 22 4f 4d 49 54 5f T_POPEN. "OMIT_
3db0: 50 4f 50 45 4e 22 2c 0a 23 65 6e 64 69 66 0a 23 POPEN",.#endif.#
3dc0: 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 50 if SQLITE_OMIT_P
3dd0: 52 41 47 4d 41 0a 20 20 22 4f 4d 49 54 5f 50 52 RAGMA. "OMIT_PR
3de0: 41 47 4d 41 22 2c 0a 23 65 6e 64 69 66 0a 23 69 AGMA",.#endif.#i
3df0: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 50 52 f SQLITE_OMIT_PR
3e00: 4f 47 52 45 53 53 5f 43 41 4c 4c 42 41 43 4b 0a OGRESS_CALLBACK.
3e10: 20 20 22 4f 4d 49 54 5f 50 52 4f 47 52 45 53 53 "OMIT_PROGRESS
3e20: 5f 43 41 4c 4c 42 41 43 4b 22 2c 0a 23 65 6e 64 _CALLBACK",.#end
3e30: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d if.#if SQLITE_OM
3e40: 49 54 5f 51 55 49 43 4b 42 41 4c 41 4e 43 45 0a IT_QUICKBALANCE.
3e50: 20 20 22 4f 4d 49 54 5f 51 55 49 43 4b 42 41 4c "OMIT_QUICKBAL
3e60: 41 4e 43 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 ANCE",.#endif.#i
3e70: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 52 45 f SQLITE_OMIT_RE
3e80: 49 4e 44 45 58 0a 20 20 22 4f 4d 49 54 5f 52 45 INDEX. "OMIT_RE
3e90: 49 4e 44 45 58 22 2c 0a 23 65 6e 64 69 66 0a 23 INDEX",.#endif.#
3ea0: 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 53 if SQLITE_OMIT_S
3eb0: 43 48 45 4d 41 5f 50 52 41 47 4d 41 53 0a 20 20 CHEMA_PRAGMAS.
3ec0: 22 4f 4d 49 54 5f 53 43 48 45 4d 41 5f 50 52 41 "OMIT_SCHEMA_PRA
3ed0: 47 4d 41 53 22 2c 0a 23 65 6e 64 69 66 0a 23 69 GMAS",.#endif.#i
3ee0: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 53 43 f SQLITE_OMIT_SC
3ef0: 48 45 4d 41 5f 56 45 52 53 49 4f 4e 5f 50 52 41 HEMA_VERSION_PRA
3f00: 47 4d 41 53 0a 20 20 22 4f 4d 49 54 5f 53 43 48 GMAS. "OMIT_SCH
3f10: 45 4d 41 5f 56 45 52 53 49 4f 4e 5f 50 52 41 47 EMA_VERSION_PRAG
3f20: 4d 41 53 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 MAS",.#endif.#if
3f30: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 53 48 41 SQLITE_OMIT_SHA
3f40: 52 45 44 5f 43 41 43 48 45 0a 20 20 22 4f 4d 49 RED_CACHE. "OMI
3f50: 54 5f 53 48 41 52 45 44 5f 43 41 43 48 45 22 2c T_SHARED_CACHE",
3f60: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
3f70: 54 45 5f 4f 4d 49 54 5f 53 48 55 54 44 4f 57 4e TE_OMIT_SHUTDOWN
3f80: 5f 44 49 52 45 43 54 4f 52 49 45 53 0a 20 20 22 _DIRECTORIES. "
3f90: 4f 4d 49 54 5f 53 48 55 54 44 4f 57 4e 5f 44 49 OMIT_SHUTDOWN_DI
3fa0: 52 45 43 54 4f 52 49 45 53 22 2c 0a 23 65 6e 64 RECTORIES",.#end
3fb0: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d if.#if SQLITE_OM
3fc0: 49 54 5f 53 55 42 51 55 45 52 59 0a 20 20 22 4f IT_SUBQUERY. "O
3fd0: 4d 49 54 5f 53 55 42 51 55 45 52 59 22 2c 0a 23 MIT_SUBQUERY",.#
3fe0: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
3ff0: 5f 4f 4d 49 54 5f 54 43 4c 5f 56 41 52 49 41 42 _OMIT_TCL_VARIAB
4000: 4c 45 0a 20 20 22 4f 4d 49 54 5f 54 43 4c 5f 56 LE. "OMIT_TCL_V
4010: 41 52 49 41 42 4c 45 22 2c 0a 23 65 6e 64 69 66 ARIABLE",.#endif
4020: 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 .#if SQLITE_OMIT
4030: 5f 54 45 4d 50 44 42 0a 20 20 22 4f 4d 49 54 5f _TEMPDB. "OMIT_
4040: 54 45 4d 50 44 42 22 2c 0a 23 65 6e 64 69 66 0a TEMPDB",.#endif.
4050: 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f #if SQLITE_OMIT_
4060: 54 45 53 54 5f 43 4f 4e 54 52 4f 4c 0a 20 20 22 TEST_CONTROL. "
4070: 4f 4d 49 54 5f 54 45 53 54 5f 43 4f 4e 54 52 4f OMIT_TEST_CONTRO
4080: 4c 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 L",.#endif.#if S
4090: 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 41 43 45 QLITE_OMIT_TRACE
40a0: 0a 20 20 22 4f 4d 49 54 5f 54 52 41 43 45 22 2c . "OMIT_TRACE",
40b0: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
40c0: 54 45 5f 4f 4d 49 54 5f 54 52 49 47 47 45 52 0a TE_OMIT_TRIGGER.
40d0: 20 20 22 4f 4d 49 54 5f 54 52 49 47 47 45 52 22 "OMIT_TRIGGER"
40e0: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
40f0: 49 54 45 5f 4f 4d 49 54 5f 54 52 55 4e 43 41 54 ITE_OMIT_TRUNCAT
4100: 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 0a 20 E_OPTIMIZATION.
4110: 20 22 4f 4d 49 54 5f 54 52 55 4e 43 41 54 45 5f "OMIT_TRUNCATE_
4120: 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 22 2c 0a 23 OPTIMIZATION",.#
4130: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
4140: 5f 4f 4d 49 54 5f 55 54 46 31 36 0a 20 20 22 4f _OMIT_UTF16. "O
4150: 4d 49 54 5f 55 54 46 31 36 22 2c 0a 23 65 6e 64 MIT_UTF16",.#end
4160: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d if.#if SQLITE_OM
4170: 49 54 5f 56 41 43 55 55 4d 0a 20 20 22 4f 4d 49 IT_VACUUM. "OMI
4180: 54 5f 56 41 43 55 55 4d 22 2c 0a 23 65 6e 64 69 T_VACUUM",.#endi
4190: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 f.#if SQLITE_OMI
41a0: 54 5f 56 49 45 57 0a 20 20 22 4f 4d 49 54 5f 56 T_VIEW. "OMIT_V
41b0: 49 45 57 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 IEW",.#endif.#if
41c0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 56 49 52 SQLITE_OMIT_VIR
41d0: 54 55 41 4c 54 41 42 4c 45 0a 20 20 22 4f 4d 49 TUALTABLE. "OMI
41e0: 54 5f 56 49 52 54 55 41 4c 54 41 42 4c 45 22 2c T_VIRTUALTABLE",
41f0: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
4200: 54 45 5f 4f 4d 49 54 5f 57 41 4c 0a 20 20 22 4f TE_OMIT_WAL. "O
4210: 4d 49 54 5f 57 41 4c 22 2c 0a 23 65 6e 64 69 66 MIT_WAL",.#endif
4220: 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 .#if SQLITE_OMIT
4230: 5f 57 53 44 0a 20 20 22 4f 4d 49 54 5f 57 53 44 _WSD. "OMIT_WSD
4240: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
4250: 4c 49 54 45 5f 4f 4d 49 54 5f 58 46 45 52 5f 4f LITE_OMIT_XFER_O
4260: 50 54 0a 20 20 22 4f 4d 49 54 5f 58 46 45 52 5f PT. "OMIT_XFER_
4270: 4f 50 54 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 OPT",.#endif.#if
4280: 20 53 51 4c 49 54 45 5f 50 43 41 43 48 45 5f 53 SQLITE_PCACHE_S
4290: 45 50 41 52 41 54 45 5f 48 45 41 44 45 52 0a 20 EPARATE_HEADER.
42a0: 20 22 50 43 41 43 48 45 5f 53 45 50 41 52 41 54 "PCACHE_SEPARAT
42b0: 45 5f 48 45 41 44 45 52 22 2c 0a 23 65 6e 64 69 E_HEADER",.#endi
42c0: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 50 45 52 f.#if SQLITE_PER
42d0: 46 4f 52 4d 41 4e 43 45 5f 54 52 41 43 45 0a 20 FORMANCE_TRACE.
42e0: 20 22 50 45 52 46 4f 52 4d 41 4e 43 45 5f 54 52 "PERFORMANCE_TR
42f0: 41 43 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 ACE",.#endif.#if
4300: 20 53 51 4c 49 54 45 5f 50 4f 57 45 52 53 41 46 SQLITE_POWERSAF
4310: 45 5f 4f 56 45 52 57 52 49 54 45 0a 20 20 22 50 E_OVERWRITE. "P
4320: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
4330: 54 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 TE",.#endif.#if
4340: 53 51 4c 49 54 45 5f 50 52 45 46 45 52 5f 50 52 SQLITE_PREFER_PR
4350: 4f 58 59 5f 4c 4f 43 4b 49 4e 47 0a 20 20 22 50 OXY_LOCKING. "P
4360: 52 45 46 45 52 5f 50 52 4f 58 59 5f 4c 4f 43 4b REFER_PROXY_LOCK
4370: 49 4e 47 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 ING",.#endif.#if
4380: 20 53 51 4c 49 54 45 5f 50 52 4f 58 59 5f 44 45 SQLITE_PROXY_DE
4390: 42 55 47 0a 20 20 22 50 52 4f 58 59 5f 44 45 42 BUG. "PROXY_DEB
43a0: 55 47 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 UG",.#endif.#if
43b0: 53 51 4c 49 54 45 5f 52 45 56 45 52 53 45 5f 55 SQLITE_REVERSE_U
43c0: 4e 4f 52 44 45 52 45 44 5f 53 45 4c 45 43 54 53 NORDERED_SELECTS
43d0: 0a 20 20 22 52 45 56 45 52 53 45 5f 55 4e 4f 52 . "REVERSE_UNOR
43e0: 44 45 52 45 44 5f 53 45 4c 45 43 54 53 22 2c 0a DERED_SELECTS",.
43f0: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
4400: 45 5f 52 54 52 45 45 5f 49 4e 54 5f 4f 4e 4c 59 E_RTREE_INT_ONLY
4410: 0a 20 20 22 52 54 52 45 45 5f 49 4e 54 5f 4f 4e . "RTREE_INT_ON
4420: 4c 59 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 LY",.#endif.#if
4430: 53 51 4c 49 54 45 5f 53 45 43 55 52 45 5f 44 45 SQLITE_SECURE_DE
4440: 4c 45 54 45 0a 20 20 22 53 45 43 55 52 45 5f 44 LETE. "SECURE_D
4450: 45 4c 45 54 45 22 2c 0a 23 65 6e 64 69 66 0a 23 ELETE",.#endif.#
4460: 69 66 20 53 51 4c 49 54 45 5f 53 4d 41 4c 4c 5f if SQLITE_SMALL_
4470: 53 54 41 43 4b 0a 20 20 22 53 4d 41 4c 4c 5f 53 STACK. "SMALL_S
4480: 54 41 43 4b 22 2c 0a 23 65 6e 64 69 66 0a 23 69 TACK",.#endif.#i
4490: 66 64 65 66 20 53 51 4c 49 54 45 5f 53 4f 52 54 fdef SQLITE_SORT
44a0: 45 52 5f 50 4d 41 53 5a 0a 20 20 22 53 4f 52 54 ER_PMASZ. "SORT
44b0: 45 52 5f 50 4d 41 53 5a 3d 22 20 43 54 49 4d 45 ER_PMASZ=" CTIME
44c0: 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 53 OPT_VAL(SQLITE_S
44d0: 4f 52 54 45 52 5f 50 4d 41 53 5a 29 2c 0a 23 65 ORTER_PMASZ),.#e
44e0: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
44f0: 53 4f 55 4e 44 45 58 0a 20 20 22 53 4f 55 4e 44 SOUNDEX. "SOUND
4500: 45 58 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 EX",.#endif.#ifd
4510: 65 66 20 53 51 4c 49 54 45 5f 53 54 41 54 34 5f ef SQLITE_STAT4_
4520: 53 41 4d 50 4c 45 53 0a 20 20 22 53 54 41 54 34 SAMPLES. "STAT4
4530: 5f 53 41 4d 50 4c 45 53 3d 22 20 43 54 49 4d 45 _SAMPLES=" CTIME
4540: 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 53 OPT_VAL(SQLITE_S
4550: 54 41 54 34 5f 53 41 4d 50 4c 45 53 29 2c 0a 23 TAT4_SAMPLES),.#
4560: 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c endif.#ifdef SQL
4570: 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 ITE_STMTJRNL_SPI
4580: 4c 4c 0a 20 20 22 53 54 4d 54 4a 52 4e 4c 5f 53 LL. "STMTJRNL_S
4590: 50 49 4c 4c 3d 22 20 43 54 49 4d 45 4f 50 54 5f PILL=" CTIMEOPT_
45a0: 56 41 4c 28 53 51 4c 49 54 45 5f 53 54 4d 54 4a VAL(SQLITE_STMTJ
45b0: 52 4e 4c 5f 53 50 49 4c 4c 29 2c 0a 23 65 6e 64 RNL_SPILL),.#end
45c0: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 53 55 if.#if SQLITE_SU
45d0: 42 53 54 52 5f 43 4f 4d 50 41 54 49 42 49 4c 49 BSTR_COMPATIBILI
45e0: 54 59 0a 20 20 22 53 55 42 53 54 52 5f 43 4f 4d TY. "SUBSTR_COM
45f0: 50 41 54 49 42 49 4c 49 54 59 22 2c 0a 23 65 6e PATIBILITY",.#en
4600: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 53 dif.#if SQLITE_S
4610: 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 0a 20 20 22 YSTEM_MALLOC. "
4620: 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 22 2c 0a SYSTEM_MALLOC",.
4630: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
4640: 45 5f 54 43 4c 0a 20 20 22 54 43 4c 22 2c 0a 23 E_TCL. "TCL",.#
4650: 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c endif.#ifdef SQL
4660: 49 54 45 5f 54 45 4d 50 5f 53 54 4f 52 45 0a 20 ITE_TEMP_STORE.
4670: 20 22 54 45 4d 50 5f 53 54 4f 52 45 3d 22 20 43 "TEMP_STORE=" C
4680: 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 TIMEOPT_VAL(SQLI
4690: 54 45 5f 54 45 4d 50 5f 53 54 4f 52 45 29 2c 0a TE_TEMP_STORE),.
46a0: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
46b0: 45 5f 54 45 53 54 0a 20 20 22 54 45 53 54 22 2c E_TEST. "TEST",
46c0: 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69 .#endif.#if defi
46d0: 6e 65 64 28 53 51 4c 49 54 45 5f 54 48 52 45 41 ned(SQLITE_THREA
46e0: 44 53 41 46 45 29 0a 20 20 22 54 48 52 45 41 44 DSAFE). "THREAD
46f0: 53 41 46 45 3d 22 20 43 54 49 4d 45 4f 50 54 5f SAFE=" CTIMEOPT_
4700: 56 41 4c 28 53 51 4c 49 54 45 5f 54 48 52 45 41 VAL(SQLITE_THREA
4710: 44 53 41 46 45 29 2c 0a 23 65 6c 69 66 20 64 65 DSAFE),.#elif de
4720: 66 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45 fined(THREADSAFE
4730: 29 0a 20 20 22 54 48 52 45 41 44 53 41 46 45 3d ). "THREADSAFE=
4740: 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 54 " CTIMEOPT_VAL(T
4750: 48 52 45 41 44 53 41 46 45 29 2c 0a 23 65 6c 73 HREADSAFE),.#els
4760: 65 0a 20 20 22 54 48 52 45 41 44 53 41 46 45 3d e. "THREADSAFE=
4770: 31 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 1",.#endif.#if S
4780: 51 4c 49 54 45 5f 55 4e 4c 49 4e 4b 5f 41 46 54 QLITE_UNLINK_AFT
4790: 45 52 5f 43 4c 4f 53 45 0a 20 20 22 55 4e 4c 49 ER_CLOSE. "UNLI
47a0: 4e 4b 5f 41 46 54 45 52 5f 43 4c 4f 53 45 22 2c NK_AFTER_CLOSE",
47b0: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
47c0: 54 45 5f 55 4e 54 45 53 54 41 42 4c 45 0a 20 20 TE_UNTESTABLE.
47d0: 22 55 4e 54 45 53 54 41 42 4c 45 22 2c 0a 23 65 "UNTESTABLE",.#e
47e0: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
47f0: 55 53 45 52 5f 41 55 54 48 45 4e 54 49 43 41 54 USER_AUTHENTICAT
4800: 49 4f 4e 0a 20 20 22 55 53 45 52 5f 41 55 54 48 ION. "USER_AUTH
4810: 45 4e 54 49 43 41 54 49 4f 4e 22 2c 0a 23 65 6e ENTICATION",.#en
4820: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 55 dif.#if SQLITE_U
4830: 53 45 5f 41 4c 4c 4f 43 41 0a 20 20 22 55 53 45 SE_ALLOCA. "USE
4840: 5f 41 4c 4c 4f 43 41 22 2c 0a 23 65 6e 64 69 66 _ALLOCA",.#endif
4850: 0a 23 69 66 20 53 51 4c 49 54 45 5f 55 53 45 5f .#if SQLITE_USE_
4860: 46 43 4e 54 4c 5f 54 52 41 43 45 0a 20 20 22 55 FCNTL_TRACE. "U
4870: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 22 2c SE_FCNTL_TRACE",
4880: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
4890: 54 45 5f 55 53 45 5f 55 52 49 0a 20 20 22 55 53 TE_USE_URI. "US
48a0: 45 5f 55 52 49 22 2c 0a 23 65 6e 64 69 66 0a 23 E_URI",.#endif.#
48b0: 69 66 20 53 51 4c 49 54 45 5f 56 44 42 45 5f 43 if SQLITE_VDBE_C
48c0: 4f 56 45 52 41 47 45 0a 20 20 22 56 44 42 45 5f OVERAGE. "VDBE_
48d0: 43 4f 56 45 52 41 47 45 22 2c 0a 23 65 6e 64 69 COVERAGE",.#endi
48e0: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 57 49 4e f.#if SQLITE_WIN
48f0: 33 32 5f 4d 41 4c 4c 4f 43 0a 20 20 22 57 49 4e 32_MALLOC. "WIN
4900: 33 32 5f 4d 41 4c 4c 4f 43 22 2c 0a 23 65 6e 64 32_MALLOC",.#end
4910: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 5a 45 if.#if SQLITE_ZE
4920: 52 4f 5f 4d 41 4c 4c 4f 43 0a 20 20 22 5a 45 52 RO_MALLOC. "ZER
4930: 4f 5f 4d 41 4c 4c 4f 43 22 2c 0a 23 65 6e 64 69 O_MALLOC",.#endi
4940: 66 0a 2f 2a 20 0a 2a 2a 20 45 4e 44 20 43 4f 44 f./* .** END COD
4950: 45 20 47 45 4e 45 52 41 54 45 44 20 42 59 20 74 E GENERATED BY t
4960: 6f 6f 6c 2f 6d 6b 63 74 69 6d 65 2e 74 63 6c 20 ool/mkctime.tcl
4970: 0a 2a 2f 0a 7d 3b 0a 0a 53 51 4c 49 54 45 5f 50 .*/.};..SQLITE_P
4980: 52 49 56 41 54 45 20 63 6f 6e 73 74 20 63 68 61 RIVATE const cha
4990: 72 20 2a 2a 73 71 6c 69 74 65 33 43 6f 6d 70 69 r **sqlite3Compi
49a0: 6c 65 4f 70 74 69 6f 6e 73 28 69 6e 74 20 2a 70 leOptions(int *p
49b0: 6e 4f 70 74 29 7b 0a 20 20 2a 70 6e 4f 70 74 20 nOpt){. *pnOpt
49c0: 3d 20 73 69 7a 65 6f 66 28 73 71 6c 69 74 65 33 = sizeof(sqlite3
49d0: 61 7a 43 6f 6d 70 69 6c 65 4f 70 74 29 20 2f 20 azCompileOpt) /
49e0: 73 69 7a 65 6f 66 28 73 71 6c 69 74 65 33 61 7a sizeof(sqlite3az
49f0: 43 6f 6d 70 69 6c 65 4f 70 74 5b 30 5d 29 3b 0a CompileOpt[0]);.
4a00: 20 20 72 65 74 75 72 6e 20 28 63 6f 6e 73 74 20 return (const
4a10: 63 68 61 72 2a 2a 29 73 71 6c 69 74 65 33 61 7a char**)sqlite3az
4a20: 43 6f 6d 70 69 6c 65 4f 70 74 3b 0a 7d 0a 0a 23 CompileOpt;.}..#
4a30: 65 6e 64 69 66 20 2f 2a 20 53 51 4c 49 54 45 5f endif /* SQLITE_
4a40: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 OMIT_COMPILEOPTI
4a50: 4f 4e 5f 44 49 41 47 53 20 2a 2f 0a 0a 2f 2a 2a ON_DIAGS */../**
4a60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 ************ End
4a70: 20 6f 66 20 63 74 69 6d 65 2e 63 20 2a 2a 2a 2a of ctime.c ****
4a80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4a90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4aa0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a ***********/./**
4ab0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 ************ Beg
4ac0: 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49 6e in file sqliteIn
4ad0: 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a t.h ************
4ae0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4af0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a ***********/./*.
4b00: 2a 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 ** 2001 Septembe
4b10: 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 r 15.**.** The a
4b20: 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 uthor disclaims
4b30: 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 copyright to thi
4b40: 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 s source code.
4b50: 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 In place of.** a
4b60: 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 legal notice, h
4b70: 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e ere is a blessin
4b80: 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 g:.**.** May
4b90: 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 you do good and
4ba0: 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 not evil..**
4bb0: 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 May you find for
4bc0: 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 giveness for you
4bd0: 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 rself and forgiv
4be0: 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 e others..**
4bf0: 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 May you share fr
4c00: 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 eely, never taki
4c10: 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 ng more than you
4c20: 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a give..**.******
4c30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4c40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4c50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4c60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4c70: 2a 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 ***.** Internal
4c80: 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 69 interface defini
4c90: 74 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 tions for SQLite
4ca0: 2e 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 ..**.*/.#ifndef
4cb0: 53 51 4c 49 54 45 49 4e 54 5f 48 0a 23 64 65 66 SQLITEINT_H.#def
4cc0: 69 6e 65 20 53 51 4c 49 54 45 49 4e 54 5f 48 0a ine SQLITEINT_H.
4cd0: 0a 2f 2a 20 53 70 65 63 69 61 6c 20 43 6f 6d 6d ./* Special Comm
4ce0: 65 6e 74 73 3a 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 ents:.**.** Some
4cf0: 20 63 6f 6d 6d 65 6e 74 73 20 68 61 76 65 20 73 comments have s
4d00: 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 pecial meaning t
4d10: 6f 20 74 68 65 20 74 6f 6f 6c 73 20 74 68 61 74 o the tools that
4d20: 20 6d 65 61 73 75 72 65 20 74 65 73 74 0a 2a 2a measure test.**
4d30: 20 63 6f 76 65 72 61 67 65 3a 0a 2a 2a 0a 2a 2a coverage:.**.**
4d40: 20 20 20 20 4e 4f 5f 54 45 53 54 20 20 20 20 20 NO_TEST
4d50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4d60: 2d 20 54 68 65 20 62 72 61 6e 63 68 65 73 20 6f - The branches o
4d70: 6e 20 74 68 69 73 20 6c 69 6e 65 20 61 72 65 20 n this line are
4d80: 6e 6f 74 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 not.**
4d90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4da0: 20 20 20 20 20 20 20 20 6d 65 61 73 75 72 65 64 measured
4db0: 20 62 79 20 62 72 61 6e 63 68 20 63 6f 76 65 72 by branch cover
4dc0: 61 67 65 2e 20 20 54 68 69 73 20 69 73 0a 2a 2a age. This is.**
4dd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4de0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4df0: 20 20 75 73 65 64 20 6f 6e 20 6c 69 6e 65 73 20 used on lines
4e00: 6f 66 20 63 6f 64 65 20 74 68 61 74 20 61 63 74 of code that act
4e10: 75 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 ually.**
4e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4e30: 20 20 20 20 20 20 20 20 20 20 69 6d 70 6c 65 6d implem
4e40: 65 6e 74 20 70 61 72 74 73 20 6f 66 20 63 6f 76 ent parts of cov
4e50: 65 72 61 67 65 20 74 65 73 74 69 6e 67 2e 0a 2a erage testing..*
4e60: 2a 0a 2a 2a 20 20 20 20 4f 50 54 49 4d 49 5a 41 *.** OPTIMIZA
4e70: 54 49 4f 4e 2d 49 46 2d 54 52 55 45 20 20 20 20 TION-IF-TRUE
4e80: 20 20 20 20 2d 20 54 68 69 73 20 62 72 61 6e 63 - This branc
4e90: 68 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 h is allowed to
4ea0: 61 6c 77 61 79 20 62 65 20 66 61 6c 73 65 0a 2a alway be false.*
4eb0: 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 *
4ec0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4ed0: 20 20 20 61 6e 64 20 74 68 65 20 63 6f 72 72 65 and the corre
4ee0: 63 74 20 61 6e 73 77 65 72 20 69 73 20 73 74 69 ct answer is sti
4ef0: 6c 6c 20 6f 62 74 61 69 6e 65 64 2c 0a 2a 2a 20 ll obtained,.**
4f00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4f10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4f20: 20 74 68 6f 75 67 68 20 70 65 72 68 61 70 73 20 though perhaps
4f30: 6d 6f 72 65 20 73 6c 6f 77 6c 79 2e 0a 2a 2a 0a more slowly..**.
4f40: 2a 2a 20 20 20 20 4f 50 54 49 4d 49 5a 41 54 49 ** OPTIMIZATI
4f50: 4f 4e 2d 49 46 2d 46 41 4c 53 45 20 20 20 20 20 ON-IF-FALSE
4f60: 20 20 2d 20 54 68 69 73 20 62 72 61 6e 63 68 20 - This branch
4f70: 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 61 6c is allowed to al
4f80: 77 61 79 20 62 65 20 74 72 75 65 0a 2a 2a 20 20 way be true.**
4f90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4fa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4fb0: 61 6e 64 20 74 68 65 20 63 6f 72 72 65 63 74 20 and the correct
4fc0: 61 6e 73 77 65 72 20 69 73 20 73 74 69 6c 6c 20 answer is still
4fd0: 6f 62 74 61 69 6e 65 64 2c 0a 2a 2a 20 20 20 20 obtained,.**
4fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4ff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 74 68 th
5000: 6f 75 67 68 20 70 65 72 68 61 70 73 20 6d 6f 72 ough perhaps mor
5010: 65 20 73 6c 6f 77 6c 79 2e 0a 2a 2a 0a 2a 2a 20 e slowly..**.**
5020: 20 20 20 50 52 45 56 45 4e 54 53 2d 48 41 52 4d PREVENTS-HARM
5030: 4c 45 53 53 2d 4f 56 45 52 52 45 41 44 20 20 2d LESS-OVERREAD -
5040: 20 54 68 69 73 20 62 72 61 6e 63 68 20 70 72 65 This branch pre
5050: 76 65 6e 74 73 20 61 20 62 75 66 66 65 72 20 6f vents a buffer o
5060: 76 65 72 72 65 61 64 0a 2a 2a 20 20 20 20 20 20 verread.**
5070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
5080: 20 20 20 20 20 20 20 20 20 20 20 20 74 68 61 74 that
5090: 20 77 6f 75 6c 64 20 62 65 20 68 61 72 6d 6c 65 would be harmle
50a0: 73 73 20 61 6e 64 20 75 6e 64 65 74 65 63 74 61 ss and undetecta
50b0: 62 6c 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ble.**
50c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
50d0: 20 20 20 20 20 20 20 20 69 66 20 69 74 20 64 69 if it di
50e0: 64 20 6f 63 63 75 72 2e 20 20 0a 2a 2a 0a 2a 2a d occur. .**.**
50f0: 20 49 6e 20 61 6c 6c 20 63 61 73 65 73 2c 20 74 In all cases, t
5100: 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6d 6d 65 he special comme
5110: 6e 74 20 6d 75 73 74 20 62 65 20 65 6e 63 6c 6f nt must be enclo
5120: 73 65 64 20 69 6e 20 74 68 65 20 75 73 75 61 6c sed in the usual
5130: 0a 2a 2a 20 73 6c 61 73 68 2d 61 73 74 65 72 69 .** slash-asteri
5140: 73 6b 2e 2e 2e 61 73 74 65 72 69 73 6b 2d 73 6c sk...asterisk-sl
5150: 61 73 68 20 63 6f 6d 6d 65 6e 74 20 6d 61 72 6b ash comment mark
5160: 73 2c 20 77 69 74 68 20 6e 6f 20 73 70 61 63 65 s, with no space
5170: 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 0a 2a s between the .*
5180: 2a 20 61 73 74 65 72 69 73 6b 73 20 61 6e 64 20 * asterisks and
5190: 74 68 65 20 63 6f 6d 6d 65 6e 74 20 74 65 78 74 the comment text
51a0: 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 ..*/../*.** Make
51b0: 20 73 75 72 65 20 74 68 65 20 54 63 6c 20 63 61 sure the Tcl ca
51c0: 6c 6c 69 6e 67 20 63 6f 6e 76 65 6e 74 69 6f 6e lling convention
51d0: 20 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e 65 macro is define
51e0: 64 2e 20 20 54 68 69 73 20 6d 61 63 72 6f 20 69 d. This macro i
51f0: 73 0a 2a 2a 20 6f 6e 6c 79 20 75 73 65 64 20 62 s.** only used b
5200: 79 20 74 65 73 74 20 63 6f 64 65 20 61 6e 64 20 y test code and
5210: 54 63 6c 20 69 6e 74 65 67 72 61 74 69 6f 6e 20 Tcl integration
5220: 63 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 code..*/.#ifndef
5230: 20 53 51 4c 49 54 45 5f 54 43 4c 41 50 49 0a 23 SQLITE_TCLAPI.#
5240: 20 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f define SQLITE_
5250: 54 43 4c 41 50 49 0a 23 65 6e 64 69 66 0a 0a 2f TCLAPI.#endif../
5260: 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 65 *.** Include the
5270: 20 68 65 61 64 65 72 20 66 69 6c 65 20 75 73 65 header file use
5280: 64 20 74 6f 20 63 75 73 74 6f 6d 69 7a 65 20 74 d to customize t
5290: 68 65 20 63 6f 6d 70 69 6c 65 72 20 6f 70 74 69 he compiler opti
52a0: 6f 6e 73 20 66 6f 72 20 4d 53 56 43 2e 0a 2a 2a ons for MSVC..**
52b0: 20 54 68 69 73 20 73 68 6f 75 6c 64 20 62 65 20 This should be
52c0: 64 6f 6e 65 20 66 69 72 73 74 20 73 6f 20 74 68 done first so th
52d0: 61 74 20 69 74 20 63 61 6e 20 73 75 63 63 65 73 at it can succes
52e0: 73 66 75 6c 6c 79 20 70 72 65 76 65 6e 74 20 73 sfully prevent s
52f0: 70 75 72 69 6f 75 73 0a 2a 2a 20 63 6f 6d 70 69 purious.** compi
5300: 6c 65 72 20 77 61 72 6e 69 6e 67 73 20 64 75 65 ler warnings due
5310: 20 74 6f 20 73 75 62 73 65 71 75 65 6e 74 20 63 to subsequent c
5320: 6f 6e 74 65 6e 74 20 69 6e 20 74 68 69 73 20 66 ontent in this f
5330: 69 6c 65 20 61 6e 64 20 6f 74 68 65 72 20 66 69 ile and other fi
5340: 6c 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 les.** that are
5350: 69 6e 63 6c 75 64 65 64 20 62 79 20 74 68 69 73 included by this
5360: 20 66 69 6c 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a file..*/./*****
5370: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 ********* Includ
5380: 65 20 6d 73 76 63 2e 68 20 69 6e 20 74 68 65 20 e msvc.h in the
5390: 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 middle of sqlite
53a0: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a Int.h **********
53b0: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a ********/./*****
53c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 ********* Begin
53d0: 66 69 6c 65 20 6d 73 76 63 2e 68 20 2a 2a 2a 2a file msvc.h ****
53e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
53f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5400: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 ********/./*.**
5410: 32 30 31 35 20 4a 61 6e 75 61 72 79 20 31 32 0a 2015 January 12.
5420: 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 **.** The author
5430: 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 72 disclaims copyr
5440: 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f 75 ight to this sou
5450: 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c rce code. In pl
5460: 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 ace of.** a lega
5470: 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 69 l notice, here i
5480: 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a s a blessing:.**
5490: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 64 .** May you d
54a0: 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65 o good and not e
54b0: 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 vil..** May y
54c0: 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65 6e ou find forgiven
54d0: 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c 66 ess for yourself
54e0: 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 68 and forgive oth
54f0: 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 ers..** May y
5500: 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79 2c ou share freely,
5510: 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f never taking mo
5520: 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76 65 re than you give
5530: 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ..**.***********
5540: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5560: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5570: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5580: 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 ***.**.** This f
5590: 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 63 6f 64 ile contains cod
55a0: 65 20 74 68 61 74 20 69 73 20 73 70 65 63 69 66 e that is specif
55b0: 69 63 20 74 6f 20 4d 53 56 43 2e 0a 2a 2f 0a 23 ic to MSVC..*/.#
55c0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 53 ifndef SQLITE_MS
55d0: 56 43 5f 48 0a 23 64 65 66 69 6e 65 20 53 51 4c VC_H.#define SQL
55e0: 49 54 45 5f 4d 53 56 43 5f 48 0a 0a 23 69 66 20 ITE_MSVC_H..#if
55f0: 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 defined(_MSC_VER
5600: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
5610: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 30 35 34 g(disable : 4054
5620: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
5630: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 30 35 35 g(disable : 4055
5640: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
5650: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 30 30 g(disable : 4100
5660: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
5670: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 32 37 g(disable : 4127
5680: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
5690: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 33 30 g(disable : 4130
56a0: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
56b0: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 35 32 g(disable : 4152
56c0: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
56d0: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 38 39 g(disable : 4189
56e0: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
56f0: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 30 36 g(disable : 4206
5700: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
5710: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 31 30 g(disable : 4210
5720: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
5730: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 33 32 g(disable : 4232
5740: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
5750: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 34 34 g(disable : 4244
5760: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
5770: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 33 30 35 g(disable : 4305
5780: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
5790: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 33 30 36 g(disable : 4306
57a0: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
57b0: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 37 30 32 g(disable : 4702
57c0: 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69 6e ).#pragma warnin
57d0: 67 28 64 69 73 61 62 6c 65 20 3a 20 34 37 30 36 g(disable : 4706
57e0: 29 0a 23 65 6e 64 69 66 20 2f 2a 20 64 65 66 69 ).#endif /* defi
57f0: 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 2a 2f ned(_MSC_VER) */
5800: 0a 0a 23 65 6e 64 69 66 20 2f 2a 20 53 51 4c 49 ..#endif /* SQLI
5810: 54 45 5f 4d 53 56 43 5f 48 20 2a 2f 0a 0a 2f 2a TE_MSVC_H */../*
5820: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e ************* En
5830: 64 20 6f 66 20 6d 73 76 63 2e 68 20 2a 2a 2a 2a d of msvc.h ****
5840: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5850: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5860: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a ************/./*
5870: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f ************* Co
5880: 6e 74 69 6e 75 69 6e 67 20 77 68 65 72 65 20 77 ntinuing where w
5890: 65 20 6c 65 66 74 20 6f 66 66 20 69 6e 20 73 71 e left off in sq
58a0: 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a liteInt.h ******
58b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f ************/../
58c0: 2a 0a 2a 2a 20 53 70 65 63 69 61 6c 20 73 65 74 *.** Special set
58d0: 75 70 20 66 6f 72 20 56 78 57 6f 72 6b 73 0a 2a up for VxWorks.*
58e0: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /./*************
58f0: 2a 20 49 6e 63 6c 75 64 65 20 76 78 77 6f 72 6b * Include vxwork
5900: 73 2e 68 20 69 6e 20 74 68 65 20 6d 69 64 64 6c s.h in the middl
5910: 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e 68 e of sqliteInt.h
5920: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ***************
5930: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /./*************
5940: 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 76 78 77 * Begin file vxw
5950: 6f 72 6b 73 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a orks.h *********
5960: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5970: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5980: 2f 0a 2f 2a 0a 2a 2a 20 32 30 31 35 2d 30 33 2d /./*.** 2015-03-
5990: 30 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 02.**.** The aut
59a0: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f hor disclaims co
59b0: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 pyright to this
59c0: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e source code. In
59d0: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c place of.** a l
59e0: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 egal notice, her
59f0: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a e is a blessing:
5a00: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f .**.** May yo
5a10: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f u do good and no
5a20: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 t evil..** Ma
5a30: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 y you find forgi
5a40: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 veness for yours
5a50: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 elf and forgive
5a60: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 others..** Ma
5a70: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 y you share free
5a80: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 ly, never taking
5a90: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 more than you g
5aa0: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a ive..**.********
5ab0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5ac0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5ad0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5ae0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5af0: 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 69 ******.**.** Thi
5b00: 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 s file contains
5b10: 63 6f 64 65 20 74 68 61 74 20 69 73 20 73 70 65 code that is spe
5b20: 63 69 66 69 63 20 74 6f 20 57 69 6e 64 20 52 69 cific to Wind Ri
5b30: 76 65 72 27 73 20 56 78 57 6f 72 6b 73 0a 2a 2f ver's VxWorks.*/
5b40: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 52 .#if defined(__R
5b50: 54 50 5f 5f 29 20 7c 7c 20 64 65 66 69 6e 65 64 TP__) || defined
5b60: 28 5f 57 52 53 5f 4b 45 52 4e 45 4c 29 0a 2f 2a (_WRS_KERNEL)./*
5b70: 20 54 68 69 73 20 69 73 20 56 78 57 6f 72 6b 73 This is VxWorks
5b80: 2e 20 20 53 65 74 20 75 70 20 74 68 69 6e 67 73 . Set up things
5b90: 20 73 70 65 63 69 61 6c 6c 79 20 66 6f 72 20 74 specially for t
5ba0: 68 61 74 20 4f 53 0a 2a 2f 0a 23 69 6e 63 6c 75 hat OS.*/.#inclu
5bb0: 64 65 20 3c 76 78 57 6f 72 6b 73 2e 68 3e 0a 23 de <vxWorks.h>.#
5bc0: 69 6e 63 6c 75 64 65 20 3c 70 74 68 72 65 61 64 include <pthread
5bd0: 2e 68 3e 20 20 2f 2a 20 61 6d 61 6c 67 61 6d 61 .h> /* amalgama
5be0: 74 6f 72 3a 20 64 6f 6e 74 63 61 63 68 65 20 2a tor: dontcache *
5bf0: 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58 57 /.#define OS_VXW
5c00: 4f 52 4b 53 20 31 0a 23 64 65 66 69 6e 65 20 53 ORKS 1.#define S
5c10: 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 20 30 QLITE_OS_OTHER 0
5c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5c30: 48 4f 4d 45 47 52 4f 57 4e 5f 52 45 43 55 52 53 HOMEGROWN_RECURS
5c40: 49 56 45 5f 4d 55 54 45 58 20 31 0a 23 64 65 66 IVE_MUTEX 1.#def
5c50: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f ine SQLITE_OMIT_
5c60: 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 LOAD_EXTENSION 1
5c70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
5c80: 45 4e 41 42 4c 45 5f 4c 4f 43 4b 49 4e 47 5f 53 ENABLE_LOCKING_S
5c90: 54 59 4c 45 20 30 0a 23 64 65 66 69 6e 65 20 48 TYLE 0.#define H
5ca0: 41 56 45 5f 55 54 49 4d 45 20 31 0a 23 65 6c 73 AVE_UTIME 1.#els
5cb0: 65 0a 2f 2a 20 54 68 69 73 20 69 73 20 6e 6f 74 e./* This is not
5cc0: 20 56 78 57 6f 72 6b 73 2e 20 2a 2f 0a 23 64 65 VxWorks. */.#de
5cd0: 66 69 6e 65 20 4f 53 5f 56 58 57 4f 52 4b 53 20 fine OS_VXWORKS
5ce0: 30 0a 23 64 65 66 69 6e 65 20 48 41 56 45 5f 46 0.#define HAVE_F
5cf0: 43 48 4f 57 4e 20 31 0a 23 64 65 66 69 6e 65 20 CHOWN 1.#define
5d00: 48 41 56 45 5f 52 45 41 44 4c 49 4e 4b 20 31 0a HAVE_READLINK 1.
5d10: 23 64 65 66 69 6e 65 20 48 41 56 45 5f 4c 53 54 #define HAVE_LST
5d20: 41 54 20 31 0a 23 65 6e 64 69 66 20 2f 2a 20 64 AT 1.#endif /* d
5d30: 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52 4e efined(_WRS_KERN
5d40: 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a EL) */../*******
5d50: 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f 66 20 76 ******* End of v
5d60: 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a 2a 2a 2a xworks.h *******
5d70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5d80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5d90: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a ******/./*******
5da0: 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69 6e 75 69 ******* Continui
5db0: 6e 67 20 77 68 65 72 65 20 77 65 20 6c 65 66 74 ng where we left
5dc0: 20 6f 66 66 20 69 6e 20 73 71 6c 69 74 65 49 6e off in sqliteIn
5dd0: 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a t.h ************
5de0: 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 54 ******/../*.** T
5df0: 68 65 73 65 20 23 64 65 66 69 6e 65 73 20 73 68 hese #defines sh
5e00: 6f 75 6c 64 20 65 6e 61 62 6c 65 20 3e 32 47 42 ould enable >2GB
5e10: 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20 6f 6e file support on
5e20: 20 50 4f 53 49 58 20 69 66 20 74 68 65 0a 2a 2a POSIX if the.**
5e30: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 underlying oper
5e40: 61 74 69 6e 67 20 73 79 73 74 65 6d 20 73 75 70 ating system sup
5e50: 70 6f 72 74 73 20 69 74 2e 20 20 49 66 20 74 68 ports it. If th
5e60: 65 20 4f 53 20 6c 61 63 6b 73 0a 2a 2a 20 6c 61 e OS lacks.** la
5e70: 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74 rge file support
5e80: 2c 20 6f 72 20 69 66 20 74 68 65 20 4f 53 20 69 , or if the OS i
5e90: 73 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 73 65 s windows, these
5ea0: 20 73 68 6f 75 6c 64 20 62 65 20 6e 6f 2d 6f 70 should be no-op
5eb0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 63 6b 65 74 20 s..**.** Ticket
5ec0: 23 32 37 33 39 3a 20 20 54 68 65 20 5f 4c 41 52 #2739: The _LAR
5ed0: 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20 6d 61 GEFILE_SOURCE ma
5ee0: 63 72 6f 20 6d 75 73 74 20 61 70 70 65 61 72 20 cro must appear
5ef0: 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20 73 79 before any.** sy
5f00: 73 74 65 6d 20 23 69 6e 63 6c 75 64 65 73 2e 20 stem #includes.
5f10: 20 48 65 6e 63 65 2c 20 74 68 69 73 20 62 6c 6f Hence, this blo
5f20: 63 6b 20 6f 66 20 63 6f 64 65 20 6d 75 73 74 20 ck of code must
5f30: 62 65 20 74 68 65 20 76 65 72 79 20 66 69 72 73 be the very firs
5f40: 74 0a 2a 2a 20 63 6f 64 65 20 69 6e 20 61 6c 6c t.** code in all
5f50: 20 73 6f 75 72 63 65 20 66 69 6c 65 73 2e 0a 2a source files..*
5f60: 2a 0a 2a 2a 20 4c 61 72 67 65 20 66 69 6c 65 20 *.** Large file
5f70: 73 75 70 70 6f 72 74 20 63 61 6e 20 62 65 20 64 support can be d
5f80: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 74 68 isabled using th
5f90: 65 20 2d 44 53 51 4c 49 54 45 5f 44 49 53 41 42 e -DSQLITE_DISAB
5fa0: 4c 45 5f 4c 46 53 20 73 77 69 74 63 68 0a 2a 2a LE_LFS switch.**
5fb0: 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 on the compiler
5fc0: 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65 2e 20 20 command line.
5fd0: 54 68 69 73 20 69 73 20 6e 65 63 65 73 73 61 72 This is necessar
5fe0: 79 20 69 66 20 79 6f 75 20 61 72 65 20 63 6f 6d y if you are com
5ff0: 70 69 6c 69 6e 67 0a 2a 2a 20 6f 6e 20 61 20 72 piling.** on a r
6000: 65 63 65 6e 74 20 6d 61 63 68 69 6e 65 20 28 65 ecent machine (e
6010: 78 3a 20 52 65 64 20 48 61 74 20 37 2e 32 29 20 x: Red Hat 7.2)
6020: 62 75 74 20 79 6f 75 20 77 61 6e 74 20 79 6f 75 but you want you
6030: 72 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a r code to work.*
6040: 2a 20 6f 6e 20 61 6e 20 6f 6c 64 65 72 20 6d 61 * on an older ma
6050: 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20 48 chine (ex: Red H
6060: 61 74 20 36 2e 30 29 2e 20 20 49 66 20 79 6f 75 at 6.0). If you
6070: 20 63 6f 6d 70 69 6c 65 20 6f 6e 20 52 65 64 20 compile on Red
6080: 48 61 74 20 37 2e 32 0a 2a 2a 20 77 69 74 68 6f Hat 7.2.** witho
6090: 75 74 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 ut this option,
60a0: 4c 46 53 20 69 73 20 65 6e 61 62 6c 65 2e 20 20 LFS is enable.
60b0: 42 75 74 20 4c 46 53 20 64 6f 65 73 20 6e 6f 74 But LFS does not
60c0: 20 65 78 69 73 74 20 69 6e 20 74 68 65 20 6b 65 exist in the ke
60d0: 72 6e 65 6c 0a 2a 2a 20 69 6e 20 52 65 64 20 48 rnel.** in Red H
60e0: 61 74 20 36 2e 30 2c 20 73 6f 20 74 68 65 20 63 at 6.0, so the c
60f0: 6f 64 65 20 77 6f 6e 27 74 20 77 6f 72 6b 2e 20 ode won't work.
6100: 20 48 65 6e 63 65 2c 20 66 6f 72 20 6d 61 78 69 Hence, for maxi
6110: 6d 75 6d 20 62 69 6e 61 72 79 0a 2a 2a 20 70 6f mum binary.** po
6120: 72 74 61 62 69 6c 69 74 79 20 79 6f 75 20 73 68 rtability you sh
6130: 6f 75 6c 64 20 6f 6d 69 74 20 4c 46 53 2e 0a 2a ould omit LFS..*
6140: 2a 0a 2a 2a 20 54 68 65 20 70 72 65 76 69 6f 75 *.** The previou
6150: 73 20 70 61 72 61 67 72 61 70 68 20 77 61 73 20 s paragraph was
6160: 77 72 69 74 74 65 6e 20 69 6e 20 32 30 30 35 2e written in 2005.
6170: 20 20 28 54 68 69 73 20 70 61 72 61 67 72 61 70 (This paragrap
6180: 68 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 h is written.**
6190: 6f 6e 20 32 30 30 38 2d 31 31 2d 32 38 2e 29 20 on 2008-11-28.)
61a0: 54 68 65 73 65 20 64 61 79 73 2c 20 61 6c 6c 20 These days, all
61b0: 4c 69 6e 75 78 20 6b 65 72 6e 65 6c 73 20 73 75 Linux kernels su
61c0: 70 70 6f 72 74 20 6c 61 72 67 65 20 66 69 6c 65 pport large file
61d0: 73 2c 20 73 6f 0a 2a 2a 20 79 6f 75 20 73 68 6f s, so.** you sho
61e0: 75 6c 64 20 70 72 6f 62 61 62 6c 79 20 6c 65 61 uld probably lea
61f0: 76 65 20 4c 46 53 20 65 6e 61 62 6c 65 64 2e 20 ve LFS enabled.
6200: 20 42 75 74 20 73 6f 6d 65 20 65 6d 62 65 64 64 But some embedd
6210: 65 64 20 70 6c 61 74 66 6f 72 6d 73 20 6d 69 67 ed platforms mig
6220: 68 74 0a 2a 2a 20 6c 61 63 6b 20 4c 46 53 20 69 ht.** lack LFS i
6230: 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 n which case the
6240: 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f SQLITE_DISABLE_
6250: 4c 46 53 20 6d 61 63 72 6f 20 6d 69 67 68 74 20 LFS macro might
6260: 73 74 69 6c 6c 20 62 65 20 75 73 65 66 75 6c 2e still be useful.
6270: 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 6c 61 72 20 69 .**.** Similar i
6280: 73 20 74 72 75 65 20 66 6f 72 20 4d 61 63 20 4f s true for Mac O
6290: 53 20 58 2e 20 20 4c 46 53 20 69 73 20 6f 6e 6c S X. LFS is onl
62a0: 79 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 4d y supported on M
62b0: 61 63 20 4f 53 20 58 20 39 20 61 6e 64 20 6c 61 ac OS X 9 and la
62c0: 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 ter..*/.#ifndef
62d0: 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c SQLITE_DISABLE_L
62e0: 46 53 0a 23 20 64 65 66 69 6e 65 20 5f 4c 41 52 FS.# define _LAR
62f0: 47 45 5f 46 49 4c 45 20 20 20 20 20 20 20 31 0a GE_FILE 1.
6300: 23 20 69 66 6e 64 65 66 20 5f 46 49 4c 45 5f 4f # ifndef _FILE_O
6310: 46 46 53 45 54 5f 42 49 54 53 0a 23 20 20 20 64 FFSET_BITS.# d
6320: 65 66 69 6e 65 20 5f 46 49 4c 45 5f 4f 46 46 53 efine _FILE_OFFS
6330: 45 54 5f 42 49 54 53 20 36 34 0a 23 20 65 6e 64 ET_BITS 64.# end
6340: 69 66 0a 23 20 64 65 66 69 6e 65 20 5f 4c 41 52 if.# define _LAR
6350: 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20 31 0a GEFILE_SOURCE 1.
6360: 23 65 6e 64 69 66 0a 0a 2f 2a 20 54 68 65 20 47 #endif../* The G
6370: 43 43 5f 56 45 52 53 49 4f 4e 20 61 6e 64 20 4d CC_VERSION and M
6380: 53 56 43 5f 56 45 52 53 49 4f 4e 20 6d 61 63 72 SVC_VERSION macr
6390: 6f 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a os are used to.*
63a0: 2a 20 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79 20 * conditionally
63b0: 69 6e 63 6c 75 64 65 20 6f 70 74 69 6d 69 7a 61 include optimiza
63c0: 74 69 6f 6e 73 20 66 6f 72 20 65 61 63 68 20 6f tions for each o
63d0: 66 20 74 68 65 73 65 20 63 6f 6d 70 69 6c 65 72 f these compiler
63e0: 73 2e 20 20 41 0a 2a 2a 20 76 61 6c 75 65 20 6f s. A.** value o
63f0: 66 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20 63 f 0 means that c
6400: 6f 6d 70 69 6c 65 72 20 69 73 20 6e 6f 74 20 62 ompiler is not b
6410: 65 69 6e 67 20 75 73 65 64 2e 20 20 54 68 65 0a eing used. The.
6420: 2a 2a 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c ** SQLITE_DISABL
6430: 45 5f 49 4e 54 52 49 4e 53 49 43 20 6d 61 63 72 E_INTRINSIC macr
6440: 6f 20 6d 65 61 6e 73 20 64 6f 20 6e 6f 74 20 75 o means do not u
6450: 73 65 20 61 6e 79 20 63 6f 6d 70 69 6c 65 72 2d se any compiler-
6460: 73 70 65 63 69 66 69 63 0a 2a 2a 20 6f 70 74 69 specific.** opti
6470: 6d 69 7a 61 74 69 6f 6e 73 2c 20 61 6e 64 20 68 mizations, and h
6480: 65 6e 63 65 20 73 65 74 20 61 6c 6c 20 63 6f 6d ence set all com
6490: 70 69 6c 65 72 20 6d 61 63 72 6f 73 20 74 6f 20 piler macros to
64a0: 30 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 77 61 0.**.** There wa
64b0: 73 20 6f 6e 63 65 20 61 6c 73 6f 20 61 20 43 4c s once also a CL
64c0: 41 4e 47 5f 56 45 52 53 49 4f 4e 20 6d 61 63 72 ANG_VERSION macr
64d0: 6f 2e 20 20 48 6f 77 65 76 65 72 2c 20 77 65 20 o. However, we
64e0: 6c 65 61 72 6e 20 74 68 61 74 20 74 68 65 0a 2a learn that the.*
64f0: 2a 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 * version number
6500: 73 20 69 6e 20 63 6c 61 6e 67 20 61 72 65 20 66 s in clang are f
6510: 6f 72 20 22 6d 61 72 6b 65 74 69 6e 67 22 20 6f or "marketing" o
6520: 6e 6c 79 20 61 6e 64 20 61 72 65 20 69 6e 63 6f nly and are inco
6530: 6e 73 69 73 74 65 6e 74 0a 2a 2a 20 61 6e 64 20 nsistent.** and
6540: 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 46 6f 72 unreliable. For
6550: 74 75 6e 61 74 65 6c 79 2c 20 61 6c 6c 20 76 65 tunately, all ve
6560: 72 73 69 6f 6e 73 20 6f 66 20 63 6c 61 6e 67 20 rsions of clang
6570: 61 6c 73 6f 20 72 65 63 6f 67 6e 69 7a 65 20 74 also recognize t
6580: 68 65 0a 2a 2a 20 67 63 63 20 76 65 72 73 69 6f he.** gcc versio
6590: 6e 20 6e 75 6d 62 65 72 73 20 61 6e 64 20 68 61 n numbers and ha
65a0: 76 65 20 72 65 61 73 6f 6e 61 62 6c 65 20 73 65 ve reasonable se
65b0: 74 74 69 6e 67 73 20 66 6f 72 20 67 63 63 20 76 ttings for gcc v
65c0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 73 2c 0a ersion numbers,.
65d0: 2a 2a 20 73 6f 20 74 68 65 20 47 43 43 5f 56 45 ** so the GCC_VE
65e0: 52 53 49 4f 4e 20 6d 61 63 72 6f 20 77 69 6c 6c RSION macro will
65f0: 20 62 65 20 73 65 74 20 74 6f 20 61 20 63 6f 72 be set to a cor
6600: 72 65 63 74 20 6e 6f 6e 2d 7a 65 72 6f 20 76 61 rect non-zero va
6610: 6c 75 65 20 65 76 65 6e 0a 2a 2a 20 77 68 65 6e lue even.** when
6620: 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 compiling with
6630: 63 6c 61 6e 67 2e 0a 2a 2f 0a 23 69 66 20 64 65 clang..*/.#if de
6640: 66 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 fined(__GNUC__)
6650: 26 26 20 21 64 65 66 69 6e 65 64 28 53 51 4c 49 && !defined(SQLI
6660: 54 45 5f 44 49 53 41 42 4c 45 5f 49 4e 54 52 49 TE_DISABLE_INTRI
6670: 4e 53 49 43 29 0a 23 20 64 65 66 69 6e 65 20 47 NSIC).# define G
6680: 43 43 5f 56 45 52 53 49 4f 4e 20 28 5f 5f 47 4e CC_VERSION (__GN
6690: 55 43 5f 5f 2a 31 30 30 30 30 30 30 2b 5f 5f 47 UC__*1000000+__G
66a0: 4e 55 43 5f 4d 49 4e 4f 52 5f 5f 2a 31 30 30 30 NUC_MINOR__*1000
66b0: 2b 5f 5f 47 4e 55 43 5f 50 41 54 43 48 4c 45 56 +__GNUC_PATCHLEV
66c0: 45 4c 5f 5f 29 0a 23 65 6c 73 65 0a 23 20 64 65 EL__).#else.# de
66d0: 66 69 6e 65 20 47 43 43 5f 56 45 52 53 49 4f 4e fine GCC_VERSION
66e0: 20 30 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65 0.#endif.#if de
66f0: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 fined(_MSC_VER)
6700: 26 26 20 21 64 65 66 69 6e 65 64 28 53 51 4c 49 && !defined(SQLI
6710: 54 45 5f 44 49 53 41 42 4c 45 5f 49 4e 54 52 49 TE_DISABLE_INTRI
6720: 4e 53 49 43 29 0a 23 20 64 65 66 69 6e 65 20 4d NSIC).# define M
6730: 53 56 43 5f 56 45 52 53 49 4f 4e 20 5f 4d 53 43 SVC_VERSION _MSC
6740: 5f 56 45 52 0a 23 65 6c 73 65 0a 23 20 64 65 66 _VER.#else.# def
6750: 69 6e 65 20 4d 53 56 43 5f 56 45 52 53 49 4f 4e ine MSVC_VERSION
6760: 20 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e 65 0.#endif../* Ne
6770: 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f 75 73 eded for various
6780: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e 20 definitions...
6790: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f */.#if defined(_
67a0: 5f 47 4e 55 43 5f 5f 29 20 26 26 20 21 64 65 66 _GNUC__) && !def
67b0: 69 6e 65 64 28 5f 47 4e 55 5f 53 4f 55 52 43 45 ined(_GNU_SOURCE
67c0: 29 0a 23 20 64 65 66 69 6e 65 20 5f 47 4e 55 5f ).# define _GNU_
67d0: 53 4f 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a 23 SOURCE.#endif..#
67e0: 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 4f 70 65 if defined(__Ope
67f0: 6e 42 53 44 5f 5f 29 20 26 26 20 21 64 65 66 69 nBSD__) && !defi
6800: 6e 65 64 28 5f 42 53 44 5f 53 4f 55 52 43 45 29 ned(_BSD_SOURCE)
6810: 0a 23 20 64 65 66 69 6e 65 20 5f 42 53 44 5f 53 .# define _BSD_S
6820: 4f 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a OURCE.#endif../*
6830: 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47 57 2c 20 63 .** For MinGW, c
6840: 68 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20 77 heck to see if w
6850: 65 20 63 61 6e 20 69 6e 63 6c 75 64 65 20 74 68 e can include th
6860: 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 63 6f e header file co
6870: 6e 74 61 69 6e 69 6e 67 20 69 74 73 0a 2a 2a 20 ntaining its.**
6880: 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d 61 74 version informat
6890: 69 6f 6e 2c 20 61 6d 6f 6e 67 20 6f 74 68 65 72 ion, among other
68a0: 20 74 68 69 6e 67 73 2e 20 20 4e 6f 72 6d 61 6c things. Normal
68b0: 6c 79 2c 20 74 68 69 73 20 69 6e 74 65 72 6e 61 ly, this interna
68c0: 6c 20 4d 69 6e 47 57 0a 2a 2a 20 68 65 61 64 65 l MinGW.** heade
68d0: 72 20 66 69 6c 65 20 77 6f 75 6c 64 20 5b 6f 6e r file would [on
68e0: 6c 79 5d 20 62 65 20 69 6e 63 6c 75 64 65 64 20 ly] be included
68f0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 automatically by
6900: 20 6f 74 68 65 72 20 4d 69 6e 47 57 20 68 65 61 other MinGW hea
6910: 64 65 72 0a 2a 2a 20 66 69 6c 65 73 3b 20 68 6f der.** files; ho
6920: 77 65 76 65 72 2c 20 74 68 65 20 63 6f 6e 74 61 wever, the conta
6930: 69 6e 65 64 20 76 65 72 73 69 6f 6e 20 69 6e 66 ined version inf
6940: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6e 6f 77 20 ormation is now
6950: 72 65 71 75 69 72 65 64 20 62 79 20 74 68 69 73 required by this
6960: 0a 2a 2a 20 68 65 61 64 65 72 20 66 69 6c 65 20 .** header file
6970: 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 62 to work around b
6980: 69 6e 61 72 79 20 63 6f 6d 70 61 74 69 62 69 6c inary compatibil
6990: 69 74 79 20 69 73 73 75 65 73 20 28 73 65 65 20 ity issues (see
69a0: 62 65 6c 6f 77 29 20 61 6e 64 0a 2a 2a 20 74 68 below) and.** th
69b0: 69 73 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 6b is is the only k
69c0: 6e 6f 77 6e 20 77 61 79 20 74 6f 20 72 65 6c 69 nown way to reli
69d0: 61 62 6c 79 20 6f 62 74 61 69 6e 20 69 74 2e 20 ably obtain it.
69e0: 20 54 68 69 73 20 65 6e 74 69 72 65 20 23 69 66 This entire #if
69f0: 20 62 6c 6f 63 6b 0a 2a 2a 20 77 6f 75 6c 64 20 block.** would
6a00: 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 20 75 6e be completely un
6a10: 6e 65 63 65 73 73 61 72 79 20 69 66 20 74 68 65 necessary if the
6a20: 72 65 20 77 61 73 20 61 6e 79 20 6f 74 68 65 72 re was any other
6a30: 20 77 61 79 20 6f 66 20 64 65 74 65 63 74 69 6e way of detectin
6a40: 67 0a 2a 2a 20 4d 69 6e 47 57 20 76 69 61 20 74 g.** MinGW via t
6a50: 68 65 69 72 20 70 72 65 70 72 6f 63 65 73 73 6f heir preprocesso
6a60: 72 20 28 65 2e 67 2e 20 69 66 20 74 68 65 79 20 r (e.g. if they
6a70: 63 75 73 74 6f 6d 69 7a 65 64 20 74 68 65 69 72 customized their
6a80: 20 47 43 43 20 74 6f 20 64 65 66 69 6e 65 0a 2a GCC to define.*
6a90: 2a 20 73 6f 6d 65 20 4d 69 6e 47 57 2d 73 70 65 * some MinGW-spe
6aa0: 63 69 66 69 63 20 6d 61 63 72 6f 73 29 2e 20 20 cific macros).
6ab0: 57 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 66 When compiling f
6ac0: 6f 72 20 4d 69 6e 47 57 2c 20 65 69 74 68 65 72 or MinGW, either
6ad0: 20 74 68 65 0a 2a 2a 20 5f 48 41 56 45 5f 4d 49 the.** _HAVE_MI
6ae0: 4e 47 57 5f 48 20 6f 72 20 5f 48 41 56 45 5f 5f NGW_H or _HAVE__
6af0: 4d 49 4e 47 57 5f 48 20 28 6e 6f 74 65 20 74 68 MINGW_H (note th
6b00: 65 20 65 78 74 72 61 20 75 6e 64 65 72 73 63 6f e extra undersco
6b10: 72 65 29 20 6d 61 63 72 6f 20 6d 75 73 74 20 62 re) macro must b
6b20: 65 0a 2a 2a 20 64 65 66 69 6e 65 64 3b 20 6f 74 e.** defined; ot
6b30: 68 65 72 77 69 73 65 2c 20 64 65 74 65 63 74 69 herwise, detecti
6b40: 6f 6e 20 6f 66 20 63 6f 6e 64 69 74 69 6f 6e 73 on of conditions
6b50: 20 73 70 65 63 69 66 69 63 20 74 6f 20 4d 69 6e specific to Min
6b60: 47 57 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 69 GW will be.** di
6b70: 73 61 62 6c 65 64 2e 0a 2a 2f 0a 23 69 66 20 64 sabled..*/.#if d
6b80: 65 66 69 6e 65 64 28 5f 48 41 56 45 5f 4d 49 4e efined(_HAVE_MIN
6b90: 47 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 GW_H).# include
6ba0: 22 6d 69 6e 67 77 2e 68 22 0a 23 65 6c 69 66 20 "mingw.h".#elif
6bb0: 64 65 66 69 6e 65 64 28 5f 48 41 56 45 5f 5f 4d defined(_HAVE__M
6bc0: 49 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 INGW_H).# includ
6bd0: 65 20 22 5f 6d 69 6e 67 77 2e 68 22 0a 23 65 6e e "_mingw.h".#en
6be0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d dif../*.** For M
6bf0: 69 6e 47 57 20 76 65 72 73 69 6f 6e 20 34 2e 78 inGW version 4.x
6c00: 20 28 61 6e 64 20 68 69 67 68 65 72 29 2c 20 63 (and higher), c
6c10: 68 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20 74 heck to see if t
6c20: 68 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 he _USE_32BIT_TI
6c30: 4d 45 5f 54 0a 2a 2a 20 64 65 66 69 6e 65 20 69 ME_T.** define i
6c40: 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 6d 61 s required to ma
6c50: 69 6e 74 61 69 6e 20 62 69 6e 61 72 79 20 63 6f intain binary co
6c60: 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 mpatibility with
6c70: 20 74 68 65 20 4d 53 56 43 20 72 75 6e 74 69 6d the MSVC runtim
6c80: 65 0a 2a 2a 20 6c 69 62 72 61 72 79 20 69 6e 20 e.** library in
6c90: 75 73 65 20 28 65 2e 67 2e 20 66 6f 72 20 57 69 use (e.g. for Wi
6ca0: 6e 64 6f 77 73 20 58 50 29 2e 0a 2a 2f 0a 23 69 ndows XP)..*/.#i
6cb0: 66 20 21 64 65 66 69 6e 65 64 28 5f 55 53 45 5f f !defined(_USE_
6cc0: 33 32 42 49 54 5f 54 49 4d 45 5f 54 29 20 26 26 32BIT_TIME_T) &&
6cd0: 20 21 64 65 66 69 6e 65 64 28 5f 55 53 45 5f 36 !defined(_USE_6
6ce0: 34 42 49 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 4BIT_TIME_T) &&
6cf0: 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 57 \. defined(_W
6d00: 49 4e 33 32 29 20 26 26 20 21 64 65 66 69 6e 65 IN32) && !define
6d10: 64 28 5f 57 49 4e 36 34 29 20 26 26 20 5c 0a 20 d(_WIN64) && \.
6d20: 20 20 20 64 65 66 69 6e 65 64 28 5f 5f 4d 49 4e defined(__MIN
6d30: 47 57 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e GW_MAJOR_VERSION
6d40: 29 20 26 26 20 5f 5f 4d 49 4e 47 57 5f 4d 41 4a ) && __MINGW_MAJ
6d50: 4f 52 5f 56 45 52 53 49 4f 4e 20 3e 3d 20 34 20 OR_VERSION >= 4
6d60: 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 && \. defined
6d70: 28 5f 5f 4d 53 56 43 52 54 5f 5f 29 0a 23 20 64 (__MSVCRT__).# d
6d80: 65 66 69 6e 65 20 5f 55 53 45 5f 33 32 42 49 54 efine _USE_32BIT
6d90: 5f 54 49 4d 45 5f 54 0a 23 65 6e 64 69 66 0a 0a _TIME_T.#endif..
6da0: 2f 2a 20 54 68 65 20 70 75 62 6c 69 63 20 53 51 /* The public SQ
6db0: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 Lite interface.
6dc0: 20 54 68 65 20 5f 46 49 4c 45 5f 4f 46 46 53 45 The _FILE_OFFSE
6dd0: 54 5f 42 49 54 53 20 6d 61 63 72 6f 20 6d 75 73 T_BITS macro mus
6de0: 74 20 61 70 70 65 61 72 0a 2a 2a 20 66 69 72 73 t appear.** firs
6df0: 74 20 69 6e 20 51 4e 58 2e 20 20 41 6c 73 6f 2c t in QNX. Also,
6e00: 20 74 68 65 20 5f 55 53 45 5f 33 32 42 49 54 5f the _USE_32BIT_
6e10: 54 49 4d 45 5f 54 20 6d 61 63 72 6f 20 6d 75 73 TIME_T macro mus
6e20: 74 20 61 70 70 65 61 72 20 66 69 72 73 74 20 66 t appear first f
6e30: 6f 72 0a 2a 2a 20 4d 69 6e 47 57 2e 0a 2a 2f 0a or.** MinGW..*/.
6e40: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 /**************
6e50: 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 65 33 2e Include sqlite3.
6e60: 68 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 h in the middle
6e70: 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a of sqliteInt.h *
6e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a **************/.
6e90: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 /**************
6ea0: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 Begin file sqlit
6eb0: 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a e3.h ***********
6ec0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
6ed0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a **************/.
6ee0: 2f 2a 0a 2a 2a 20 32 30 30 31 2d 30 39 2d 31 35 /*.** 2001-09-15
6ef0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f .**.** The autho
6f00: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 r disclaims copy
6f10: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f right to this so
6f20: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 urce code. In p
6f30: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 lace of.** a leg
6f40: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 al notice, here
6f50: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a is a blessing:.*
6f60: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 *.** May you
6f70: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 do good and not
6f80: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 evil..** May
6f90: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65 you find forgive
6fa0: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c ness for yoursel
6fb0: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 f and forgive ot
6fc0: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 hers..** May
6fd0: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79 you share freely
6fe0: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d , never taking m
6ff0: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76 ore than you giv
7000: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a e..**.**********
7010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
7020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
7030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
7040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a ***************.
7050: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66 ** This header f
7060: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 ile defines the
7070: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74 interface that t
7080: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
7090: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f y.** presents to
70a0: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 client programs
70b0: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69 . If a C-functi
70c0: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64 on, structure, d
70d0: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 atatype,.** or c
70e0: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69 onstant definiti
70f0: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 on does not appe
7100: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c ar in this file,
7110: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e then it is.** n
7120: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41 ot a published A
7130: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 PI of SQLite, is
7140: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e subject to chan
7150: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f ge without.** no
7160: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 tice, and should
7170: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63 not be referenc
7180: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74 ed by programs t
7190: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a hat use SQLite..
71a0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 **.** Some of th
71b0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 e definitions th
71c0: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66 at are in this f
71d0: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61 ile are marked a
71e0: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 s.** "experiment
71f0: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 al". Experiment
7200: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 al interfaces ar
7210: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a e normally new.*
7220: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e * features recen
7230: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c tly added to SQL
7240: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 ite. We do not
7250: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67 anticipate chang
7260: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d es.** to experim
7270: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 ental interfaces
7280: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65 but reserve the
7290: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d right to make m
72a0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 inor changes.**
72b0: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 if experience fr
72c0: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 om use "in the w
72d0: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63 ild" suggest suc
72e0: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 h changes are pr
72f0: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 udent..**.** The
7300: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 official C-lang
7310: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e uage API documen
7320: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 tation for SQLit
7330: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 e is derived.**
7340: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e from comments in
7350: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 this file. Thi
7360: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 s file is the au
7370: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 thoritative sour
7380: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c ce.** on how SQL
7390: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 ite interfaces a
73a0: 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f 20 6f re supposed to o
73b0: 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 perate..**.** Th
73c0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66 e name of this f
73d0: 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 ile under config
73e0: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 uration manageme
73f0: 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e nt is "sqlite.h.
7400: 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 in"..** The make
7410: 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 file makes some
7420: 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f minor changes to
7430: 20 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68 this file (such
7440: 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a as inserting.**
7450: 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d the version num
7460: 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73 ber) and changes
7470: 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 its name to "sq
7480: 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 lite3.h" as.** p
7490: 61 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64 art of the build
74a0: 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 process..*/.#if
74b0: 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48 0a 23 ndef SQLITE3_H.#
74c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 48 define SQLITE3_H
74d0: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72 .#include <stdar
74e0: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64 g.h> /* Need
74f0: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e ed for the defin
7500: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74 ition of va_list
7510: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 */../*.** Make
7520: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c sure we can call
7530: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d this stuff from
7540: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 C++..*/.#if 0.e
7550: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 xtern "C" {.#end
7560: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 if.../*.** Provi
7570: 64 65 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 de the ability t
7580: 6f 20 6f 76 65 72 72 69 64 65 20 6c 69 6e 6b 61 o override linka
7590: 67 65 20 66 65 61 74 75 72 65 73 20 6f 66 20 74 ge features of t
75a0: 68 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f he interface..*/
75b0: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f .#ifndef SQLITE_
75c0: 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e 65 20 EXTERN.# define
75d0: 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 65 78 SQLITE_EXTERN ex
75e0: 74 65 72 6e 0a 23 65 6e 64 69 66 0a 23 69 66 6e tern.#endif.#ifn
75f0: 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 def SQLITE_API.#
7600: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 define SQLITE_A
7610: 50 49 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 PI.#endif.#ifnde
7620: 66 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 f SQLITE_CDECL.#
7630: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 define SQLITE_C
7640: 44 45 43 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e DECL.#endif.#ifn
7650: 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 43 41 def SQLITE_APICA
7660: 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 LL.# define SQLI
7670: 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 TE_APICALL.#endi
7680: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 f.#ifndef SQLITE
7690: 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66 69 6e _STDCALL.# defin
76a0: 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c e SQLITE_STDCALL
76b0: 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a SQLITE_APICALL.
76c0: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 #endif.#ifndef S
76d0: 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 QLITE_CALLBACK.#
76e0: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 define SQLITE_C
76f0: 41 4c 4c 42 41 43 4b 0a 23 65 6e 64 69 66 0a 23 ALLBACK.#endif.#
7700: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 53 59 ifndef SQLITE_SY
7710: 53 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 SAPI.# define SQ
7720: 4c 49 54 45 5f 53 59 53 41 50 49 0a 23 65 6e 64 LITE_SYSAPI.#end
7730: 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 if../*.** These
7740: 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 no-op macros are
7750: 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f used in front o
7760: 66 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 f interfaces to
7770: 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e mark those.** in
7780: 74 65 72 66 61 63 65 73 20 61 73 20 65 69 74 68 terfaces as eith
7790: 65 72 20 64 65 70 72 65 63 61 74 65 64 20 6f 72 er deprecated or
77a0: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 experimental.
77b0: 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 New applications
77c0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 .** should not u
77d0: 73 65 20 64 65 70 72 65 63 61 74 65 64 20 69 6e se deprecated in
77e0: 74 65 72 66 61 63 65 73 20 2d 20 74 68 65 79 20 terfaces - they
77f0: 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f are supported fo
7800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 r backwards.** c
7810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c ompatibility onl
7820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20 y. Application
7830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62 writers should b
7840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20 e aware that.**
7850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 experimental int
7860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a erfaces are subj
7870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e ect to change in
7880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e point releases.
7890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63 .**.** These mac
78a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f ros used to reso
78b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b lve to various k
78c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72 inds of compiler
78d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77 magic that.** w
78e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61 ould generate wa
78f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77 rning messages w
7900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73 hen they were us
7910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a ed. But that.**
7920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 compiler magic
7930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74 ended up generat
7940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72 ing such a flurr
7950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73 y of bug reports
7960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65 .** that we have
7970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75 taken it all ou
7980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20 t and gone back
7990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a to using simple.
79a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a ** noop macros..
79b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
79c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65 E_DEPRECATED.#de
79d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45 fine SQLITE_EXPE
79e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 RIMENTAL../*.**
79f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d Ensure these sym
7a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65 bols were not de
7a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72 fined by some pr
7a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69 evious header fi
7a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 le..*/.#ifdef SQ
7a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75 LITE_VERSION.# u
7a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 ndef SQLITE_VERS
7a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 ION.#endif.#ifde
7a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e f SQLITE_VERSION
7a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20 _NUMBER.# undef
7a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e SQLITE_VERSION_N
7aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a UMBER.#endif../*
7ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f .** CAPI3REF: Co
7ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61 mpile-Time Libra
7ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
7ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b rs.**.** ^(The [
7af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20 SQLITE_VERSION]
7b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d C preprocessor m
7b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69 acro in the sqli
7b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20 te3.h header.**
7b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73 evaluates to a s
7b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68 tring literal th
7b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65 at is the SQLite
7b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a version in the.
7b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a ** format "X.Y.Z
7b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65 " where X is the
7b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e major version n
7ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20 umber (always 3
7bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20 for.** SQLite3)
7bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e and Y is the min
7bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 or version numbe
7be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72 r and Z is the r
7bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e elease number.)^
7c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 .** ^(The [SQLIT
7c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
7c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 ] C preprocessor
7c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20 macro resolves
7c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a to an integer.**
7c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20 with the value
7c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31 (X*1000000 + Y*1
7c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58 000 + Z) where X
7c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74 , Y, and Z are t
7c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 he same.** numbe
7ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49 rs used in [SQLI
7cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a TE_VERSION].)^.*
7cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52 * The SQLITE_VER
7cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20 SION_NUMBER for
7ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73 any given releas
7cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c e of SQLite will
7d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 also.** be larg
7d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65 er than the rele
7d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69 ase from which i
7d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45 t is derived. E
7d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 ither Y will.**
7d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74 be held constant
7d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69 and Z will be i
7d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c ncremented or el
7d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63 se Y will be inc
7d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 remented.** and
7da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20 Z will be reset
7db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 to zero..**.** S
7dc0: 69 6e 63 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e ince [version 3.
7dd0: 36 2e 31 38 5d 20 28 5b 64 61 74 65 6f 66 3a 33 6.18] ([dateof:3
7de0: 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a 20 53 51 4c .6.18]), .** SQL
7df0: 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 ite source code
7e00: 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 has been stored
7e10: 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 in the.** <a hre
7e20: 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f f="http://www.fo
7e30: 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 ssil-scm.org/">F
7e40: 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 ossil configurat
7e50: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a ion management.*
7e60: 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e * system</a>. ^
7e70: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 The SQLITE_SOURC
7e80: 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 E_ID macro evalu
7e90: 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 ates to.** a str
7ea0: 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 ing which identi
7eb0: 66 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 fies a particula
7ec0: 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 r check-in of SQ
7ed0: 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 Lite.** within i
7ee0: 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ts configuration
7ef0: 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 management syst
7f00: 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 em. ^The SQLITE
7f10: 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 _SOURCE_ID.** st
7f20: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 ring contains th
7f30: 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 e date and time
7f40: 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 of the check-in
7f50: 28 55 54 43 29 20 61 6e 64 20 61 20 53 48 41 31 (UTC) and a SHA1
7f60: 0a 2a 2a 20 6f 72 20 53 48 41 33 2d 32 35 36 20 .** or SHA3-256
7f70: 68 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 hash of the enti
7f80: 72 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 20 re source tree.
7f90: 20 49 66 20 74 68 65 20 73 6f 75 72 63 65 20 63 If the source c
7fa0: 6f 64 65 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 ode has.** been
7fb0: 65 64 69 74 65 64 20 69 6e 20 61 6e 79 20 77 61 edited in any wa
7fc0: 79 20 73 69 6e 63 65 20 69 74 20 77 61 73 20 6c y since it was l
7fd0: 61 73 74 20 63 68 65 63 6b 65 64 20 69 6e 2c 20 ast checked in,
7fe0: 74 68 65 6e 20 74 68 65 20 6c 61 73 74 0a 2a 2a then the last.**
7ff0: 20 66 6f 75 72 20 68 65 78 61 64 65 63 69 6d 61 four hexadecima
8000: 6c 20 64 69 67 69 74 73 20 6f 66 20 74 68 65 20 l digits of the
8010: 68 61 73 68 20 6d 61 79 20 62 65 20 6d 6f 64 69 hash may be modi
8020: 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 fied..**.** See
8030: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c also: [sqlite3_l
8040: 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a ibversion()],.**
8050: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 [sqlite3_libver
8060: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 sion_number()],
8070: 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 [sqlite3_sourcei
8080: 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 d()],.** [sqlite
8090: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 _version()] and
80a0: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 [sqlite_source_i
80b0: 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 d()]..*/.#define
80c0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 SQLITE_VERSION
80d0: 20 20 20 20 20 20 20 22 33 2e 32 35 2e 33 22 0a "3.25.3".
80e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 #define SQLITE_V
80f0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 ERSION_NUMBER 30
8100: 32 35 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 25003.#define SQ
8110: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 LITE_SOURCE_ID
8120: 20 20 20 20 22 32 30 31 38 2d 31 31 2d 30 35 20 "2018-11-05
8130: 32 30 3a 33 37 3a 33 38 20 38 39 65 30 39 39 66 20:37:38 89e099f
8140: 62 65 35 65 31 33 63 33 33 65 36 38 33 62 65 66 be5e13c33e683bef
8150: 30 37 33 36 31 32 33 31 63 61 35 32 35 62 38 38 07361231ca525b88
8160: 66 37 39 30 37 62 65 37 30 39 32 30 35 38 30 30 f7907be709205800
8170: 37 62 37 35 30 33 36 66 32 22 0a 0a 2f 2a 0a 2a 7b75036f2"../*.*
8180: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d * CAPI3REF: Run-
8190: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 Time Library Ver
81a0: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 sion Numbers.**
81b0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 KEYWORDS: sqlite
81c0: 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c 69 74 65 3_version sqlite
81d0: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 3_sourceid.**.**
81e0: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 These interface
81f0: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 s provide the sa
8200: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 me information a
8210: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 s the [SQLITE_VE
8220: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 RSION],.** [SQLI
8230: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
8240: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f R], and [SQLITE_
8250: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 SOURCE_ID] C pre
8260: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 processor macros
8270: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f .** but are asso
8280: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
8290: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 library instead
82a0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 of the header fi
82b0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a le. ^(Cautious.
82c0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d ** programmers m
82d0: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 ight include ass
82e0: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 ert() statements
82f0: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 in their applic
8300: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 ation to.** veri
8310: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 fy that values r
8320: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 eturned by these
8330: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 interfaces matc
8340: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a h the macros in.
8350: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 ** the header, a
8360: 6e 64 20 74 68 75 73 20 65 6e 73 75 72 65 20 74 nd thus ensure t
8370: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 hat the applicat
8380: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c ion is.** compil
8390: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 ed with matching
83a0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 library and hea
83b0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a der files..**.**
83c0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 <blockquote><pr
83d0: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 e>.** assert( sq
83e0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
83f0: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 _number()==SQLIT
8400: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
8410: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 );.** assert( s
8420: 74 72 6e 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 trncmp(sqlite3_s
8430: 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 ourceid(),SQLITE
8440: 5f 53 4f 55 52 43 45 5f 49 44 2c 38 30 29 3d 3d _SOURCE_ID,80)==
8450: 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 0 );.** assert(
8460: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c strcmp(sqlite3_l
8470: 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 ibversion(),SQLI
8480: 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 TE_VERSION)==0 )
8490: 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ;.** </pre></blo
84a0: 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a ckquote>)^.**.**
84b0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 ^The sqlite3_ve
84c0: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 rsion[] string c
84d0: 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 onstant contains
84e0: 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 the text of [SQ
84f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a LITE_VERSION].**
8500: 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 macro. ^The sq
8510: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e lite3_libversion
8520: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 () function retu
8530: 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f rns a pointer to
8540: 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 the.** to the s
8550: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d qlite3_version[]
8560: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
8570: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c . The sqlite3_l
8580: 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 ibversion().** f
8590: 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 unction is provi
85a0: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 ded for use in D
85b0: 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 LLs since DLL us
85c0: 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e ers usually do n
85d0: 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 ot have.** direc
85e0: 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 t access to stri
85f0: 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 ng constants wit
8600: 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 hin the DLL. ^T
8610: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 he.** sqlite3_li
8620: 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 bversion_number(
8630: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 ) function retur
8640: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 ns an integer eq
8650: 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 ual to.** [SQLIT
8660: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 E_VERSION_NUMBER
8670: 5d 2e 20 20 5e 28 54 68 65 20 73 71 6c 69 74 65 ]. ^(The sqlite
8680: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e 3_sourceid() fun
8690: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a ction returns .*
86a0: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 * a pointer to a
86b0: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 string constant
86c0: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20 whose value is
86d0: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20 the same as the
86e0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 .** [SQLITE_SOUR
86f0: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 CE_ID] C preproc
8700: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 20 20 45 78 essor macro. Ex
8710: 63 65 70 74 20 69 66 20 53 51 4c 69 74 65 20 69 cept if SQLite i
8720: 73 20 62 75 69 6c 74 0a 2a 2a 20 75 73 69 6e 67 s built.** using
8730: 20 61 6e 20 65 64 69 74 65 64 20 63 6f 70 79 20 an edited copy
8740: 6f 66 20 5b 74 68 65 20 61 6d 61 6c 67 61 6d 61 of [the amalgama
8750: 74 69 6f 6e 5d 2c 20 74 68 65 6e 20 74 68 65 20 tion], then the
8760: 6c 61 73 74 20 66 6f 75 72 20 63 68 61 72 61 63 last four charac
8770: 74 65 72 73 0a 2a 2a 20 6f 66 20 74 68 65 20 68 ters.** of the h
8780: 61 73 68 20 6d 69 67 68 74 20 62 65 20 64 69 66 ash might be dif
8790: 66 65 72 65 6e 74 20 66 72 6f 6d 20 5b 53 51 4c ferent from [SQL
87a0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 2e 29 ITE_SOURCE_ID].)
87b0: 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ^.**.** See also
87c0: 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f : [sqlite_versio
87d0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 n()] and [sqlite
87e0: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a _source_id()]..*
87f0: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e /.SQLITE_API con
8800: 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f st char sqlite3_
8810: 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 version[] = SQLI
8820: 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 TE_VERSION;.SQLI
8830: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 TE_API const cha
8840: 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 r *sqlite3_libve
8850: 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c rsion(void);.SQL
8860: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 ITE_API const ch
8870: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 ar *sqlite3_sour
8880: 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 ceid(void);.SQLI
8890: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
88a0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 e3_libversion_nu
88b0: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a mber(void);../*.
88c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e ** CAPI3REF: Run
88d0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f -Time Library Co
88e0: 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e mpilation Option
88f0: 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a s Diagnostics.**
8900: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
8910: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 _compileoption_u
8920: 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 sed() function r
8930: 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a eturns 0 or 1 .*
8940: 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 * indicating whe
8950: 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69 ther the specifi
8960: 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 ed option was de
8970: 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d fined at .** com
8980: 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 pile time. ^The
8990: 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 SQLITE_ prefix
89a0: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 may be omitted f
89b0: 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 rom the .** opti
89c0: 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 on name passed t
89d0: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c o sqlite3_compil
89e0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 eoption_used().
89f0: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c .**.** ^The sql
8a00: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
8a10: 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f on_get() functio
8a20: 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 n allows iterati
8a30: 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c ng.** over the l
8a40: 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 ist of options t
8a50: 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 hat were defined
8a60: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 at compile time
8a70: 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 by.** returning
8a80: 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c the N-th compil
8a90: 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 e time option st
8aa0: 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 ring. ^If N is
8ab0: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a out of range,.**
8ac0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 sqlite3_compile
8ad0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 option_get() ret
8ae0: 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e urns a NULL poin
8af0: 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 ter. ^The SQLIT
8b00: 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 E_ .** prefix is
8b10: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e omitted from an
8b20: 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e y strings return
8b30: 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 ed by .** sqlite
8b40: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 3_compileoption_
8b50: 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 get()..**.** ^Su
8b60: 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 pport for the di
8b70: 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f agnostic functio
8b80: 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 ns sqlite3_compi
8b90: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a leoption_used().
8ba0: 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 ** and sqlite3_c
8bb0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 ompileoption_get
8bc0: 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 () may be omitte
8bd0: 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 d by specifying
8be0: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the .** [SQLITE_
8bf0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 OMIT_COMPILEOPTI
8c00: 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e ON_DIAGS] option
8c10: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 at compile time
8c20: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f ..**.** See also
8c30: 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 : SQL functions
8c40: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f [sqlite_compileo
8c50: 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e ption_used()] an
8c60: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d d.** [sqlite_com
8c70: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 pileoption_get()
8c80: 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 ] and the [compi
8c90: 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d le_options pragm
8ca0: 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 a]..*/.#ifndef S
8cb0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 QLITE_OMIT_COMPI
8cc0: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 LEOPTION_DIAGS.S
8cd0: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
8ce0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 lite3_compileopt
8cf0: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 ion_used(const c
8d00: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a har *zOptName);.
8d10: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
8d20: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 char *sqlite3_c
8d30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 ompileoption_get
8d40: 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a (int N);.#endif.
8d50: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
8d60: 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 Test To See If
8d70: 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 The Library Is T
8d80: 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 hreadsafe.**.**
8d90: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 ^The sqlite3_thr
8da0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 eadsafe() functi
8db0: 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 on returns zero
8dc0: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a if and only if.*
8dd0: 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d * SQLite was com
8de0: 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 piled with mutex
8df0: 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 ing code omitted
8e00: 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b due to the.** [
8e10: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
8e20: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 E] compile-time
8e30: 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 option being set
8e40: 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c to 0..**.** SQL
8e50: 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 ite can be compi
8e60: 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 led with or with
8e70: 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 out mutexes. Wh
8e80: 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 en.** the [SQLIT
8e90: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 E_THREADSAFE] C
8ea0: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
8eb0: 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 ro is 1 or 2, mu
8ec0: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 texes.** are ena
8ed0: 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 bled and SQLite
8ee0: 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 is threadsafe.
8ef0: 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c When the.** [SQL
8f00: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
8f10: 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 macro is 0, .**
8f20: 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 the mutexes are
8f30: 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 omitted. Withou
8f40: 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 t the mutexes, i
8f50: 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a t is not safe.**
8f60: 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 to use SQLite c
8f70: 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d oncurrently from
8f80: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 more than one t
8f90: 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 hread..**.** Ena
8fa0: 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e bling mutexes in
8fb0: 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c curs a measurabl
8fc0: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 e performance pe
8fd0: 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 nalty..** So if
8fe0: 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f speed is of utmo
8ff0: 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 st importance, i
9000: 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f t makes sense to
9010: 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 disable.** the
9020: 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f mutexes. But fo
9030: 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 r maximum safety
9040: 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 , mutexes should
9050: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 be enabled..**
9060: 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 ^The default beh
9070: 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 avior is for mut
9080: 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c exes to be enabl
9090: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 ed..**.** This i
90a0: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 nterface can be
90b0: 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 used by an appli
90c0: 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 cation to make s
90d0: 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 ure that the.**
90e0: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 version of SQLit
90f0: 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e e that it is lin
9100: 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 king against was
9110: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
9120: 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 * the desired se
9130: 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 tting of the [SQ
9140: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d LITE_THREADSAFE]
9150: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 macro..**.** Th
9160: 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c is interface onl
9170: 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 y reports on the
9180: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 compile-time mu
9190: 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f tex setting.** o
91a0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 f the [SQLITE_TH
91b0: 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 READSAFE] flag.
91c0: 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f If SQLite is co
91d0: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 mpiled with.** S
91e0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
91f0: 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 =1 or =2 then mu
9200: 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 texes are enable
9210: 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 d by default but
9220: 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 .** can be fully
9230: 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 or partially di
9240: 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 sabled using a c
9250: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f all to [sqlite3_
9260: 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 config()].** wit
9270: 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c h the verbs [SQL
9280: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c ITE_CONFIG_SINGL
9290: 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 ETHREAD], [SQLIT
92a0: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 E_CONFIG_MULTITH
92b0: 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 READ],.** or [SQ
92c0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 LITE_CONFIG_SERI
92d0: 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 ALIZED]. ^(The
92e0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
92f0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 the.** sqlite3_t
9300: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 hreadsafe() func
9310: 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 tion shows only
9320: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 the compile-time
9330: 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 setting of.** t
9340: 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f hread safety, no
9350: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 t any run-time c
9360: 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 hanges to that s
9370: 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a etting made by.*
9380: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 * sqlite3_config
9390: 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 (). In other wor
93a0: 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 ds, the return v
93b0: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 alue from sqlite
93c0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 3_threadsafe().*
93d0: 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 * is unchanged b
93e0: 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 y calls to sqlit
93f0: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a e3_config().)^.*
9400: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 *.** See the [th
9410: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f reading mode] do
9420: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 cumentation for
9430: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 additional infor
9440: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 mation..*/.SQLIT
9450: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
9460: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 3_threadsafe(voi
9470: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
9480: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f REF: Database Co
9490: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a nnection Handle.
94a0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 ** KEYWORDS: {da
94b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
94c0: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e n} {database con
94d0: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 nections}.**.**
94e0: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 Each open SQLite
94f0: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 database is rep
9500: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f resented by a po
9510: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 inter to an inst
9520: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f ance of.** the o
9530: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 paque structure
9540: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e named "sqlite3".
9550: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 It is useful t
9560: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 o think of an sq
9570: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 lite3.** pointer
9580: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 as an object.
9590: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 The [sqlite3_ope
95a0: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f n()], [sqlite3_o
95b0: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a pen16()], and.**
95c0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
95d0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 2()] interfaces
95e0: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 are its construc
95f0: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 tors, and [sqlit
9600: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 e3_close()].** a
9610: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 nd [sqlite3_clos
9620: 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 e_v2()] are its
9630: 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 destructors. Th
9640: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 ere are many oth
9650: 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 er.** interfaces
9660: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 (such as.** [sq
9670: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 lite3_prepare_v2
9680: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 ()], [sqlite3_cr
9690: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d eate_function()]
96a0: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
96b0: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3_busy_timeout()
96c0: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 ] to name but th
96d0: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 ree) that are me
96e0: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 thods on an.** s
96f0: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a qlite3 object..*
9700: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 /.typedef struct
9710: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 sqlite3 sqlite3
9720: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
9730: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 F: 64-Bit Intege
9740: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f r Types.** KEYWO
9750: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 RDS: sqlite_int6
9760: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 4 sqlite_uint64.
9770: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 **.** Because th
9780: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d ere is no cross-
9790: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 platform way to
97a0: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 specify 64-bit i
97b0: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 nteger types.**
97c0: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 SQLite includes
97d0: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d typedefs for 64-
97e0: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 bit signed and u
97f0: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 nsigned integers
9800: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 ..**.** The sqli
9810: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 te3_int64 and sq
9820: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 lite3_uint64 are
9830: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 the preferred t
9840: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e ype definitions.
9850: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 .** The sqlite_i
9860: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f nt64 and sqlite_
9870: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 uint64 types are
9880: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 supported for b
9890: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 ackwards.** comp
98a0: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a atibility only..
98b0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
98c0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c e3_int64 and sql
98d0: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 ite_int64 types
98e0: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 can store intege
98f0: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 r values.** betw
9900: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 een -92233720368
9910: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 54775808 and +92
9920: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 2337203685477580
9930: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 7 inclusive. ^T
9940: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 he.** sqlite3_ui
9950: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f nt64 and sqlite_
9960: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e uint64 types can
9970: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 store integer v
9980: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 alues .** betwee
9990: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 n 0 and +1844674
99a0: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 4073709551615 in
99b0: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 clusive..*/.#ifd
99c0: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f ef SQLITE_INT64_
99d0: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 TYPE. typedef S
99e0: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 QLITE_INT64_TYPE
99f0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 23 sqlite_int64;.#
9a00: 20 69 66 64 65 66 20 53 51 4c 49 54 45 5f 55 49 ifdef SQLITE_UI
9a10: 4e 54 36 34 5f 54 59 50 45 0a 20 20 20 20 74 79 NT64_TYPE. ty
9a20: 70 65 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e pedef SQLITE_UIN
9a30: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f T64_TYPE sqlite_
9a40: 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73 65 20 20 uint64;.# else
9a50: 0a 20 20 20 20 74 79 70 65 64 65 66 20 75 6e 73 . typedef uns
9a60: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 igned SQLITE_INT
9a70: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 64_TYPE sqlite_u
9a80: 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69 66 0a 23 int64;.# endif.#
9a90: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 elif defined(_MS
9aa0: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 C_VER) || define
9ab0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a d(__BORLANDC__).
9ac0: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 typedef __int6
9ad0: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 4 sqlite_int64;.
9ae0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e typedef unsign
9af0: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 ed __int64 sqlit
9b00: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a e_uint64;.#else.
9b10: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c typedef long l
9b20: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 ong int sqlite_i
9b30: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
9b40: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f unsigned long lo
9b50: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 ng int sqlite_ui
9b60: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 nt64;.#endif.typ
9b70: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 edef sqlite_int6
9b80: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 4 sqlite3_int64;
9b90: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f .typedef sqlite_
9ba0: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 uint64 sqlite3_u
9bb0: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 int64;../*.** If
9bc0: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 compiling for a
9bd0: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 processor that
9be0: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 lacks floating p
9bf0: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a oint support,.**
9c00: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 substitute inte
9c10: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 ger for floating
9c20: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 -point..*/.#ifde
9c30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c f SQLITE_OMIT_FL
9c40: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 OATING_POINT.# d
9c50: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c efine double sql
9c60: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 ite3_int64.#endi
9c70: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 f../*.** CAPI3RE
9c80: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 F: Closing A Dat
9c90: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
9ca0: 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 .** DESTRUCTOR:
9cb0: 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
9cc0: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 he sqlite3_close
9cd0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
9ce0: 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e lose_v2() routin
9cf0: 65 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f es are destructo
9d00: 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 rs.** for the [s
9d10: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a qlite3] object..
9d20: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c ** ^Calls to sql
9d30: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 ite3_close() and
9d40: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 sqlite3_close_v
9d50: 32 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 2() return [SQLI
9d60: 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 TE_OK] if.** the
9d70: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 [sqlite3] objec
9d80: 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c t is successfull
9d90: 79 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 y destroyed and
9da0: 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a all associated.*
9db0: 2a 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 * resources are
9dc0: 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a deallocated..**.
9dd0: 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 ** ^If the datab
9de0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 ase connection i
9df0: 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 s associated wit
9e00: 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 h unfinalized pr
9e10: 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d epared.** statem
9e20: 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 ents or unfinish
9e30: 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 ed sqlite3_backu
9e40: 70 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 p objects then s
9e50: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a qlite3_close().*
9e60: 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 * will leave the
9e70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
9e80: 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 tion open and re
9e90: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 turn [SQLITE_BUS
9ea0: 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 Y]..** ^If sqlit
9eb0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 e3_close_v2() is
9ec0: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 called with unf
9ed0: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 inalized prepare
9ee0: 64 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 d statements.**
9ef0: 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 and/or unfinishe
9f00: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 d sqlite3_backup
9f10: 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 s, then the data
9f20: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
9f30: 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e becomes.** an un
9f40: 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 usable "zombie"
9f50: 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d which will autom
9f60: 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c atically be deal
9f70: 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 located when the
9f80: 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 .** last prepare
9f90: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 d statement is f
9fa0: 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 inalized or the
9fb0: 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 last sqlite3_bac
9fc0: 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 kup is.** finish
9fd0: 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 ed. The sqlite3
9fe0: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 _close_v2() inte
9ff0: 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 rface is intende
a000: 64 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a d for use with.*
a010: 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 * host languages
a020: 20 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 that are garbag
a030: 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 e collected, and
a040: 20 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 where the order
a050: 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 in which.** des
a060: 74 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c tructors are cal
a070: 6c 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 led is arbitrary
a080: 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ..**.** Applicat
a090: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c ions should [sql
a0a0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 ite3_finalize |
a0b0: 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 finalize] all [p
a0c0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
a0d0: 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ts],.** [sqlite3
a0e0: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c _blob_close | cl
a0f0: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 ose] all [BLOB h
a100: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a andles], and .**
a110: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 [sqlite3_backup
a120: 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 _finish | finish
a130: 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 ] all [sqlite3_b
a140: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 ackup] objects a
a150: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 ssociated.** wit
a160: 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 h the [sqlite3]
a170: 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 object prior to
a180: 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c attempting to cl
a190: 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 ose the object.
a1a0: 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f ^If.** sqlite3_
a1b0: 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 close_v2() is ca
a1c0: 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 lled on a [datab
a1d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
a1e0: 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a that still has.*
a1f0: 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 * outstanding [p
a200: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
a210: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c ts], [BLOB handl
a220: 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b es], and/or.** [
a230: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 sqlite3_backup]
a240: 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 objects then it
a250: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
a260: 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c OK] and the deal
a270: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 location.** of r
a280: 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 esources is defe
a290: 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b rred until all [
a2a0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
a2b0: 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 nts], [BLOB hand
a2c0: 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 les],.** and [sq
a2d0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 lite3_backup] ob
a2e0: 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 jects are also d
a2f0: 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 estroyed..**.**
a300: 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d ^If an [sqlite3]
a310: 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 object is destr
a320: 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 oyed while a tra
a330: 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e nsaction is open
a340: 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 ,.** the transac
a350: 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 tion is automati
a360: 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 cally rolled bac
a370: 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 k..**.** The C p
a380: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c arameter to [sql
a390: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 ite3_close(C)] a
a3a0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 nd [sqlite3_clos
a3b0: 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 e_v2(C)].** must
a3c0: 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c be either a NUL
a3d0: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 L.** pointer or
a3e0: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a an [sqlite3] obj
a3f0: 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 ect pointer obta
a400: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 ined.** from [sq
a410: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b lite3_open()], [
a420: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
a430: 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 ], or.** [sqlite
a440: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 3_open_v2()], an
a450: 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 d not previously
a460: 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c closed..** ^Cal
a470: 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f ling sqlite3_clo
a480: 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f se() or sqlite3_
a490: 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 close_v2() with
a4a0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a a NULL pointer.*
a4b0: 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 * argument is a
a4c0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a harmless no-op..
a4d0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
a4e0: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 t sqlite3_close(
a4f0: 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 sqlite3*);.SQLIT
a500: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
a510: 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 3_close_v2(sqlit
a520: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 e3*);../*.** The
a530: 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c type for a call
a540: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a back function..*
a550: 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 * This is legacy
a560: 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e and deprecated.
a570: 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 It is included
a580: 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a for historical.
a590: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ** compatibility
a5a0: 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 and is not docu
a5b0: 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 mented..*/.typed
a5c0: 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 ef int (*sqlite3
a5d0: 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a _callback)(void*
a5e0: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 ,int,char**, cha
a5f0: 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 r**);../*.** CAP
a600: 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 I3REF: One-Step
a610: 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 Query Execution
a620: 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 Interface.** MET
a630: 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
a640: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 ** The sqlite3_e
a650: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 xec() interface
a660: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 is a convenience
a670: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a wrapper around.
a680: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
a690: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
a6a0: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 te3_step()], and
a6b0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
a6c0: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 ze()],.** that a
a6d0: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 llows an applica
a6e0: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 tion to run mult
a6f0: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 iple statements
a700: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 of SQL.** withou
a710: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 t having to use
a720: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e a lot of C code.
a730: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c .**.** ^The sql
a740: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 ite3_exec() inte
a750: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 rface runs zero
a760: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e or more UTF-8 en
a770: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f coded,.** semico
a780: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c lon-separate SQL
a790: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 statements pass
a7a0: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 ed into its 2nd
a7b0: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 argument,.** in
a7c0: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 the context of t
a7d0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
a7e0: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 nection] passed
a7f0: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a in as its 1st.**
a800: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 argument. ^If
a810: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e the callback fun
a820: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 ction of the 3rd
a830: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
a840: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
a850: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e s not NULL, then
a860: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 it is invoked f
a870: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 or each result r
a880: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 ow.** coming out
a890: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 of the evaluate
a8a0: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 d SQL statements
a8b0: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 . ^The 4th argu
a8c0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 ment to.** sqlit
a8d0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c e3_exec() is rel
a8e0: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 ayed through to
a8f0: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 the 1st argument
a900: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c of each.** call
a910: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e back invocation.
a920: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 ^If the callba
a930: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 ck pointer to sq
a940: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 lite3_exec().**
a950: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f is NULL, then no
a960: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 callback is eve
a970: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 r invoked and re
a980: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a sult rows are.**
a990: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 ignored..**.**
a9a0: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 ^If an error occ
a9b0: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 urs while evalua
a9c0: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 ting the SQL sta
a9d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 tements passed i
a9e0: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 nto.** sqlite3_e
a9f0: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 xec(), then exec
aa00: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 ution of the cur
aa10: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 rent statement s
aa20: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 tops and.** subs
aa30: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 equent statement
aa40: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 s are skipped.
aa50: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 ^If the 5th para
aa60: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
aa70: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f _exec().** is no
aa80: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 t NULL then any
aa90: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 error message is
aaa0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 written into me
aab0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a mory obtained.**
aac0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
aad0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 alloc()] and pas
aae0: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 sed back through
aaf0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 the 5th paramet
ab00: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 er..** To avoid
ab10: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 memory leaks, th
ab20: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
ab30: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c ould invoke [sql
ab40: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 ite3_free()].**
ab50: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 on error message
ab60: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 strings returne
ab70: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 d through the 5t
ab80: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a h parameter of.*
ab90: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 * sqlite3_exec()
aba0: 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 after the error
abb0: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 message string
abc0: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 is no longer nee
abd0: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ded..** ^If the
abe0: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
abf0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
ac00: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 is not NULL and
ac10: 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 no errors.** occ
ac20: 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ur, then sqlite3
ac30: 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 _exec() sets the
ac40: 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 pointer in its
ac50: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
ac60: 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 .** NULL before
ac70: 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a returning..**.**
ac80: 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f ^If an sqlite3_
ac90: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 exec() callback
aca0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f returns non-zero
acb0: 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 , the sqlite3_ex
acc0: 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 ec().** routine
acd0: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 returns SQLITE_A
ace0: 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 BORT without inv
acf0: 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 oking the callba
ad00: 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 ck again and.**
ad10: 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 without running
ad20: 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 any subsequent S
ad30: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
ad40: 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 *.** ^The 2nd ar
ad50: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 gument to the sq
ad60: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
ad70: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 lback function i
ad80: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
ad90: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 of columns in th
ada0: 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 e result. ^The
adb0: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 3rd argument to
adc0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 the sqlite3_exec
add0: 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 ().** callback i
ade0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f s an array of po
adf0: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 inters to string
ae00: 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 s obtained as if
ae10: 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 from.** [sqlite
ae20: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 3_column_text()]
ae30: 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 , one for each c
ae40: 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 olumn. ^If an e
ae50: 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 lement of a.** r
ae60: 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c esult row is NUL
ae70: 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 L then the corre
ae80: 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 sponding string
ae90: 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a pointer for the.
aea0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 ** sqlite3_exec(
aeb0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 ) callback is a
aec0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e NULL pointer. ^
aed0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 The 4th argument
aee0: 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 to the.** sqlit
aef0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 e3_exec() callba
af00: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f ck is an array o
af10: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 f pointers to st
af20: 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 rings where each
af30: 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 .** entry repres
af40: 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 ents the name of
af50: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 corresponding r
af60: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 esult column as
af70: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d obtained.** from
af80: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e [sqlite3_column
af90: 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 _name()]..**.**
afa0: 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 ^If the 2nd para
afb0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
afc0: 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c _exec() is a NUL
afd0: 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 L pointer, a poi
afe0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d nter.** to an em
aff0: 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 pty string, or a
b000: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f pointer that co
b010: 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 ntains only whit
b020: 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a espace and/or .*
b030: 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 * SQL comments,
b040: 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 then no SQL stat
b050: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 ements are evalu
b060: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 ated and the dat
b070: 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 abase.** is not
b080: 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 changed..**.** R
b090: 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a estrictions:.**.
b0a0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
b0b0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
b0c0: 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 must ensure that
b0d0: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 the 1st paramet
b0e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 er to sqlite3_ex
b0f0: 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 ec().** is
b100: 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e a valid and open
b110: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
b120: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 ction]..** <li>
b130: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 The application
b140: 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 must not close t
b150: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
b160: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 nection] specifi
b170: 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 ed by.** th
b180: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 e 1st parameter
b190: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 to sqlite3_exec(
b1a0: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f ) while sqlite3_
b1b0: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e exec() is runnin
b1c0: 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 g..** <li> The a
b1d0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 pplication must
b1e0: 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 not modify the S
b1f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 QL statement tex
b200: 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a t passed into.**
b210: 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 the 2nd pa
b220: 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 rameter of sqlit
b230: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 e3_exec() while
b240: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 sqlite3_exec() i
b250: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f s running..** </
b260: 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ul>.*/.SQLITE_AP
b270: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 I int sqlite3_ex
b280: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 ec(. sqlite3*,
b290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b2a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b2b0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 /* An open data
b2c0: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 base */. const
b2d0: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 char *sql,
b2e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b2f0: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 /* SQL to b
b300: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 e evaluated */.
b310: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 int (*callback)
b320: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a (void*,int,char*
b330: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 *,char**), /* C
b340: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e allback function
b350: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 */. void *,
b360: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b380: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 /* 1st argument
b390: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a to callback */.
b3a0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 char **errmsg
b3b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 /*
b3d0: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 Error msg writte
b3e0: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a n here */.);../*
b3f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 .** CAPI3REF: Re
b400: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 sult Codes.** KE
b410: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 YWORDS: {result
b420: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 code definitions
b430: 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c }.**.** Many SQL
b440: 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 ite functions re
b450: 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 turn an integer
b460: 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d result code from
b470: 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a the set shown.*
b480: 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 * here in order
b490: 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 to indicate succ
b4a0: 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a ess or failure..
b4b0: 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 **.** New error
b4c0: 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 codes may be add
b4d0: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 ed in future ver
b4e0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e sions of SQLite.
b4f0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
b500: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c [extended resul
b510: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f t code definitio
b520: 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ns].*/.#define S
b530: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 QLITE_OK
b540: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 0 /* Succes
b550: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f sful result */./
b560: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 * beginning-of-e
b570: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 rror-codes */.#d
b580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 efine SQLITE_ERR
b590: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a OR 1 /*
b5a0: 20 47 65 6e 65 72 69 63 20 65 72 72 6f 72 20 2a Generic error *
b5b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
b5c0: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 _INTERNAL 2
b5d0: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f /* Internal lo
b5e0: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c gic error in SQL
b5f0: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ite */.#define S
b600: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 QLITE_PERM
b610: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 3 /* Access
b620: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 permission deni
b630: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
b640: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 LITE_ABORT
b650: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 4 /* Callbac
b660: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 k routine reques
b670: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a ted an abort */.
b680: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 #define SQLITE_B
b690: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 USY 5
b6a0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 /* The database
b6b0: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a file is locked *
b6c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
b6d0: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 _LOCKED 6
b6e0: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 /* A table in
b6f0: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 the database is
b700: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e locked */.#defin
b710: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 e SQLITE_NOMEM
b720: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 7 /* A m
b730: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a alloc() failed *
b740: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
b750: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 _READONLY 8
b760: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 /* Attempt to
b770: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 write a readonly
b780: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 database */.#de
b790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 fine SQLITE_INTE
b7a0: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 RRUPT 9 /*
b7b0: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e Operation termin
b7c0: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f ated by sqlite3_
b7d0: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 interrupt()*/.#d
b7e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
b7f0: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a RR 10 /*
b800: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 Some kind of di
b810: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 sk I/O error occ
b820: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 urred */.#define
b830: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 SQLITE_CORRUPT
b840: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 11 /* The
b850: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d database disk im
b860: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 age is malformed
b870: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
b880: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 TE_NOTFOUND 1
b890: 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 2 /* Unknown o
b8a0: 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 pcode in sqlite3
b8b0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 _file_control()
b8c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
b8d0: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 E_FULL 13
b8e0: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 /* Insertion
b8f0: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 failed because d
b900: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 atabase is full
b910: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
b920: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 E_CANTOPEN 14
b930: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 /* Unable to
b940: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 open the databas
b950: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e e file */.#defin
b960: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f e SQLITE_PROTOCO
b970: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 L 15 /* Dat
b980: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f abase lock proto
b990: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 col error */.#de
b9a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 fine SQLITE_EMPT
b9b0: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 Y 16 /*
b9c0: 49 6e 74 65 72 6e 61 6c 20 75 73 65 20 6f 6e 6c Internal use onl
b9d0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
b9e0: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 ITE_SCHEMA
b9f0: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 17 /* The data
ba00: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e base schema chan
ba10: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ged */.#define S
ba20: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 QLITE_TOOBIG
ba30: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 18 /* String
ba40: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 or BLOB exceeds
ba50: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 size limit */.#
ba60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
ba70: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f NSTRAINT 19 /
ba80: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 * Abort due to c
ba90: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 onstraint violat
baa0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ion */.#define S
bab0: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 QLITE_MISMATCH
bac0: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 20 /* Data t
bad0: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a ype mismatch */.
bae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d #define SQLITE_M
baf0: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 ISUSE 21
bb00: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 /* Library used
bb10: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 incorrectly */.#
bb20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
bb30: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f LFS 22 /
bb40: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 * Uses OS featur
bb50: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 es not supported
bb60: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 on host */.#def
bb70: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 ine SQLITE_AUTH
bb80: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 23 /* A
bb90: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e uthorization den
bba0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ied */.#define S
bbb0: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 QLITE_FORMAT
bbc0: 20 20 32 34 20 20 20 2f 2a 20 4e 6f 74 20 75 73 24 /* Not us
bbd0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
bbe0: 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 LITE_RANGE
bbf0: 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 25 /* 2nd par
bc00: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
bc10: 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 3_bind out of ra
bc20: 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nge */.#define S
bc30: 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 QLITE_NOTADB
bc40: 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 26 /* File o
bc50: 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f pened that is no
bc60: 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c t a database fil
bc70: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
bc80: 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 ITE_NOTICE
bc90: 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 27 /* Notifica
bca0: 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 tions from sqlit
bcb0: 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 e3_log() */.#def
bcc0: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 ine SQLITE_WARNI
bcd0: 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 NG 28 /* W
bce0: 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c arnings from sql
bcf0: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 ite3_log() */.#d
bd00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 efine SQLITE_ROW
bd10: 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 100 /*
bd20: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 sqlite3_step()
bd30: 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 has another row
bd40: 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 ready */.#define
bd50: 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 SQLITE_DONE
bd60: 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 101 /* sqli
bd70: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 te3_step() has f
bd80: 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e inished executin
bd90: 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 g */./* end-of-e
bda0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f rror-codes */../
bdb0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 *.** CAPI3REF: E
bdc0: 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
bdd0: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 odes.** KEYWORDS
bde0: 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 : {extended resu
bdf0: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 lt code definiti
be00: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 ons}.**.** In it
be10: 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 s default config
be20: 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 uration, SQLite
be30: 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 API routines ret
be40: 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e urn one of 30 in
be50: 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 teger.** [result
be60: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 codes]. Howeve
be70: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 r, experience ha
be80: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e s shown that man
be90: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 y of.** these re
bea0: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 sult codes are t
beb0: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 oo coarse-graine
bec0: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 d. They do not
bed0: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 provide as.** mu
bee0: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 ch information a
bef0: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 bout problems as
bf00: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 programmers mig
bf10: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 ht like. In an
bf20: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 effort to.** add
bf30: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 ress this, newer
bf40: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c versions of SQL
bf50: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 ite (version 3.3
bf60: 2e 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 2e 38 .8 [dateof:3.3.8
bf70: 5d 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 29 20 ].** and later)
bf80: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f include.** suppo
bf90: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 rt for additiona
bfa0: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 l result codes t
bfb0: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 hat provide more
bfc0: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d detailed inform
bfd0: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 ation.** about e
bfe0: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78 rrors. These [ex
bff0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f tended result co
c000: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 des] are enabled
c010: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 or disabled.**
c020: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 on a per databas
c030: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 e connection bas
c040: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 is using the.**
c050: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 [sqlite3_extende
c060: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 d_result_codes()
c070: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 ] API. Or, the
c080: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f extended code fo
c090: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 r.** the most re
c0a0: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62 cent error can b
c0b0: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67 e obtained using
c0c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 .** [sqlite3_ext
c0d0: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d ended_errcode()]
c0e0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
c0f0: 49 54 45 5f 45 52 52 4f 52 5f 4d 49 53 53 49 4e ITE_ERROR_MISSIN
c100: 47 5f 43 4f 4c 4c 53 45 51 20 20 20 28 53 51 4c G_COLLSEQ (SQL
c110: 49 54 45 5f 45 52 52 4f 52 20 7c 20 28 31 3c 3c ITE_ERROR | (1<<
c120: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
c130: 54 45 5f 45 52 52 4f 52 5f 52 45 54 52 59 20 20 TE_ERROR_RETRY
c140: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 (SQLI
c150: 54 45 5f 45 52 52 4f 52 20 7c 20 28 32 3c 3c 38 TE_ERROR | (2<<8
c160: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
c170: 45 5f 45 52 52 4f 52 5f 53 4e 41 50 53 48 4f 54 E_ERROR_SNAPSHOT
c180: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
c190: 45 5f 45 52 52 4f 52 20 7c 20 28 33 3c 3c 38 29 E_ERROR | (3<<8)
c1a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
c1b0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 _IOERR_READ
c1c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
c1d0: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 _IOERR | (1<<8))
c1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c1f0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 IOERR_SHORT_READ
c200: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
c210: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a IOERR | (2<<8)).
c220: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c230: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 OERR_WRITE
c240: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c250: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 OERR | (3<<8)).#
c260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
c270: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 ERR_FSYNC
c280: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f (SQLITE_IO
c290: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 ERR | (4<<8)).#d
c2a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 efine SQLITE_IOE
c2b0: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 RR_DIR_FSYNC
c2c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 (SQLITE_IOE
c2d0: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 RR | (5<<8)).#de
c2e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 fine SQLITE_IOER
c2f0: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 R_TRUNCATE
c300: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 (SQLITE_IOER
c310: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 R | (6<<8)).#def
c320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 ine SQLITE_IOERR
c330: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 _FSTAT
c340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 (SQLITE_IOERR
c350: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 | (7<<8)).#defi
c360: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f ne SQLITE_IOERR_
c370: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 UNLOCK
c380: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 (SQLITE_IOERR
c390: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (8<<8)).#defin
c3a0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 e SQLITE_IOERR_R
c3b0: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 DLOCK
c3c0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c (SQLITE_IOERR |
c3d0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (9<<8)).#define
c3e0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 SQLITE_IOERR_DE
c3f0: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 LETE
c400: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c410: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (10<<8)).#define
c420: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c SQLITE_IOERR_BL
c430: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 OCKED
c440: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c450: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (11<<8)).#define
c460: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f SQLITE_IOERR_NO
c470: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 MEM
c480: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c490: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (12<<8)).#define
c4a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 SQLITE_IOERR_AC
c4b0: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 CESS
c4c0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c4d0: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (13<<8)).#define
c4e0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 SQLITE_IOERR_CH
c4f0: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 ECKRESERVEDLOCK
c500: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c510: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (14<<8)).#define
c520: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f SQLITE_IOERR_LO
c530: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CK
c540: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c550: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (15<<8)).#define
c560: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c SQLITE_IOERR_CL
c570: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 OSE
c580: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c590: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (16<<8)).#define
c5a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 SQLITE_IOERR_DI
c5b0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 R_CLOSE
c5c0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c5d0: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (17<<8)).#define
c5e0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
c5f0: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 MOPEN
c600: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c610: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (18<<8)).#define
c620: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
c630: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 MSIZE
c640: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c650: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (19<<8)).#define
c660: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
c670: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 MLOCK
c680: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c690: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (20<<8)).#define
c6a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 SQLITE_IOERR_SH
c6b0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 MMAP
c6c0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c6d0: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (21<<8)).#define
c6e0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 SQLITE_IOERR_SE
c6f0: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 EK
c700: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c710: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (22<<8)).#define
c720: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 SQLITE_IOERR_DE
c730: 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 LETE_NOENT
c740: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c750: 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (23<<8)).#define
c760: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d SQLITE_IOERR_MM
c770: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AP
c780: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c790: 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (24<<8)).#define
c7a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 SQLITE_IOERR_GE
c7b0: 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 TTEMPPATH
c7c0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c7d0: 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (25<<8)).#define
c7e0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f SQLITE_IOERR_CO
c7f0: 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20 NVPATH
c800: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c810: 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (26<<8)).#define
c820: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e SQLITE_IOERR_VN
c830: 4f 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ODE
c840: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c850: 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (27<<8)).#define
c860: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55 SQLITE_IOERR_AU
c870: 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 TH
c880: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c890: 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (28<<8)).#define
c8a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 45 SQLITE_IOERR_BE
c8b0: 47 49 4e 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 GIN_ATOMIC
c8c0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c8d0: 28 32 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (29<<8)).#define
c8e0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f SQLITE_IOERR_CO
c8f0: 4d 4d 49 54 5f 41 54 4f 4d 49 43 20 20 20 20 20 MMIT_ATOMIC
c900: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c910: 28 33 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (30<<8)).#define
c920: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 4f SQLITE_IOERR_RO
c930: 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 20 20 20 LLBACK_ATOMIC
c940: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c950: 28 33 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (31<<8)).#define
c960: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 SQLITE_LOCKED_S
c970: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 HAREDCACHE
c980: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c (SQLITE_LOCKED |
c990: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e (1<<8)).#defin
c9a0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f e SQLITE_LOCKED_
c9b0: 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 VTAB
c9c0: 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 (SQLITE_LOCKED
c9d0: 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
c9e0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 ne SQLITE_BUSY_R
c9f0: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 ECOVERY
ca00: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 (SQLITE_BUSY
ca10: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 | (1<<8)).#def
ca20: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f ine SQLITE_BUSY_
ca30: 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 SNAPSHOT
ca40: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 (SQLITE_BUSY
ca50: 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 | (2<<8)).#de
ca60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 fine SQLITE_CANT
ca70: 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 OPEN_NOTEMPDIR
ca80: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 (SQLITE_CANT
ca90: 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 OPEN | (1<<8)).#
caa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 define SQLITE_CA
cab0: 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 NTOPEN_ISDIR
cac0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 (SQLITE_CA
cad0: 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 NTOPEN | (2<<8))
cae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
caf0: 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 CANTOPEN_FULLPAT
cb00: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f H (SQLITE_
cb10: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 CANTOPEN | (3<<8
cb20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
cb30: 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 E_CANTOPEN_CONVP
cb40: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 ATH (SQLIT
cb50: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c E_CANTOPEN | (4<
cb60: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
cb70: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 44 49 52 ITE_CANTOPEN_DIR
cb80: 54 59 57 41 4c 20 20 20 20 20 20 20 28 53 51 4c TYWAL (SQL
cb90: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
cba0: 35 3c 3c 38 29 29 20 2f 2a 20 4e 6f 74 20 55 73 5<<8)) /* Not Us
cbb0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ed */.#define SQ
cbc0: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 LITE_CORRUPT_VTA
cbd0: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 B (SQ
cbe0: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 LITE_CORRUPT | (
cbf0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
cc00: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 53 45 QLITE_CORRUPT_SE
cc10: 51 55 45 4e 43 45 20 20 20 20 20 20 20 20 28 53 QUENCE (S
cc20: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 QLITE_CORRUPT |
cc30: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (2<<8)).#define
cc40: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f SQLITE_READONLY_
cc50: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 RECOVERY (
cc60: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
cc70: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
cc80: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c e SQLITE_READONL
cc90: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 Y_CANTLOCK
cca0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c (SQLITE_READONL
ccb0: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 Y | (2<<8)).#def
ccc0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
ccd0: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 NLY_ROLLBACK
cce0: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
ccf0: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 NLY | (3<<8)).#d
cd00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
cd10: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 DONLY_DBMOVED
cd20: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
cd30: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a DONLY | (4<<8)).
cd40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
cd50: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 49 4e 49 54 EADONLY_CANTINIT
cd60: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 (SQLITE_R
cd70: 45 41 44 4f 4e 4c 59 20 7c 20 28 35 3c 3c 38 29 EADONLY | (5<<8)
cd80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
cd90: 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 52 45 43 54 _READONLY_DIRECT
cda0: 4f 52 59 20 20 20 20 20 20 28 53 51 4c 49 54 45 ORY (SQLITE
cdb0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 36 3c 3c _READONLY | (6<<
cdc0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
cdd0: 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 TE_ABORT_ROLLBAC
cde0: 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 K (SQLI
cdf0: 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 TE_ABORT | (2<<8
ce00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
ce10: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 E_CONSTRAINT_CHE
ce20: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 CK (SQLIT
ce30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
ce40: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 1<<8)).#define S
ce50: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
ce60: 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 _COMMITHOOK (S
ce70: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
ce80: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
ce90: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
cea0: 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 AINT_FOREIGNKEY
ceb0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
cec0: 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 AINT | (3<<8)).#
ced0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
cee0: 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f NSTRAINT_FUNCTIO
cef0: 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f N (SQLITE_CO
cf00: 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 NSTRAINT | (4<<8
cf10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
cf20: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 E_CONSTRAINT_NOT
cf30: 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 NULL (SQLIT
cf40: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
cf50: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 5<<8)).#define S
cf60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
cf70: 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 _PRIMARYKEY (S
cf80: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
cf90: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 | (6<<8)).#defi
cfa0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
cfb0: 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 AINT_TRIGGER
cfc0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
cfd0: 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 AINT | (7<<8)).#
cfe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
cff0: 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 NSTRAINT_UNIQUE
d000: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
d010: 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 NSTRAINT | (8<<8
d020: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
d030: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 E_CONSTRAINT_VTA
d040: 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 B (SQLIT
d050: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
d060: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 9<<8)).#define S
d070: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
d080: 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 _ROWID (S
d090: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
d0a0: 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 |(10<<8)).#defi
d0b0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
d0c0: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 _RECOVER_WAL
d0d0: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 (SQLITE_NOTICE
d0e0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
d0f0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
d100: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 _RECOVER_ROLLBAC
d110: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 K (SQLITE_NOTICE
d120: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 | (2<<8)).#defi
d130: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e ne SQLITE_WARNIN
d140: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 G_AUTOINDEX
d150: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e (SQLITE_WARNIN
d160: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 G | (1<<8)).#def
d170: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f ine SQLITE_AUTH_
d180: 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20 USER
d190: 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 (SQLITE_AUTH
d1a0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
d1b0: 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 e SQLITE_OK_LOAD
d1c0: 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 _PERMANENTLY
d1d0: 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 (SQLITE_OK | (1
d1e0: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 <<8))../*.** CAP
d1f0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 I3REF: Flags For
d200: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 File Open Opera
d210: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 tions.**.** Thes
d220: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 e bit values are
d230: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 intended for us
d240: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 e in the.** 3rd
d250: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
d260: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
d270: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 2()] interface a
d280: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 nd.** in the 4th
d290: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
d2a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 e [sqlite3_vfs.x
d2b0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f Open] method..*/
d2c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d2d0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 OPEN_READONLY
d2e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0x00000001
d2f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
d300: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
d310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d320: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 OPEN_READWRITE
d330: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0x00000002
d340: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
d350: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
d360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d370: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 OPEN_CREATE
d380: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0x00000004
d390: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
d3a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
d3b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d3c0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f OPEN_DELETEONCLO
d3d0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 SE 0x00000008
d3e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
d3f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d400: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 OPEN_EXCLUSIVE
d410: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0x00000010
d420: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
d430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d440: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 OPEN_AUTOPROXY
d450: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0x00000020
d460: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
d470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d480: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 OPEN_URI
d490: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0x00000040
d4a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
d4b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
d4c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d4d0: 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 OPEN_MEMORY
d4e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0x00000080
d4f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
d500: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
d510: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d520: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 OPEN_MAIN_DB
d530: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0x00000100
d540: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
d550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d560: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 OPEN_TEMP_DB
d570: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0x00000200
d580: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
d590: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d5a0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 OPEN_TRANSIENT_D
d5b0: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 B 0x00000400
d5c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
d5d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d5e0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 OPEN_MAIN_JOURNA
d5f0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 L 0x00000800
d600: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
d610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d620: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 OPEN_TEMP_JOURNA
d630: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 L 0x00001000
d640: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
d650: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d660: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 OPEN_SUBJOURNAL
d670: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0x00002000
d680: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
d690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d6a0: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 OPEN_MASTER_JOUR
d6b0: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 NAL 0x00004000
d6c0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
d6d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d6e0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 OPEN_NOMUTEX
d6f0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 0x00008000
d700: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
d710: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
d720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d730: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 OPEN_FULLMUTEX
d740: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 0x00010000
d750: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
d760: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
d770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d780: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
d790: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 0x00020000
d7a0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
d7b0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
d7c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d7d0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 OPEN_PRIVATECACH
d7e0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 E 0x00040000
d7f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 /* Ok for sqli
d800: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f te3_open_v2() */
d810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
d820: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 OPEN_WAL
d830: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 0x00080000
d840: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f /* VFS only */
d850: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 ../* Reserved:
d860: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
d870: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 0x00F0000
d880: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 0 */../*.** CAPI
d890: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 3REF: Device Cha
d8a0: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a racteristics.**.
d8b0: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 ** The xDeviceCh
d8c0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 aracteristics me
d8d0: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c thod of the [sql
d8e0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d ite3_io_methods]
d8f0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 .** object retur
d900: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 ns an integer wh
d910: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 ich is a vector
d920: 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 of these.** bit
d930: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e values expressin
d940: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 g I/O characteri
d950: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 stics of the mas
d960: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 s storage.** dev
d970: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 ice that holds t
d980: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 he file that the
d990: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
d9a0: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 hods].** refers
d9b0: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 to..**.** The SQ
d9c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
d9d0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 C property means
d9e0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 that all writes
d9f0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 of.** any size
da00: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
da10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
da20: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a OMICnnn values.*
da30: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 * mean that writ
da40: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 es of blocks tha
da50: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 t are nnn bytes
da60: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 in size and.** a
da70: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e re aligned to an
da80: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 address which i
da90: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c s an integer mul
daa0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 tiple of.** nnn
dab0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 are atomic. The
dac0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 SQLITE_IOCAP_SA
dad0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 FE_APPEND value
dae0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 means.** that wh
daf0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e en data is appen
db00: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 ded to a file, t
db10: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e he data is appen
db20: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 ded.** first the
db30: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 n the size of th
db40: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 e file is extend
db50: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 ed, never the ot
db60: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e her.** way aroun
db70: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 d. The SQLITE_I
db80: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 OCAP_SEQUENTIAL
db90: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 property means t
dba0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 hat.** informati
dbb0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f on is written to
dbc0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d disk in the sam
dbd0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 e order as calls
dbe0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e .** to xWrite().
dbf0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 The SQLITE_IOC
dc00: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 AP_POWERSAFE_OVE
dc10: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 RWRITE property
dc20: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 means that.** af
dc30: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f ter reboot follo
dc40: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 wing a crash or
dc50: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 power loss, the
dc60: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a only bytes in a.
dc70: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 ** file that wer
dc80: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 e written at the
dc90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 application lev
dca0: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 el might have ch
dcb0: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 anged.** and tha
dcc0: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 t adjacent bytes
dcd0: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 , even bytes wit
dce0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 hin the same sec
dcf0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 tor are.** guara
dd00: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 nteed to be unch
dd10: 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 anged. The SQLI
dd20: 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 TE_IOCAP_UNDELET
dd30: 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a ABLE_WHEN_OPEN.*
dd40: 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 * flag indicates
dd50: 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e that a file can
dd60: 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 not be deleted w
dd70: 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a hen open. The.*
dd80: 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 * SQLITE_IOCAP_I
dd90: 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e MMUTABLE flag in
dda0: 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68 65 dicates that the
ddb0: 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 file is on.** r
ddc0: 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 ead-only media a
ddd0: 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 nd cannot be cha
dde0: 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f nged even by pro
ddf0: 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 cesses with.** e
de00: 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 levated privileg
de10: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 es..**.** The SQ
de20: 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 LITE_IOCAP_BATCH
de30: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 _ATOMIC property
de40: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 means that the
de50: 75 6e 64 65 72 6c 79 69 6e 67 0a 2a 2a 20 66 69 underlying.** fi
de60: 6c 65 73 79 73 74 65 6d 20 73 75 70 70 6f 72 74 lesystem support
de70: 73 20 64 6f 69 6e 67 20 6d 75 6c 74 69 70 6c 65 s doing multiple
de80: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e write operation
de90: 73 20 61 74 6f 6d 69 63 61 6c 6c 79 20 77 68 65 s atomically whe
dea0: 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 72 69 74 65 n those.** write
deb0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 operations are
dec0: 62 72 61 63 6b 65 74 65 64 20 62 79 20 5b 53 51 bracketed by [SQ
ded0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e LITE_FCNTL_BEGIN
dee0: 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 61 _ATOMIC_WRITE] a
def0: 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 nd.** [SQLITE_FC
df00: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 NTL_COMMIT_ATOMI
df10: 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f 0a 23 64 65 C_WRITE]..*/.#de
df20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
df30: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 P_ATOMIC
df40: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
df50: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 001.#define SQLI
df60: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 TE_IOCAP_ATOMIC5
df70: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 12
df80: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 0x00000002.#defi
df90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
dfa0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 ATOMIC1K
dfb0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 0x0000000
dfc0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
dfd0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 _IOCAP_ATOMIC2K
dfe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
dff0: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 00000008.#define
e000: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
e010: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 OMIC4K
e020: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 0x00000010.
e030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
e040: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 OCAP_ATOMIC8K
e050: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
e060: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 000020.#define S
e070: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
e080: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 IC16K
e090: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 0x00000040.#d
e0a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
e0b0: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 AP_ATOMIC32K
e0c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
e0d0: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0080.#define SQL
e0e0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
e0f0: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 64K
e100: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 0x00000100.#def
e110: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
e120: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 _SAFE_APPEND
e130: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 0x000002
e140: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
e150: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 E_IOCAP_SEQUENTI
e160: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 AL 0
e170: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e x00000400.#defin
e180: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 e SQLITE_IOCAP_U
e190: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f NDELETABLE_WHEN_
e1a0: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 OPEN 0x00000800
e1b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
e1c0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f IOCAP_POWERSAFE_
e1d0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 OVERWRITE 0x0
e1e0: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 0001000.#define
e1f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d SQLITE_IOCAP_IMM
e200: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 UTABLE
e210: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 23 0x00002000.#
e220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
e230: 43 41 50 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 CAP_BATCH_ATOMIC
e240: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
e250: 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 04000../*.** CAP
e260: 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b I3REF: File Lock
e270: 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a ing Levels.**.**
e280: 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 SQLite uses one
e290: 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 of these intege
e2a0: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 r values as the
e2b0: 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 second.** argume
e2c0: 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d nt to calls it m
e2d0: 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 akes to the xLoc
e2e0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 k() and xUnlock(
e2f0: 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 ) methods.** of
e300: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d an [sqlite3_io_m
e310: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a ethods] object..
e320: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
e330: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 E_LOCK_NONE
e340: 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 0.#define S
e350: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
e360: 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 D 1.#defi
e370: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 ne SQLITE_LOCK_R
e380: 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 ESERVED 2.#
e390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
e3a0: 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 CK_PENDING
e3b0: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 3.#define SQLIT
e3c0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 E_LOCK_EXCLUSIVE
e3d0: 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 4../*.** CA
e3e0: 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e PI3REF: Synchron
e3f0: 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 ization Type Fla
e400: 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 gs.**.** When SQ
e410: 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 Lite invokes the
e420: 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 xSync() method
e430: 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 of an.** [sqlite
e440: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 3_io_methods] ob
e450: 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 ject it uses a c
e460: 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a ombination of.**
e470: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 these integer v
e480: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 alues as the sec
e490: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a ond argument..**
e4a0: 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c .** When the SQL
e4b0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c ITE_SYNC_DATAONL
e4c0: 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 Y flag is used,
e4d0: 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 it means that th
e4e0: 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 e.** sync operat
e4f0: 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 ion only needs t
e500: 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 o flush data to
e510: 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 mass storage. I
e520: 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 node.** informat
e530: 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 ion need not be
e540: 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 flushed. If the
e550: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 lower four bits
e560: 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 of the flag.** e
e570: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 qual SQLITE_SYNC
e580: 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 _NORMAL, that me
e590: 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 ans to use norma
e5a0: 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 l fsync() semant
e5b0: 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c ics..** If the l
e5c0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 ower four bits e
e5d0: 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 qual SQLITE_SYNC
e5e0: 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e _FULL, that mean
e5f0: 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 s.** to use Mac
e600: 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 OS X style fulls
e610: 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 ync instead of f
e620: 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f sync()..**.** Do
e630: 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 not confuse the
e640: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 SQLITE_SYNC_NOR
e650: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 MAL and SQLITE_S
e660: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a YNC_FULL flags.*
e670: 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 * with the [PRAG
e680: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d MA synchronous]=
e690: 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 NORMAL and [PRAG
e6a0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d MA synchronous]=
e6b0: 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 FULL.** settings
e6c0: 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e . The [synchron
e6d0: 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 ous pragma] dete
e6e0: 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c rmines when call
e6f0: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e s to the.** xSyn
e700: 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 c VFS method occ
e710: 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 ur and applies u
e720: 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 niformly across
e730: 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a all platforms..*
e740: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e * The SQLITE_SYN
e750: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c C_NORMAL and SQL
e760: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c ITE_SYNC_FULL fl
e770: 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f ags determine ho
e780: 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f w.** energetic o
e790: 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f r rigorous or fo
e7a0: 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 rceful the sync
e7b0: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 operations are a
e7c0: 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 nd.** only make
e7d0: 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 a difference on
e7e0: 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 Mac OSX for the
e7f0: 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 default SQLite c
e800: 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 ode..** (Third-p
e810: 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 arty VFS impleme
e820: 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 ntations might a
e830: 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 lso make the dis
e840: 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 tinction.** betw
e850: 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f een SQLITE_SYNC_
e860: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 NORMAL and SQLIT
e870: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 E_SYNC_FULL, but
e880: 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 among the.** op
e890: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 erating systems
e8a0: 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 natively support
e8b0: 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e ed by SQLite, on
e8c0: 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 ly Mac OSX.** ca
e8d0: 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 res about the di
e8e0: 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 fference.).*/.#d
e8f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e efine SQLITE_SYN
e900: 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 C_NORMAL
e910: 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 0x00002.#define
e920: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c SQLITE_SYNC_FULL
e930: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
e940: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
e950: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 _SYNC_DATAONLY
e960: 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 0x00010../*.
e970: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
e980: 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 Interface Open F
e990: 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a ile Handle.**.**
e9a0: 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c An [sqlite3_fil
e9b0: 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 e] object repres
e9c0: 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c ents an open fil
e9d0: 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 e in the .** [sq
e9e0: 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 lite3_vfs | OS i
e9f0: 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e nterface layer].
ea00: 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 Individual OS
ea10: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 interface.** imp
ea20: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c lementations wil
ea30: 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 l.** want to sub
ea40: 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 class this objec
ea50: 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 t by appending a
ea60: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 dditional fields
ea70: 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 .** for their ow
ea80: 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 n use. The pMet
ea90: 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 hods entry is a
eaa0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a pointer to an.**
eab0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
eac0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 hods] object tha
ead0: 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 t defines method
eae0: 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 s for performing
eaf0: 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f .** I/O operatio
eb00: 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 ns on the open f
eb10: 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ile..*/.typedef
eb20: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 struct sqlite3_f
eb30: 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 ile sqlite3_file
eb40: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 ;.struct sqlite3
eb50: 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 _file {. const
eb60: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
eb70: 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 o_methods *pMeth
eb80: 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 ods; /* Methods
eb90: 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c for an open fil
eba0: 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 e */.};../*.** C
ebb0: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 API3REF: OS Inte
ebc0: 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 rface File Virtu
ebd0: 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 al Methods Objec
ebe0: 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 t.**.** Every fi
ebf0: 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 le opened by the
ec00: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f [sqlite3_vfs.xO
ec10: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 pen] method popu
ec20: 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c lates an.** [sql
ec30: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 ite3_file] objec
ec40: 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d t (or, more comm
ec50: 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 only, a subclass
ec60: 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 of the.** [sqli
ec70: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
ec80: 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 ) with a pointer
ec90: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
eca0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a of this object..
ecb0: 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 ** This object d
ecc0: 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f efines the metho
ecd0: 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f ds used to perfo
ece0: 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 rm various opera
ecf0: 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 tions.** against
ed00: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 the open file r
ed10: 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 epresented by th
ed20: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
ed30: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 object..**.** I
ed40: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 f the [sqlite3_v
ed50: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 fs.xOpen] method
ed60: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 sets the sqlite
ed70: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 3_file.pMethods
ed80: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 element .** to a
ed90: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 non-NULL pointe
eda0: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 r, then the sqli
edb0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 te3_io_methods.x
edc0: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 Close method.**
edd0: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 may be invoked e
ede0: 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 ven if the [sqli
edf0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 te3_vfs.xOpen] r
ee00: 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 eported that it
ee10: 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 failed. The.**
ee20: 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 only way to prev
ee30: 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 ent a call to xC
ee40: 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 lose following a
ee50: 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 failed [sqlite3
ee60: 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 _vfs.xOpen].** i
ee70: 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 s for the [sqlit
ee80: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f e3_vfs.xOpen] to
ee90: 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 set the sqlite3
eea0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 _file.pMethods e
eeb0: 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c lement.** to NUL
eec0: 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 L..**.** The fla
eed0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 gs argument to x
eee0: 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 Sync may be one
eef0: 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f of [SQLITE_SYNC_
ef00: 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 NORMAL] or.** [S
ef10: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d QLITE_SYNC_FULL]
ef20: 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f . The first cho
ef30: 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 ice is the norma
ef40: 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 l fsync()..** Th
ef50: 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 e second choice
ef60: 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 is a Mac OS X st
ef70: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 yle fullsync. T
ef80: 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f he [SQLITE_SYNC_
ef90: 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 DATAONLY].** fla
efa0: 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e g may be ORed in
efb0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 to indicate tha
efc0: 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 t only the data
efd0: 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 of the file.** a
efe0: 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 nd not its inode
eff0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e needs to be syn
f000: 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 ced..**.** The i
f010: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f nteger values to
f020: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e xLock() and xUn
f030: 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f lock() are one o
f040: 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 f.** <ul>.** <li
f050: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e > [SQLITE_LOCK_N
f060: 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ONE],.** <li> [S
f070: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 QLITE_LOCK_SHARE
f080: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
f090: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
f0a0: 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c D],.** <li> [SQL
f0b0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 ITE_LOCK_PENDING
f0c0: 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ], or.** <li> [S
f0d0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
f0e0: 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a SIVE]..** </ul>.
f0f0: 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 ** xLock() incre
f100: 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 ases the lock. x
f110: 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 Unlock() decreas
f120: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 es the lock..**
f130: 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 The xCheckReserv
f140: 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 edLock() method
f150: 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 checks whether a
f160: 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ny database conn
f170: 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 ection,.** eithe
f180: 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 r in this proces
f190: 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 s or in some oth
f1a0: 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 er process, is h
f1b0: 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 olding a RESERVE
f1c0: 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f D,.** PENDING, o
f1d0: 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b r EXCLUSIVE lock
f1e0: 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 on the file. I
f1f0: 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a t returns true.*
f200: 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b * if such a lock
f210: 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 exists and fals
f220: 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a e otherwise..**.
f230: 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 ** The xFileCont
f240: 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 rol() method is
f250: 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 a generic interf
f260: 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 ace that allows
f270: 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d custom.** VFS im
f280: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f plementations to
f290: 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f directly contro
f2a0: 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 l an open file u
f2b0: 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c sing the.** [sql
f2c0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
f2d0: 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 l()] interface.
f2e0: 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 The second "op"
f2f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a argument is an.
f300: 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 ** integer opcod
f310: 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 e. The third ar
f320: 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 gument is a gene
f330: 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 ric pointer inte
f340: 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 nded to.** point
f350: 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 to a structure
f360: 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e that may contain
f370: 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 arguments or sp
f380: 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a ace in which to.
f390: 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 ** write return
f3a0: 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 values. Potenti
f3b0: 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c al uses for xFil
f3c0: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 eControl() might
f3d0: 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 be.** functions
f3e0: 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b to enable block
f3f0: 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 ing locks with t
f400: 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e imeouts, to chan
f410: 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e ge the.** lockin
f420: 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 g strategy (for
f430: 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 example to use d
f440: 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 ot-file locks),
f450: 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 to inquire.** ab
f460: 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f out the status o
f470: 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 f a lock, or to
f480: 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b break stale lock
f490: 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a s. The SQLite.*
f4a0: 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 * core reserves
f4b0: 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 all opcodes less
f4c0: 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 than 100 for it
f4d0: 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 s own use..** A
f4e0: 5b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 [file control op
f4f0: 63 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 codes | list of
f500: 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 opcodes] less th
f510: 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 an 100 is availa
f520: 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 ble..** Applicat
f530: 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 ions that define
f540: 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 a custom xFileC
f550: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 ontrol method sh
f560: 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 ould use opcodes
f570: 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e .** greater than
f580: 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 100 to avoid co
f590: 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d nflicts. VFS im
f5a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
f5b0: 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b ould.** return [
f5c0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d SQLITE_NOTFOUND]
f5d0: 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f for file contro
f5e0: 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 l opcodes that t
f5f0: 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 hey do not.** re
f600: 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 cognize..**.** T
f610: 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 he xSectorSize()
f620: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 method returns
f630: 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 the sector size
f640: 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 of the.** device
f650: 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 that underlies
f660: 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 the file. The s
f670: 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 ector size is th
f680: 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 e.** minimum wri
f690: 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 te that can be p
f6a0: 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 erformed without
f6b0: 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f disturbing.** o
f6c0: 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 ther bytes in th
f6d0: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 e file. The xDe
f6e0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 viceCharacterist
f6f0: 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 ics().** method
f700: 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 returns a bit ve
f710: 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 ctor describing
f720: 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 behaviors of the
f730: 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 .** underlying d
f740: 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c evice:.**.** <ul
f750: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 >.** <li> [SQLIT
f760: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a E_IOCAP_ATOMIC].
f770: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f ** <li> [SQLITE_
f780: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d IOCAP_ATOMIC512]
f790: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
f7a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d _IOCAP_ATOMIC1K]
f7b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
f7c0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d _IOCAP_ATOMIC2K]
f7d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
f7e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d _IOCAP_ATOMIC4K]
f7f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
f800: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d _IOCAP_ATOMIC8K]
f810: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
f820: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b _IOCAP_ATOMIC16K
f830: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
f840: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 E_IOCAP_ATOMIC32
f850: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 K].** <li> [SQLI
f860: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 TE_IOCAP_ATOMIC6
f870: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 4K].** <li> [SQL
f880: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 ITE_IOCAP_SAFE_A
f890: 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b PPEND].** <li> [
f8a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 SQLITE_IOCAP_SEQ
f8b0: 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e UENTIAL].** <li>
f8c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 [SQLITE_IOCAP_U
f8d0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f NDELETABLE_WHEN_
f8e0: 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 OPEN].** <li> [S
f8f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
f900: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d RSAFE_OVERWRITE]
f910: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 .** <li> [SQLITE
f920: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 _IOCAP_IMMUTABLE
f930: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 ].** <li> [SQLIT
f940: 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 E_IOCAP_BATCH_AT
f950: 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a OMIC].** </ul>.*
f960: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f *.** The SQLITE_
f970: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f IOCAP_ATOMIC pro
f980: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 perty means that
f990: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a all writes of.*
f9a0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 * any size are a
f9b0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
f9c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e TE_IOCAP_ATOMICn
f9d0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 nn values.** mea
f9e0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 n that writes of
f9f0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 blocks that are
fa00: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 nnn bytes in si
fa10: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c ze and.** are al
fa20: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 igned to an addr
fa30: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 ess which is an
fa40: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 integer multiple
fa50: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 of.** nnn are a
fa60: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 tomic. The SQLI
fa70: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 TE_IOCAP_SAFE_AP
fa80: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 PEND value means
fa90: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 .** that when da
faa0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 ta is appended t
fab0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 o a file, the da
fac0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a ta is appended.*
fad0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 * first then the
fae0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c size of the fil
faf0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e e is extended, n
fb00: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a ever the other.*
fb10: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 * way around. T
fb20: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f he SQLITE_IOCAP_
fb30: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 SEQUENTIAL prope
fb40: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
fb50: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 * information is
fb60: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b written to disk
fb70: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 in the same ord
fb80: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 er as calls.** t
fb90: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a o xWrite()..**.*
fba0: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 * If xRead() ret
fbb0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 urns SQLITE_IOER
fbc0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 R_SHORT_READ it
fbd0: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a must also fill.*
fbe0: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 * in the unread
fbf0: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 portions of the
fc00: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f buffer with zero
fc10: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a s. A VFS that.*
fc20: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d * fails to zero-
fc30: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 fill short reads
fc40: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 might seem to w
fc50: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a ork. However,.*
fc60: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 * failure to zer
fc70: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 o-fill short rea
fc80: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c ds will eventual
fc90: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 ly lead to.** da
fca0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f tabase corruptio
fcb0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 n..*/.typedef st
fcc0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f ruct sqlite3_io_
fcd0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f methods sqlite3_
fce0: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 io_methods;.stru
fcf0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 ct sqlite3_io_me
fd00: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 thods {. int iV
fd10: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a ersion;. int (*
fd20: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f xClose)(sqlite3_
fd30: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
fd40: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 xRead)(sqlite3_f
fd50: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 ile*, void*, int
fd60: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 iAmt, sqlite3_i
fd70: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 nt64 iOfst);. i
fd80: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c nt (*xWrite)(sql
fd90: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 ite3_file*, cons
fda0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d t void*, int iAm
fdb0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 t, sqlite3_int64
fdc0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 iOfst);. int (
fdd0: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 *xTruncate)(sqli
fde0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 te3_file*, sqlit
fdf0: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a e3_int64 size);.
fe00: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 int (*xSync)(s
fe10: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e qlite3_file*, in
fe20: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 t flags);. int
fe30: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c (*xFileSize)(sql
fe40: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 ite3_file*, sqli
fe50: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 te3_int64 *pSize
fe60: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b );. int (*xLock
fe70: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c )(sqlite3_file*,
fe80: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 int);. int (*x
fe90: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f Unlock)(sqlite3_
fea0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 file*, int);. i
feb0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 nt (*xCheckReser
fec0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 vedLock)(sqlite3
fed0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 _file*, int *pRe
fee0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 sOut);. int (*x
fef0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c FileControl)(sql
ff00: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
ff10: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b op, void *pArg);
ff20: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 . int (*xSector
ff30: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 Size)(sqlite3_fi
ff40: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 le*);. int (*xD
ff50: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 eviceCharacteris
ff60: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 tics)(sqlite3_fi
ff70: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f le*);. /* Metho
ff80: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c ds above are val
ff90: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 id for version 1
ffa0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d */. int (*xShm
ffb0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c Map)(sqlite3_fil
ffc0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 e*, int iPg, int
ffd0: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 pgsz, int, void
ffe0: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 volatile**);.
fff0: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 int (*xShmLock)(
10000 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 sqlite3_file*, i
10010 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e nt offset, int n
10020 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 , int flags);.
10030 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 void (*xShmBarri
10040 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 er)(sqlite3_file
10050 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d *);. int (*xShm
10060 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 Unmap)(sqlite3_f
10070 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 ile*, int delete
10080 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 Flag);. /* Meth
10090 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 ods above are va
100a0 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 lid for version
100b0 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 2 */. int (*xFe
100c0 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c tch)(sqlite3_fil
100d0 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
100e0 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 4 iOfst, int iAm
100f0 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 t, void **pp);.
10100 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 int (*xUnfetch)
10110 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
10120 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f sqlite3_int64 iO
10130 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 fst, void *p);.
10140 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 /* Methods abov
10150 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 e are valid for
10160 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f version 3 */. /
10170 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 * Additional met
10180 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 hods may be adde
10190 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
101a0 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a ases */.};../*.*
101b0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e * CAPI3REF: Stan
101c0 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f dard File Contro
101d0 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 l Opcodes.** KEY
101e0 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e WORDS: {file con
101f0 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 trol opcodes} {f
10200 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f ile control opco
10210 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 de}.**.** These
10220 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 integer constant
10230 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f s are opcodes fo
10240 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 r the xFileContr
10250 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 ol method.** of
10260 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f the [sqlite3_io_
10270 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 methods] object
10280 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c and for the [sql
10290 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f ite3_file_contro
102a0 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 l()].** interfac
102b0 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a e..**.** <ul>.**
102c0 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
102d0 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a NTL_LOCKSTATE]].
102e0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
102f0 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 CNTL_LOCKSTATE]
10300 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 opcode is used f
10310 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 or debugging. T
10320 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 his.** opcode ca
10330 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f uses the xFileCo
10340 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 ntrol method to
10350 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e write the curren
10360 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 t state of.** th
10370 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b e lock (one of [
10380 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 SQLITE_LOCK_NONE
10390 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f ], [SQLITE_LOCK_
103a0 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c SHARED],.** [SQL
103b0 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 ITE_LOCK_RESERVE
103c0 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b D], [SQLITE_LOCK
103d0 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 _PENDING], or [S
103e0 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
103f0 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 SIVE]).** into a
10400 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 n integer that t
10410 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 he pArg argument
10420 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 points to. This
10430 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 capability.** i
10440 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 s used during te
10450 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c sting and is onl
10460 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e y available when
10470 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 the SQLITE_TEST
10480 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 .** compile-time
10490 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e option is used.
104a0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
104b0 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
104c0 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 INT]].** The [SQ
104d0 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
104e0 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 HINT] opcode is
104f0 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 used by SQLite t
10500 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a o give the VFS.*
10510 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f * layer a hint o
10520 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 f how large the
10530 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 database file wi
10540 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 ll grow to be du
10550 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 ring the.** curr
10560 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e ent transaction.
10570 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e This hint is n
10580 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f ot guaranteed to
10590 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 be accurate but
105a0 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 it.** is often
105b0 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 close. The unde
105c0 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 rlying VFS might
105d0 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c choose to preal
105e0 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a locate database.
105f0 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 ** file space ba
10600 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 sed on this hint
10610 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c in order to hel
10620 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 p writes to the
10630 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 database.** file
10640 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a run faster..**.
10650 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
10660 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 FCNTL_CHUNK_SIZE
10670 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
10680 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 E_FCNTL_CHUNK_SI
10690 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 ZE] opcode is us
106a0 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 ed to request th
106b0 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 at the VFS.** ex
106c0 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 tends and trunca
106d0 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 tes the database
106e0 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 file in chunks
106f0 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 of a size specif
10700 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 ied.** by the us
10710 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 er. The fourth a
10720 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
10730 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c te3_file_control
10740 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 ()] should .** p
10750 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 oint to an integ
10760 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f er (type int) co
10770 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 ntaining the new
10780 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 chunk-size to u
10790 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f se.** for the no
107a0 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 minated database
107b0 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 . Allocating dat
107c0 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 abase file space
107d0 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 in large.** chu
107e0 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 nks (say 1MB at
107f0 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 a time), may red
10800 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 uce file-system
10810 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e fragmentation an
10820 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 d.** improve per
10830 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 formance on some
10840 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 systems..**.**
10850 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
10860 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d TL_FILE_POINTER]
10870 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
10880 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e _FCNTL_FILE_POIN
10890 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 TER] opcode is u
108a0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 sed to obtain a
108b0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 pointer.** to th
108c0 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d e [sqlite3_file]
108d0 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 object associat
108e0 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 ed with a partic
108f0 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a ular database.**
10900 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 connection. Se
10910 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 e also [SQLITE_F
10920 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 CNTL_JOURNAL_POI
10930 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 NTER]..**.** <li
10940 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
10950 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d JOURNAL_POINTER]
10960 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
10970 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 _FCNTL_JOURNAL_P
10980 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 OINTER] opcode i
10990 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e s used to obtain
109a0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
109b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 the [sqlite3_fi
109c0 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 le] object assoc
109d0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a iated with the j
109e0 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 ournal file (eit
109f0 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c her.** the [roll
10a00 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 back journal] or
10a10 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 the [write-ahea
10a20 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 d log]) for a pa
10a30 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 rticular databas
10a40 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
10a50 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 See also [SQLI
10a60 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
10a70 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c INTER]..**.** <l
10a80 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
10a90 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a _SYNC_OMITTED]].
10aa0 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 ** No longer in
10ab0 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b use..**.** <li>[
10ac0 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 [SQLITE_FCNTL_SY
10ad0 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c NC]].** The [SQL
10ae0 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 ITE_FCNTL_SYNC]
10af0 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 opcode is genera
10b00 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 ted internally b
10b10 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 y SQLite and.**
10b20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 sent to the VFS
10b30 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f immediately befo
10b40 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 re the xSync met
10b50 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f hod is invoked o
10b60 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 n a.** database
10b70 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e file descriptor.
10b80 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e Or, if the xSyn
10b90 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 c method is not
10ba0 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 invoked .** beca
10bb0 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 use the user has
10bc0 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 configured SQLi
10bd0 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 te with .** [PRA
10be0 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 GMA synchronous
10bf0 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f | PRAGMA synchro
10c00 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 nous=OFF] it is
10c10 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 invoked in place
10c20 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e .** of the xSyn
10c30 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 c method. In mos
10c40 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 t cases, the poi
10c50 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 nter argument pa
10c60 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 ssed with.** thi
10c70 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 s file-control i
10c80 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c s NULL. However,
10c90 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 if the database
10ca0 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 file is being s
10cb0 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 ynced.** as part
10cc0 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 of a multi-data
10cd0 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 base commit, the
10ce0 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 argument points
10cf0 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e to a nul-termin
10d00 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 ated.** string c
10d10 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 ontaining the tr
10d20 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 ansactions maste
10d30 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e r-journal file n
10d40 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 ame. VFSes that
10d50 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 .** do not need
10d60 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 this signal shou
10d70 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f ld silently igno
10d80 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 re this opcode.
10d90 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a Applications .**
10da0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c should not call
10db0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 [sqlite3_file_c
10dc0 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 ontrol()] with t
10dd0 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f his opcode as do
10de0 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 ing so may .** d
10df0 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 isrupt the opera
10e00 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 tion of the spec
10e10 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 ialized VFSes th
10e20 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 at do require it
10e30 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b . .**.** <li>[[
10e40 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d SQLITE_FCNTL_COM
10e50 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a MIT_PHASETWO]].*
10e60 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
10e70 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 NTL_COMMIT_PHASE
10e80 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 TWO] opcode is g
10e90 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 enerated interna
10ea0 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a lly by SQLite.**
10eb0 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 and sent to the
10ec0 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 VFS after a tra
10ed0 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 nsaction has bee
10ee0 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 n committed imme
10ef0 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 diately.** but b
10f00 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 efore the databa
10f10 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 se is unlocked.
10f20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f VFSes that do no
10f30 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e t need this sign
10f40 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c al.** should sil
10f50 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 ently ignore thi
10f60 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 s opcode. Applic
10f70 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f ations should no
10f80 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 t call.** [sqlit
10f90 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
10fa0 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 )] with this opc
10fb0 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 ode as doing so
10fc0 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 may disrupt the
10fd0 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 .** operation of
10fe0 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 the specialized
10ff0 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 VFSes that do r
11000 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a equire it. .**.
11010 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
11020 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 FCNTL_WIN32_AV_R
11030 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b ETRY]].** ^The [
11040 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e SQLITE_FCNTL_WIN
11050 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 32_AV_RETRY] opc
11060 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 ode is used to c
11070 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 onfigure automat
11080 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e ic.** retry coun
11090 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 ts and intervals
110a0 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 for certain dis
110b0 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 k I/O operations
110c0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 for the.** wind
110d0 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 ows [VFS] in ord
110e0 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f er to provide ro
110f0 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 bustness in the
11100 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 presence of.** a
11110 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 nti-virus progra
11120 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c ms. By default,
11130 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 the windows VFS
11140 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 will retry file
11150 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 read,.** file w
11160 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 rite, and file d
11170 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 elete operations
11180 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c up to 10 times,
11190 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a with a delay.**
111a0 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f of 25 milliseco
111b0 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 nds before the f
111c0 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 irst retry and w
111d0 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e ith the delay in
111e0 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 creasing.** by a
111f0 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 n additional 25
11200 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 milliseconds wit
11210 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e h each subsequen
11220 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a t retry. This.*
11230 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 * opcode allows
11240 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 these two values
11250 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 (10 retries and
11260 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 25 milliseconds
11270 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f of delay).** to
11280 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 be adjusted. T
11290 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 he values are ch
112a0 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 anged for all da
112b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
112c0 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 ns.** within the
112d0 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 same process.
112e0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 The argument is
112f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
11300 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 array of two.**
11310 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 integers where t
11320 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 he first integer
11330 20 69 73 20 74 68 65 20 6e 65 77 20 72 65 74 72 is the new retr
11340 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 y count and the
11350 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 second.** intege
11360 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 r is the delay.
11370 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 If either integ
11380 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 er is negative,
11390 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 then the setting
113a0 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 .** is not chang
113b0 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 ed but instead t
113c0 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f he prior value o
113d0 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 f that setting i
113e0 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 s written.** int
113f0 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 o the array entr
11400 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 y, allowing the
11410 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 current retry se
11420 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 ttings to be.**
11430 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 interrogated. T
11440 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d he zDbName param
11450 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e eter is ignored.
11460 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
11470 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 ITE_FCNTL_PERSIS
11480 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 T_WAL]].** ^The
11490 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 [SQLITE_FCNTL_PE
114a0 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 RSIST_WAL] opcod
114b0 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 e is used to set
114c0 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a or query the.**
114d0 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c persistent [WAL
114e0 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c | Write Ahead L
114f0 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 og] setting. By
11500 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 default, the au
11510 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 xiliary.** write
11520 20 61 68 65 61 64 20 6c 6f 67 20 28 5b 57 41 4c ahead log ([WAL
11530 20 66 69 6c 65 5d 29 20 61 6e 64 20 73 68 61 72 file]) and shar
11540 65 64 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 69 6c ed memory.** fil
11550 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e es used for tran
11560 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a saction control.
11570 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 ** are automatic
11580 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 ally deleted whe
11590 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e n the latest con
115a0 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 nection to the d
115b0 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 atabase.** close
115c0 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 s. Setting pers
115d0 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 istent WAL mode
115e0 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c causes those fil
115f0 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 es to persist af
11600 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 ter.** close. P
11610 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 ersisting the fi
11620 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 les is useful wh
11630 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 en other process
11640 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a es that do not.*
11650 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 * have write per
11660 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 mission on the d
11670 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e irectory contain
11680 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 ing the database
11690 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f file want.** to
116a0 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 read the databa
116b0 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 se file, as the
116c0 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d WAL and shared m
116d0 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 emory files must
116e0 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 exist.** in ord
116f0 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 er for the datab
11700 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 ase to be readab
11710 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 le. The fourth
11720 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 parameter to.**
11730 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
11740 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 ntrol()] for thi
11750 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 s opcode should
11760 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 be a pointer to
11770 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 an integer..** T
11780 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 hat integer is 0
11790 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 to disable pers
117a0 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 istent WAL mode
117b0 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 or 1 to enable p
117c0 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c ersistent.** WAL
117d0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 mode. If the i
117e0 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 nteger is -1, th
117f0 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 en it is overwri
11800 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 tten with the cu
11810 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 rrent.** WAL per
11820 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 sistence setting
11830 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
11840 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 LITE_FCNTL_POWER
11850 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d SAFE_OVERWRITE]]
11860 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
11870 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 _FCNTL_POWERSAFE
11880 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f _OVERWRITE] opco
11890 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 de is used to se
118a0 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a t or query the.*
118b0 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f * persistent "po
118c0 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 wersafe-overwrit
118d0 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 e" or "PSOW" set
118e0 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 ting. The PSOW
118f0 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 setting.** deter
11900 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 mines the [SQLIT
11910 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 E_IOCAP_POWERSAF
11920 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 E_OVERWRITE] bit
11930 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 of the.** xDevi
11940 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
11950 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 s methods. The f
11960 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 ourth parameter
11970 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 to.** [sqlite3_f
11980 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 ile_control()] f
11990 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 or this opcode s
119a0 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 hould be a point
119b0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 er to an integer
119c0 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 ..** That intege
119d0 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c r is 0 to disabl
119e0 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f e zero-damage mo
119f0 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c de or 1 to enabl
11a00 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a e zero-damage.**
11a10 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 mode. If the i
11a20 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 nteger is -1, th
11a30 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 en it is overwri
11a40 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 tten with the cu
11a50 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 rrent.** zero-da
11a60 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e mage mode settin
11a70 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 g..**.** <li>[[S
11a80 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 QLITE_FCNTL_OVER
11a90 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 WRITE]].** ^The
11aa0 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 [SQLITE_FCNTL_OV
11ab0 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 ERWRITE] opcode
11ac0 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 is invoked by SQ
11ad0 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 Lite after openi
11ae0 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 ng.** a write tr
11af0 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 ansaction to ind
11b00 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 icate that, unle
11b10 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 ss it is rolled
11b20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a back for some.**
11b30 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 reason, the ent
11b40 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c ire database fil
11b50 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 e will be overwr
11b60 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 itten by the cur
11b70 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 rent .** transac
11b80 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 tion. This is us
11b90 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 ed by VACUUM ope
11ba0 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c rations..**.** <
11bb0 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
11bc0 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e L_VFSNAME]].** ^
11bd0 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
11be0 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 L_VFSNAME] opcod
11bf0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f e can be used to
11c00 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 obtain the name
11c10 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 s of.** all [VFS
11c20 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 es] in the VFS s
11c30 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 tack. The names
11c40 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 are of all VFS
11c50 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a shims and the.**
11c60 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 final bottom-le
11c70 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 vel VFS are writ
11c80 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 ten into memory
11c90 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a obtained from .*
11ca0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f * [sqlite3_mallo
11cb0 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 c()] and the res
11cc0 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e ult is stored in
11cd0 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 the char* varia
11ce0 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 ble.** that the
11cf0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
11d00 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c of [sqlite3_fil
11d10 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 e_control()] poi
11d20 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 nts to..** The c
11d30 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 aller is respons
11d40 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 ible for freeing
11d50 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e the memory when
11d60 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a done. As with.
11d70 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 ** all file-cont
11d80 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 rol actions, the
11d90 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 re is no guarant
11da0 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c ee that this wil
11db0 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f l actually.** do
11dc0 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c anything. Call
11dd0 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 ers should initi
11de0 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 alize the char*
11df0 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 variable to a NU
11e00 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e LL.** pointer in
11e10 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d case this file-
11e20 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 control is not i
11e30 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 mplemented. Thi
11e40 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a s file-control.*
11e50 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f * is intended fo
11e60 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 r diagnostic use
11e70 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 only..**.** <li
11e80 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
11e90 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a VFS_POINTER]].**
11ea0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 ^The [SQLITE_FC
11eb0 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d NTL_VFS_POINTER]
11ec0 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 opcode finds a
11ed0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 pointer to the t
11ee0 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 op-level.** [VFS
11ef0 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e es] currently in
11f00 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 use. ^(The arg
11f10 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 ument X in.** sq
11f20 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 lite3_file_contr
11f30 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e ol(db,SQLITE_FCN
11f40 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 TL_VFS_POINTER,X
11f50 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 ) must be.** of
11f60 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 type "[sqlite3_v
11f70 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f fs] **". This o
11f80 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 pcodes will set
11f90 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 *X.** to a point
11fa0 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 er to the top-le
11fb0 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 vel VFS.)^.** ^W
11fc0 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 hen there are mu
11fd0 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 ltiple VFS shims
11fe0 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 in the stack, t
11ff0 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 his opcode finds
12000 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f the.** upper-mo
12010 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a st shim only..**
12020 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
12030 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a _FCNTL_PRAGMA]].
12040 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b ** ^Whenever a [
12050 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e PRAGMA] statemen
12060 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 t is parsed, an
12070 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
12080 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 AGMA] .** file c
12090 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 ontrol is sent t
120a0 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 o the open [sqli
120b0 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 te3_file] object
120c0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a corresponding.*
120d0 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 * to the databas
120e0 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 e file to which
120f0 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 the pragma state
12100 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 ment refers. ^Th
12110 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f e argument.** to
12120 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e the [SQLITE_FCN
12130 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 TL_PRAGMA] file
12140 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 control is an ar
12150 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 ray of.** pointe
12160 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 rs to strings (c
12170 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 har**) in which
12180 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 the second eleme
12190 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a nt of the array.
121a0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f ** is the name o
121b0 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 f the pragma and
121c0 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 the third eleme
121d0 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 nt is the argume
121e0 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 nt to the.** pra
121f0 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 gma or NULL if t
12200 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f he pragma has no
12210 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 argument. ^The
12220 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a handler for an.
12230 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
12240 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f _PRAGMA] file co
12250 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e ntrol can option
12260 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 ally make the fi
12270 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f rst element.** o
12280 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 f the char** arg
12290 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 ument point to a
122a0 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 string obtained
122b0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d from [sqlite3_m
122c0 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 printf()].** or
122d0 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 the equivalent a
122e0 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 nd that string w
122f0 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 ill become the r
12300 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 esult of the pra
12310 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 gma or.** the er
12320 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 ror message if t
12330 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e he pragma fails.
12340 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c ^If the.** [SQL
12350 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 ITE_FCNTL_PRAGMA
12360 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 ] file control r
12370 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e eturns [SQLITE_N
12380 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e OTFOUND], then n
12390 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d ormal .** [PRAGM
123a0 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f A] processing co
123b0 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 ntinues. ^If th
123c0 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
123d0 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 PRAGMA].** file
123e0 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 control returns
123f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 [SQLITE_OK], the
12400 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 n the parser ass
12410 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a umes that the.**
12420 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 VFS has handled
12430 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 the PRAGMA itse
12440 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 lf and the parse
12450 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f r generates a no
12460 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 -op.** prepared
12470 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 statement if res
12480 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 ult string is NU
12490 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 LL, or that retu
124a0 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 rns a copy.** of
124b0 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 the result stri
124c0 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 ng if the string
124d0 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a is non-NULL..**
124e0 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 ^If the [SQLITE
124f0 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 _FCNTL_PRAGMA] f
12500 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 ile control retu
12510 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c rns.** any resul
12520 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 t code other tha
12530 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 n [SQLITE_OK] or
12540 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e [SQLITE_NOTFOUN
12550 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a D], that means.*
12560 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 * that the VFS e
12570 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 ncountered an er
12580 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 ror while handli
12590 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 ng the [PRAGMA]
125a0 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 and the.** compi
125b0 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 lation of the PR
125c0 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 AGMA fails with
125d0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 an error. ^The
125e0 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
125f0 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f AGMA].** file co
12600 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 ntrol occurs at
12610 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 the beginning of
12620 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e pragma statemen
12630 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 t analysis and s
12640 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 o.** it is able
12650 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c to override buil
12660 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 t-in [PRAGMA] st
12670 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 atements..**.**
12680 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
12690 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d TL_BUSYHANDLER]]
126a0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 .** ^The [SQLITE
126b0 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c _FCNTL_BUSYHANDL
126c0 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 ER].** file-cont
126d0 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b rol may be invok
126e0 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 ed by SQLite on
126f0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
12700 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 e handle.** shor
12710 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 tly after it is
12720 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 opened in order
12730 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 to provide a cus
12740 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 tom VFS with acc
12750 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f ess.** to the co
12760 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 nnections busy-h
12770 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e andler callback.
12780 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 The argument is
12790 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a of type (void *
127a0 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 *).** - an array
127b0 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 of two (void *)
127c0 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 values. The fir
127d0 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 st (void *) actu
127e0 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 ally points.** t
127f0 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 o a function of
12800 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f type (int (*)(vo
12810 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 id *)). In order
12820 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 to invoke the c
12830 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 onnections.** bu
12840 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 sy-handler, this
12850 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 function should
12860 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
12870 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 the second (voi
12880 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 d *) in.** the a
12890 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 rray as the only
128a0 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 argument. If it
128b0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 returns non-zer
128c0 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 o, then the oper
128d0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 ation.** should
128e0 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 be retried. If i
128f0 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 t returns zero,
12900 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 the custom VFS s
12910 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 hould abandon th
12920 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 e.** current ope
12930 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c ration..**.** <l
12940 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
12950 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a _TEMPFILENAME]].
12960 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 ** ^Application
12970 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b can invoke the [
12980 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d SQLITE_FCNTL_TEM
12990 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d PFILENAME] file-
129a0 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 control.** to ha
129b0 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 ve SQLite genera
129c0 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 te a.** temporar
129d0 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 y filename using
129e0 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 the same algori
129f0 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c thm that is foll
12a00 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 owed to generate
12a10 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 .** temporary fi
12a20 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 lenames for TEMP
12a30 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 tables and othe
12a40 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e r internal uses.
12a50 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e The.** argumen
12a60 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 t should be a ch
12a70 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 ar** which will
12a80 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 be filled with t
12a90 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 he filename.** w
12aa0 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f ritten into memo
12ab0 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
12ac0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
12ad0 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 ()]. The caller
12ae0 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b should.** invok
12af0 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 e [sqlite3_free(
12b00 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 )] on the result
12b10 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f to avoid a memo
12b20 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c ry leak..**.** <
12b30 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
12b40 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a L_MMAP_SIZE]].**
12b50 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e The [SQLITE_FCN
12b60 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 TL_MMAP_SIZE] fi
12b70 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 le control is us
12b80 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 ed to query or s
12b90 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 et the.** maximu
12ba0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 m number of byte
12bb0 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 s that will be u
12bc0 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d sed for memory-m
12bd0 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 apped I/O..** Th
12be0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 e argument is a
12bf0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c pointer to a val
12c00 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 ue of type sqlit
12c10 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a e3_int64 that.**
12c20 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 is an advisory
12c30 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f maximum number o
12c40 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 f bytes in the f
12c50 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 ile to memory ma
12c60 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 p. The.** point
12c70 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 er is overwritte
12c80 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 n with the old v
12c90 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 alue. The limit
12ca0 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 is not changed
12cb0 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 if.** the value
12cc0 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 originally point
12cd0 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 ed to is negativ
12ce0 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 e, and so the cu
12cf0 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 rrent limit .**
12d00 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 can be queried b
12d10 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 y passing in a p
12d20 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 ointer to a nega
12d30 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 tive number. Th
12d40 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 is.** file-contr
12d50 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 ol is used inter
12d60 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 nally to impleme
12d70 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f nt [PRAGMA mmap_
12d80 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 size]..**.** <li
12d90 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
12da0 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b TRACE]].** The [
12db0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 SQLITE_FCNTL_TRA
12dc0 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c CE] file control
12dd0 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f provides adviso
12de0 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a ry information.*
12df0 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f * to the VFS abo
12e00 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 ut what the high
12e10 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 er layers of the
12e20 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 SQLite stack ar
12e30 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 e doing..** This
12e40 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 file control is
12e50 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 used by some VF
12e60 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 S activity traci
12e70 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 ng [shims]..** T
12e80 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 he argument is a
12e90 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
12ea0 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 string. Higher
12eb0 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a layers in the.*
12ec0 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d * SQLite stack m
12ed0 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 ay generate inst
12ee0 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 ances of this fi
12ef0 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a le control if.**
12f00 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 the [SQLITE_USE
12f10 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f _FCNTL_TRACE] co
12f20 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
12f30 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a n is enabled..**
12f40 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
12f50 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 _FCNTL_HAS_MOVED
12f60 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
12f70 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 E_FCNTL_HAS_MOVE
12f80 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 D] file control
12f90 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 interprets its a
12fa0 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 rgument as a.**
12fb0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
12fc0 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 teger and it wri
12fd0 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e tes a boolean in
12fe0 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 to that integer
12ff0 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 depending.** on
13000 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
13010 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e he file has been
13020 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c renamed, moved,
13030 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 or deleted sinc
13040 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 e it.** was firs
13050 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 t opened..**.**
13060 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
13070 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e TL_WIN32_GET_HAN
13080 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 DLE]].** The [SQ
13090 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 LITE_FCNTL_WIN32
130a0 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 _GET_HANDLE] opc
130b0 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ode can be used
130c0 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a to obtain the.**
130d0 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 underlying nati
130e0 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 ve file handle a
130f0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 ssociated with a
13100 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 file handle. T
13110 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 his file.** cont
13120 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 rol interprets i
13130 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 ts argument as a
13140 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 pointer to a na
13150 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 tive file handle
13160 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 and.** writes t
13170 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c he resulting val
13180 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 ue there..**.**
13190 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
131a0 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e TL_WIN32_SET_HAN
131b0 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 DLE]].** The [SQ
131c0 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 LITE_FCNTL_WIN32
131d0 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 _SET_HANDLE] opc
131e0 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 ode is used for
131f0 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 debugging. This
13200 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 .** opcode cause
13210 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 s the xFileContr
13220 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 ol method to swa
13230 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c p the file handl
13240 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a e with the one.*
13250 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 * pointed to by
13260 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e the pArg argumen
13270 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c t. This capabil
13280 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 ity is used duri
13290 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e ng testing.** an
132a0 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 d only needs to
132b0 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 be supported whe
132c0 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 n SQLITE_TEST is
132d0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 defined..**.**
132e0 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
132f0 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a TL_WAL_BLOCK]].*
13300 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
13310 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 NTL_WAL_BLOCK] i
13320 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 s a signal to th
13330 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 e VFS layer that
13340 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 it might.** be
13350 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 advantageous to
13360 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 block on the nex
13370 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 t WAL lock if th
13380 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d e lock is not im
13390 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 mediately.** ava
133a0 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c ilable. The WAL
133b0 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 subsystem issue
133c0 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 s this signal du
133d0 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 ring rare.** cir
133e0 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 cumstances in or
133f0 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f der to fix a pro
13400 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 blem with priori
13410 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a ty inversion..**
13420 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 Applications sh
13430 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d ould <em>not</em
13440 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d > use this file-
13450 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c control..**.** <
13460 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
13470 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 L_ZIPVFS]].** Th
13480 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
13490 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 ZIPVFS] opcode i
134a0 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 s implemented by
134b0 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c zipvfs only. Al
134c0 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 l other.** VFS s
134d0 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c hould return SQL
134e0 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 ITE_NOTFOUND for
134f0 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a this opcode..**
13500 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
13510 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 _FCNTL_RBU]].**
13520 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
13530 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 L_RBU] opcode is
13540 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 implemented by
13550 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 the special VFS
13560 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 used by.** the R
13570 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c BU extension onl
13580 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 y. All other VF
13590 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 S should return
135a0 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 SQLITE_NOTFOUND
135b0 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f for.** this opco
135c0 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e de. .**.** <li>
135d0 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 [[SQLITE_FCNTL_B
135e0 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 EGIN_ATOMIC_WRIT
135f0 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 65 20 5b 53 E]].** If the [S
13600 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 QLITE_FCNTL_BEGI
13610 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 N_ATOMIC_WRITE]
13620 6f 70 63 6f 64 65 20 72 65 74 75 72 6e 73 20 53 opcode returns S
13630 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 65 6e 0a 2a QLITE_OK, then.*
13640 2a 20 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 * the file descr
13650 69 70 74 6f 72 20 69 73 20 70 6c 61 63 65 64 20 iptor is placed
13660 69 6e 20 22 62 61 74 63 68 20 77 72 69 74 65 20 in "batch write
13670 6d 6f 64 65 22 2c 20 77 68 69 63 68 0a 2a 2a 20 mode", which.**
13680 6d 65 61 6e 73 20 61 6c 6c 20 73 75 62 73 65 71 means all subseq
13690 75 65 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61 uent write opera
136a0 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 20 64 65 tions will be de
136b0 66 65 72 72 65 64 20 61 6e 64 20 64 6f 6e 65 0a ferred and done.
136c0 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c 79 20 61 74 ** atomically at
136d0 20 74 68 65 20 6e 65 78 74 20 5b 53 51 4c 49 54 the next [SQLIT
136e0 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 E_FCNTL_COMMIT_A
136f0 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 20 20 53 TOMIC_WRITE]. S
13700 79 73 74 65 6d 73 0a 2a 2a 20 74 68 61 74 20 64 ystems.** that d
13710 6f 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 62 61 o not support ba
13720 74 63 68 20 61 74 6f 6d 69 63 20 77 72 69 74 65 tch atomic write
13730 73 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 s will return SQ
13740 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 2e 0a 2a LITE_NOTFOUND..*
13750 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 20 61 20 73 * ^Following a s
13760 75 63 63 65 73 73 66 75 6c 20 53 51 4c 49 54 45 uccessful SQLITE
13770 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f _FCNTL_BEGIN_ATO
13780 4d 49 43 5f 57 52 49 54 45 20 61 6e 64 20 70 72 MIC_WRITE and pr
13790 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6c ior to.** the cl
137a0 6f 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 43 osing [SQLITE_FC
137b0 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 NTL_COMMIT_ATOMI
137c0 43 5f 57 52 49 54 45 5d 20 6f 72 0a 2a 2a 20 5b C_WRITE] or.** [
137d0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c SQLITE_FCNTL_ROL
137e0 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 LBACK_ATOMIC_WRI
137f0 54 45 5d 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c TE], SQLite will
13800 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 56 46 53 20 make.** no VFS
13810 69 6e 74 65 72 66 61 63 65 20 63 61 6c 6c 73 20 interface calls
13820 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 73 71 6c on the same [sql
13830 69 74 65 33 5f 66 69 6c 65 5d 20 66 69 6c 65 20 ite3_file] file
13840 64 65 73 63 72 69 70 74 6f 72 0a 2a 2a 20 65 78 descriptor.** ex
13850 63 65 70 74 20 66 6f 72 20 63 61 6c 6c 73 20 74 cept for calls t
13860 6f 20 74 68 65 20 78 57 72 69 74 65 20 6d 65 74 o the xWrite met
13870 68 6f 64 20 61 6e 64 20 74 68 65 20 78 46 69 6c hod and the xFil
13880 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a eControl method.
13890 2a 2a 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f ** with [SQLITE_
138a0 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d FCNTL_SIZE_HINT]
138b0 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
138c0 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 LITE_FCNTL_COMMI
138d0 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d T_ATOMIC_WRITE]]
138e0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
138f0 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f FCNTL_COMMIT_ATO
13900 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 MIC_WRITE] opcod
13910 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 69 e causes all wri
13920 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 te.** operations
13930 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 69 since the previ
13940 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 63 ous successful c
13950 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 all to .** [SQLI
13960 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 TE_FCNTL_BEGIN_A
13970 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 TOMIC_WRITE] to
13980 62 65 20 70 65 72 66 6f 72 6d 65 64 20 61 74 6f be performed ato
13990 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 54 68 69 73 mically..** This
139a0 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 file control re
139b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b turns [SQLITE_OK
139c0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 ] if and only if
139d0 20 74 68 65 20 77 72 69 74 65 73 20 77 65 72 65 the writes were
139e0 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 6f 72 6d 65 .** all performe
139f0 64 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 61 d successfully a
13a00 6e 64 20 68 61 76 65 20 62 65 65 6e 20 63 6f 6d nd have been com
13a10 6d 69 74 74 65 64 20 74 6f 20 70 65 72 73 69 73 mitted to persis
13a20 74 65 6e 74 20 73 74 6f 72 61 67 65 2e 0a 2a 2a tent storage..**
13a30 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 ^Regardless of
13a40 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 whether or not i
13a50 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 2c t is successful,
13a60 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 this file contr
13a70 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 74 68 65 20 ol takes.** the
13a80 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 20 file descriptor
13a90 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 69 out of batch wri
13aa0 74 65 20 6d 6f 64 65 20 73 6f 20 74 68 61 74 20 te mode so that
13ab0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a all subsequent.*
13ac0 2a 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f * write operatio
13ad0 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 65 ns are independe
13ae0 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 nt..** ^SQLite w
13af0 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 ill never invoke
13b00 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f SQLITE_FCNTL_CO
13b10 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 MMIT_ATOMIC_WRIT
13b20 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 E without.** a p
13b30 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 rior successful
13b40 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f call to [SQLITE_
13b50 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d FCNTL_BEGIN_ATOM
13b60 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a IC_WRITE]..**.**
13b70 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
13b80 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f NTL_ROLLBACK_ATO
13b90 4d 49 43 5f 57 52 49 54 45 5d 5d 0a 2a 2a 20 54 MIC_WRITE]].** T
13ba0 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
13bb0 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 _ROLLBACK_ATOMIC
13bc0 5f 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 63 _WRITE] opcode c
13bd0 61 75 73 65 73 20 61 6c 6c 20 77 72 69 74 65 0a auses all write.
13be0 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 73 20 73 69 ** operations si
13bf0 6e 63 65 20 74 68 65 20 70 72 65 76 69 6f 75 73 nce the previous
13c00 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c successful call
13c10 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f to .** [SQLITE_
13c20 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d FCNTL_BEGIN_ATOM
13c30 49 43 5f 57 52 49 54 45 5d 20 74 6f 20 62 65 20 IC_WRITE] to be
13c40 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 20 rolled back..**
13c50 5e 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 ^This file contr
13c60 6f 6c 20 74 61 6b 65 73 20 74 68 65 20 66 69 6c ol takes the fil
13c70 65 20 64 65 73 63 72 69 70 74 6f 72 20 6f 75 74 e descriptor out
13c80 20 6f 66 20 62 61 74 63 68 20 77 72 69 74 65 20 of batch write
13c90 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 68 61 74 20 mode.** so that
13ca0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 77 all subsequent w
13cb0 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 rite operations
13cc0 61 72 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 2e are independent.
13cd0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
13ce0 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 53 51 never invoke SQ
13cf0 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 LITE_FCNTL_ROLLB
13d00 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 ACK_ATOMIC_WRITE
13d10 20 77 69 74 68 6f 75 74 0a 2a 2a 20 61 20 70 72 without.** a pr
13d20 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 ior successful c
13d30 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 54 45 5f 46 all to [SQLITE_F
13d40 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 CNTL_BEGIN_ATOMI
13d50 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a 0a 2a 2a 20 C_WRITE]..**.**
13d60 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
13d70 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 4f 55 54 5d TL_LOCK_TIMEOUT]
13d80 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
13d90 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 5f 54 49 4d 45 _FCNTL_LOCK_TIME
13da0 4f 55 54 5d 20 6f 70 63 6f 64 65 20 63 61 75 73 OUT] opcode caus
13db0 65 73 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6f es attempts to o
13dc0 62 74 61 69 6e 0a 2a 2a 20 61 20 66 69 6c 65 20 btain.** a file
13dd0 6c 6f 63 6b 20 75 73 69 6e 67 20 74 68 65 20 78 lock using the x
13de0 4c 6f 63 6b 20 6f 72 20 78 53 68 6d 4c 6f 63 6b Lock or xShmLock
13df0 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68 65 20 methods of the
13e00 56 46 53 20 74 6f 20 77 61 69 74 0a 2a 2a 20 66 VFS to wait.** f
13e10 6f 72 20 75 70 20 74 6f 20 4d 20 6d 69 6c 6c 69 or up to M milli
13e20 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 66 seconds before f
13e30 61 69 6c 69 6e 67 2c 20 77 68 65 72 65 20 4d 20 ailing, where M
13e40 69 73 20 74 68 65 20 73 69 6e 67 6c 65 20 0a 2a is the single .*
13e50 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 * unsigned integ
13e60 65 72 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a er parameter..**
13e70 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
13e80 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 _FCNTL_DATA_VERS
13e90 49 4f 4e 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 ION]].** The [SQ
13ea0 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f LITE_FCNTL_DATA_
13eb0 56 45 52 53 49 4f 4e 5d 20 6f 70 63 6f 64 65 20 VERSION] opcode
13ec0 69 73 20 75 73 65 64 20 74 6f 20 64 65 74 65 63 is used to detec
13ed0 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 t changes to.**
13ee0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e a database file.
13ef0 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 The argument i
13f00 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
13f10 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 32-bit unsigned
13f20 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 65 integer..** The
13f30 20 22 64 61 74 61 20 76 65 72 73 69 6f 6e 22 20 "data version"
13f40 66 6f 72 20 74 68 65 20 70 61 67 65 72 20 69 73 for the pager is
13f50 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
13f60 65 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 0a e pointer. The.
13f70 2a 2a 20 22 64 61 74 61 20 76 65 72 73 69 6f 6e ** "data version
13f80 22 20 63 68 61 6e 67 65 73 20 77 68 65 6e 65 76 " changes whenev
13f90 65 72 20 61 6e 79 20 63 68 61 6e 67 65 20 6f 63 er any change oc
13fa0 63 75 72 73 20 74 6f 20 74 68 65 20 63 6f 72 72 curs to the corr
13fb0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 64 61 74 esponding.** dat
13fc0 61 62 61 73 65 20 66 69 6c 65 2c 20 65 69 74 68 abase file, eith
13fd0 65 72 20 74 68 72 6f 75 67 68 20 53 51 4c 20 73 er through SQL s
13fe0 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 74 68 65 tatements on the
13ff0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 0a 2a same database.*
14000 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 72 20 * connection or
14010 74 68 72 6f 75 67 68 20 74 72 61 6e 73 61 63 74 through transact
14020 69 6f 6e 73 20 63 6f 6d 6d 69 74 74 65 64 20 62 ions committed b
14030 79 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 y separate datab
14040 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
14050 6e 73 20 70 6f 73 73 69 62 6c 79 20 69 6e 20 6f ns possibly in o
14060 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 2e 20 ther processes.
14070 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 The [sqlite3_tot
14080 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 0a 2a 2a al_changes()].**
14090 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 interface can b
140a0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 69 e used to find i
140b0 66 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 6f f any database o
140c0 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e n the connection
140d0 20 68 61 73 20 63 68 61 6e 67 65 64 2c 0a 2a 2a has changed,.**
140e0 20 62 75 74 20 74 68 61 74 20 69 6e 74 65 72 66 but that interf
140f0 61 63 65 20 72 65 73 70 6f 6e 64 73 20 74 6f 20 ace responds to
14100 63 68 61 6e 67 65 73 20 6f 6e 20 54 45 4d 50 20 changes on TEMP
14110 61 73 20 77 65 6c 6c 20 61 73 20 4d 41 49 4e 20 as well as MAIN
14120 61 6e 64 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 and does.** not
14130 70 72 6f 76 69 64 65 20 61 20 6d 65 63 68 61 6e provide a mechan
14140 69 73 6d 20 74 6f 20 64 65 74 65 63 74 20 63 68 ism to detect ch
14150 61 6e 67 65 73 20 74 6f 20 4d 41 49 4e 20 6f 6e anges to MAIN on
14160 6c 79 2e 20 20 41 6c 73 6f 2c 20 74 68 65 0a 2a ly. Also, the.*
14170 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c * [sqlite3_total
14180 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 _changes()] inte
14190 72 66 61 63 65 20 72 65 73 70 6f 6e 64 73 20 74 rface responds t
141a0 6f 20 69 6e 74 65 72 6e 61 6c 20 63 68 61 6e 67 o internal chang
141b0 65 73 20 6f 6e 6c 79 20 61 6e 64 0a 2a 2a 20 6f es only and.** o
141c0 6d 69 74 73 20 63 68 61 6e 67 65 73 20 6d 61 64 mits changes mad
141d0 65 20 62 79 20 6f 74 68 65 72 20 64 61 74 61 62 e by other datab
141e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e ase connections.
141f0 20 20 54 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 The.** [PRAGMA
14200 20 64 61 74 61 5f 76 65 72 73 69 6f 6e 5d 20 63 data_version] c
14210 6f 6d 6d 61 6e 64 20 70 72 6f 76 69 64 65 20 61 ommand provide a
14220 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65 mechanism to de
14230 74 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a tect changes to.
14240 2a 2a 20 61 20 73 69 6e 67 6c 65 20 61 74 74 61 ** a single atta
14250 63 68 65 64 20 64 61 74 61 62 61 73 65 20 74 68 ched database th
14260 61 74 20 6f 63 63 75 72 20 64 75 65 20 74 6f 20 at occur due to
14270 6f 74 68 65 72 20 64 61 74 61 62 61 73 65 20 63 other database c
14280 6f 6e 6e 65 63 74 69 6f 6e 73 2c 0a 2a 2a 20 62 onnections,.** b
14290 75 74 20 6f 6d 69 74 73 20 63 68 61 6e 67 65 73 ut omits changes
142a0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 implemented by
142b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
142c0 6e 65 63 74 69 6f 6e 20 6f 6e 20 77 68 69 63 68 nection on which
142d0 20 69 74 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 it is.** called
142e0 2e 20 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e . This file con
142f0 74 72 6f 6c 20 69 73 20 74 68 65 20 6f 6e 6c 79 trol is the only
14300 20 6d 65 63 68 61 6e 69 73 6d 20 74 6f 20 64 65 mechanism to de
14310 74 65 63 74 20 63 68 61 6e 67 65 73 20 74 68 61 tect changes tha
14320 74 0a 2a 2a 20 68 61 70 70 65 6e 20 65 69 74 68 t.** happen eith
14330 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 er internally or
14340 20 65 78 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 externally and
14350 74 68 61 74 20 61 72 65 20 61 73 73 6f 63 69 61 that are associa
14360 74 65 64 20 77 69 74 68 0a 2a 2a 20 61 20 70 61 ted with.** a pa
14370 72 74 69 63 75 6c 61 72 20 61 74 74 61 63 68 65 rticular attache
14380 64 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 20 3c d database..** <
14390 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /ul>.*/.#define
143a0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
143b0 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 KSTATE
143c0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
143d0 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f QLITE_FCNTL_GET_
143e0 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 LOCKPROXYFILE
143f0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 2.#define SQ
14400 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c LITE_FCNTL_SET_L
14410 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 OCKPROXYFILE
14420 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 3.#define SQL
14430 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 ITE_FCNTL_LAST_E
14440 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 RRNO
14450 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 4.#define SQLI
14460 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 TE_FCNTL_SIZE_HI
14470 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 NT
14480 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 5.#define SQLIT
14490 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 E_FCNTL_CHUNK_SI
144a0 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ZE
144b0 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 6.#define SQLITE
144c0 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e _FCNTL_FILE_POIN
144d0 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 TER 7
144e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
144f0 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 FCNTL_SYNC_OMITT
14500 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a ED 8.
14510 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
14520 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 CNTL_WIN32_AV_RE
14530 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 TRY 9.#
14540 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
14550 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 NTL_PERSIST_WAL
14560 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 10.#d
14570 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
14580 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 TL_OVERWRITE
14590 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 11.#de
145a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
145b0 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 L_VFSNAME
145c0 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 12.#def
145d0 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
145e0 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 _POWERSAFE_OVERW
145f0 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 RITE 13.#defi
14600 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
14610 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 PRAGMA
14620 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 14.#defin
14630 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 e SQLITE_FCNTL_B
14640 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 USYHANDLER
14650 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 15.#define
14660 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 SQLITE_FCNTL_TE
14670 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 MPFILENAME
14680 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 16.#define
14690 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 SQLITE_FCNTL_MMA
146a0 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 P_SIZE
146b0 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 18.#define S
146c0 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 QLITE_FCNTL_TRAC
146d0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 E
146e0 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 19.#define SQ
146f0 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d LITE_FCNTL_HAS_M
14700 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20 OVED
14710 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 20.#define SQL
14720 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 ITE_FCNTL_SYNC
14730 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
14740 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 21.#define SQLI
14750 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f TE_FCNTL_COMMIT_
14760 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 PHASETWO
14770 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 22.#define SQLIT
14780 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 E_FCNTL_WIN32_SE
14790 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 T_HANDLE 2
147a0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
147b0 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b _FCNTL_WAL_BLOCK
147c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 24
147d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
147e0 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 FCNTL_ZIPVFS
147f0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 25.
14800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
14810 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 CNTL_RBU
14820 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 26.#
14830 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
14840 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 NTL_VFS_POINTER
14850 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23 64 27.#d
14860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
14870 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 TL_JOURNAL_POINT
14880 45 52 20 20 20 20 20 20 20 20 32 38 0a 23 64 65 ER 28.#de
14890 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
148a0 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 L_WIN32_GET_HAND
148b0 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64 65 66 LE 29.#def
148c0 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
148d0 5f 50 44 42 20 20 20 20 20 20 20 20 20 20 20 20 _PDB
148e0 20 20 20 20 20 20 20 20 33 30 0a 23 64 65 66 69 30.#defi
148f0 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
14900 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 BEGIN_ATOMIC_WRI
14910 54 45 20 20 20 20 20 33 31 0a 23 64 65 66 69 6e TE 31.#defin
14920 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 e SQLITE_FCNTL_C
14930 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 OMMIT_ATOMIC_WRI
14940 54 45 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 TE 32.#define
14950 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 4f SQLITE_FCNTL_RO
14960 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 52 LLBACK_ATOMIC_WR
14970 49 54 45 20 20 33 33 0a 23 64 65 66 69 6e 65 20 ITE 33.#define
14980 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 SQLITE_FCNTL_LOC
14990 4b 5f 54 49 4d 45 4f 55 54 20 20 20 20 20 20 20 K_TIMEOUT
149a0 20 20 20 20 33 34 0a 23 64 65 66 69 6e 65 20 53 34.#define S
149b0 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 QLITE_FCNTL_DATA
149c0 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 _VERSION
149d0 20 20 20 33 35 0a 0a 2f 2a 20 64 65 70 72 65 63 35../* deprec
149e0 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 ated names */.#d
149f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 efine SQLITE_GET
14a00 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
14a10 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c SQLITE_FCNTL
14a20 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 _GET_LOCKPROXYFI
14a30 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 LE.#define SQLIT
14a40 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 E_SET_LOCKPROXYF
14a50 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f ILE SQLITE_
14a60 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 FCNTL_SET_LOCKPR
14a70 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 OXYFILE.#define
14a80 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e SQLITE_LAST_ERRN
14a90 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51 O SQ
14aa0 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f LITE_FCNTL_LAST_
14ab0 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 ERRNO.../*.** CA
14ac0 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 PI3REF: Mutex Ha
14ad0 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d ndle.**.** The m
14ae0 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 utex module with
14af0 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 in SQLite define
14b00 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 s [sqlite3_mutex
14b10 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 ] to be an.** ab
14b20 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 stract type for
14b30 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 a mutex object.
14b40 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 The SQLite core
14b50 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 never looks.**
14b60 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 at the internal
14b70 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f representation o
14b80 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 f an [sqlite3_mu
14b90 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a tex]. It only.*
14ba0 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 * deals with poi
14bb0 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 nters to the [sq
14bc0 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a lite3_mutex] obj
14bd0 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 ect..**.** Mutex
14be0 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 es are created u
14bf0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 sing [sqlite3_mu
14c00 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f tex_alloc()]..*/
14c10 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 .typedef struct
14c20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 sqlite3_mutex sq
14c30 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a lite3_mutex;../*
14c40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f .** CAPI3REF: Lo
14c50 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e adable Extension
14c60 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 Thunk.**.** A p
14c70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70 ointer to the op
14c80 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69 aque sqlite3_api
14c90 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74 _routines struct
14ca0 75 72 65 20 69 73 20 70 61 73 73 65 64 20 61 73 ure is passed as
14cb0 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 .** the third pa
14cc0 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79 rameter to entry
14cd0 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 points of [load
14ce0 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d able extensions]
14cf0 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 . This.** struc
14d00 74 75 72 65 20 6d 75 73 74 20 62 65 20 74 79 70 ture must be typ
14d10 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20 edefed in order
14d20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 to work around c
14d30 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 ompiler warnings
14d40 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 .** on some plat
14d50 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 forms..*/.typede
14d60 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
14d70 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 _api_routines sq
14d80 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e lite3_api_routin
14d90 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 es;../*.** CAPI3
14da0 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 REF: OS Interfac
14db0 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 e Object.**.** A
14dc0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
14dd0 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 e sqlite3_vfs ob
14de0 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
14df0 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 interface betwe
14e00 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 en.** the SQLite
14e10 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e core and the un
14e20 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 derlying operati
14e30 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 ng system. The
14e40 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 "vfs".** in the
14e50 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 name of the obje
14e60 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 ct stands for "v
14e70 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 irtual file syst
14e80 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 em". See.** the
14e90 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 [VFS | VFS docu
14ea0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 mentation] for f
14eb0 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 urther informati
14ec0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 56 46 on..**.** The VF
14ed0 53 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 S interface is s
14ee0 6f 6d 65 74 69 6d 65 73 20 65 78 74 65 6e 64 65 ometimes extende
14ef0 64 20 62 79 20 61 64 64 69 6e 67 20 6e 65 77 20 d by adding new
14f00 6d 65 74 68 6f 64 73 20 6f 6e 74 6f 0a 2a 2a 20 methods onto.**
14f10 74 68 65 20 65 6e 64 2e 20 20 45 61 63 68 20 74 the end. Each t
14f20 69 6d 65 20 73 75 63 68 20 61 6e 20 65 78 74 65 ime such an exte
14f30 6e 73 69 6f 6e 20 6f 63 63 75 72 73 2c 20 74 68 nsion occurs, th
14f40 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 e iVersion field
14f50 0a 2a 2a 20 69 73 20 69 6e 63 72 65 6d 65 6e 74 .** is increment
14f60 65 64 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f ed. The iVersio
14f70 6e 20 76 61 6c 75 65 20 73 74 61 72 74 65 64 20 n value started
14f80 6f 75 74 20 61 73 20 31 20 69 6e 0a 2a 2a 20 53 out as 1 in.** S
14f90 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 QLite [version 3
14fa0 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 .5.0] on [dateof
14fb0 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 6e 20 69 6e :3.5.0], then in
14fc0 63 72 65 61 73 65 64 20 74 6f 20 32 0a 2a 2a 20 creased to 2.**
14fd0 77 69 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 with SQLite [ver
14fe0 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 6f 6e 20 5b sion 3.7.0] on [
14ff0 64 61 74 65 6f 66 3a 33 2e 37 2e 30 5d 2c 20 61 dateof:3.7.0], a
15000 6e 64 20 74 68 65 6e 20 69 6e 63 72 65 61 73 65 nd then increase
15010 64 0a 2a 2a 20 74 6f 20 33 20 77 69 74 68 20 53 d.** to 3 with S
15020 51 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 QLite [version 3
15030 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 74 65 6f 66 .7.6] on [dateof
15040 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 64 69 74 69 :3.7.6]. Additi
15050 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 6d onal fields.** m
15060 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 ay be appended t
15070 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 o the sqlite3_vf
15080 73 20 6f 62 6a 65 63 74 20 61 6e 64 20 74 68 65 s object and the
15090 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 0a iVersion value.
150a0 2a 2a 20 6d 61 79 20 69 6e 63 72 65 61 73 65 20 ** may increase
150b0 61 67 61 69 6e 20 69 6e 20 66 75 74 75 72 65 20 again in future
150c0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
150d0 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 te..** Note that
150e0 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a the structure.*
150f0 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 * of the sqlite3
15100 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e _vfs object chan
15110 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 ges in the trans
15120 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 53 51 ition from.** SQ
15130 4c 69 74 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e Lite [version 3.
15140 35 2e 39 5d 20 74 6f 20 5b 76 65 72 73 69 6f 6e 5.9] to [version
15150 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b 64 61 74 65 3.6.0] on [date
15160 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a 20 61 6e 64 of:3.6.0].** and
15170 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f yet the iVersio
15180 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 20 n field was not
15190 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 modified..**.**
151a0 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 The szOsFile fie
151b0 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f ld is the size o
151c0 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 f the subclassed
151d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a [sqlite3_file].
151e0 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 ** structure use
151f0 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 d by this VFS.
15200 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 mxPathname is th
15210 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 e maximum length
15220 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d of.** a pathnam
15230 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a e in this VFS..*
15240 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 *.** Registered
15250 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 sqlite3_vfs obje
15260 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 cts are kept on
15270 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f a linked list fo
15280 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 rmed by.** the p
15290 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 Next pointer. T
152a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f he [sqlite3_vfs_
152b0 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 register()].** a
152c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f nd [sqlite3_vfs_
152d0 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e unregister()] in
152e0 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 terfaces manage
152f0 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 this list.** in
15300 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 a thread-safe wa
15310 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 y. The [sqlite3
15320 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 _vfs_find()] int
15330 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 erface.** search
15340 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 es the list. Ne
15350 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 ither the applic
15360 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 ation code nor t
15370 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d he VFS.** implem
15380 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 entation should
15390 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f use the pNext po
153a0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 inter..**.** The
153b0 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 pNext field is
153c0 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 the only field i
153d0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 n the sqlite3_vf
153e0 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 s.** structure t
153f0 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
15400 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 ever modify. SQ
15410 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 Lite will only a
15420 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 ccess.** or modi
15430 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 fy this field wh
15440 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 ile holding a pa
15450 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 rticular static
15460 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 mutex..** The ap
15470 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 plication should
15480 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e never modify an
15490 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 ything within th
154a0 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a e sqlite3_vfs.**
154b0 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 object once the
154c0 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e object has been
154d0 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a registered..**.
154e0 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 ** The zName fie
154f0 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d ld holds the nam
15500 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 e of the VFS mod
15510 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d ule. The name m
15520 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 ust.** be unique
15530 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 across all VFS
15540 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b modules..**.** [
15550 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 [sqlite3_vfs.xOp
15560 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 en]].** ^SQLite
15570 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 guarantees that
15580 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 the zFilename pa
15590 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e rameter to xOpen
155a0 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 .** is either a
155b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 NULL pointer or
155c0 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a string obtained.
155d0 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 ** from xFullPat
155e0 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 hname() with an
155f0 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 optional suffix
15600 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 added..** ^If a
15610 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 suffix is added
15620 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 to the zFilename
15630 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 parameter, it w
15640 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f ill.** consist o
15650 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 f a single "-" c
15660 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 haracter followe
15670 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 d by no more tha
15680 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d n.** 11 alphanum
15690 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 eric and/or "-"
156a0 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e characters..** ^
156b0 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 SQLite further g
156c0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a uarantees that.*
156d0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c * the string wil
156e0 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 l be valid and u
156f0 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 nchanged until x
15700 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 Close() is.** ca
15710 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 lled. Because of
15720 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 the previous se
15730 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b ntence,.** the [
15740 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 sqlite3_file] ca
15750 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 n safely store a
15760 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a pointer to the.
15770 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 ** filename if i
15780 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d t needs to remem
15790 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 ber the filename
157a0 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e for some reason
157b0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c ..** If the zFil
157c0 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 ename parameter
157d0 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 to xOpen is a NU
157e0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
157f0 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e xOpen.** must in
15800 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d vent its own tem
15810 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 porary name for
15820 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e the file. ^When
15830 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 ever the .** xFi
15840 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 lename parameter
15850 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c is NULL it will
15860 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 also be the cas
15870 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c e that the.** fl
15880 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 ags parameter wi
15890 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 ll include [SQLI
158a0 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e TE_OPEN_DELETEON
158b0 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 CLOSE]..**.** Th
158c0 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 e flags argument
158d0 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c to xOpen() incl
158e0 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 udes all bits se
158f0 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 t in.** the flag
15900 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 s argument to [s
15910 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
15920 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 ]. Or if [sqlit
15930 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 e3_open()].** or
15940 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 [sqlite3_open16
15950 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 ()] is used, the
15960 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 n flags includes
15970 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 at least.** [SQ
15980 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 LITE_OPEN_READWR
15990 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f ITE] | [SQLITE_O
159a0 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a PEN_CREATE]. .**
159b0 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e If xOpen() open
159c0 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e s a file read-on
159d0 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 ly then it sets
159e0 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a *pOutFlags to.**
159f0 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 include [SQLITE
15a00 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e _OPEN_READONLY].
15a10 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 Other bits in
15a20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 *pOutFlags may b
15a30 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 e set..**.** ^(S
15a40 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 QLite will also
15a50 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 add one of the f
15a60 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 ollowing flags t
15a70 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a o the xOpen().**
15a80 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 call, depending
15a90 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 on the object b
15aa0 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a eing opened:.**.
15ab0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 ** <ul>.** <li>
15ac0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
15ad0 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 IN_DB].** <li>
15ae0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 [SQLITE_OPEN_MAI
15af0 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c N_JOURNAL].** <l
15b00 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
15b10 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 _TEMP_DB].** <li
15b20 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
15b30 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a TEMP_JOURNAL].**
15b40 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
15b50 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 PEN_TRANSIENT_DB
15b60 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
15b70 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e TE_OPEN_SUBJOURN
15b80 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 AL].** <li> [SQ
15b90 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 LITE_OPEN_MASTER
15ba0 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 _JOURNAL].** <li
15bb0 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f > [SQLITE_OPEN_
15bc0 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a WAL].** </ul>)^.
15bd0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 **.** The file I
15be0 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f /O implementatio
15bf0 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 n can use the ob
15c00 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 ject type flags
15c10 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 to.** change the
15c20 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 way it deals wi
15c30 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 th files. For e
15c40 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 xample, an appli
15c50 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 cation.** that d
15c60 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f oes not care abo
15c70 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 ut crash recover
15c80 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 y or rollback mi
15c90 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 ght make.** the
15ca0 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 open of a journa
15cb0 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 l file a no-op.
15cc0 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 Writes to this
15cd0 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a journal would.**
15ce0 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c also be no-ops,
15cf0 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 and any attempt
15d00 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 to read the jou
15d10 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 rnal would retur
15d20 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 n.** SQLITE_IOER
15d30 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 R. Or the imple
15d40 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 mentation might
15d50 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 recognize that a
15d60 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c database.** fil
15d70 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 e will be doing
15d80 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 page-aligned sec
15d90 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 tor reads and wr
15da0 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d ites in a random
15db0 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 .** order and se
15dc0 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 t up its I/O sub
15dd0 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 system according
15de0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ly..**.** SQLite
15df0 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 might also add
15e00 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f one of the follo
15e10 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 wing flags to th
15e20 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a e xOpen method:.
15e30 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c **.** <ul>.** <l
15e40 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f i> [SQLITE_OPEN_
15e50 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a DELETEONCLOSE].*
15e60 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f * <li> [SQLITE_O
15e70 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a PEN_EXCLUSIVE].*
15e80 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 * </ul>.**.** Th
15e90 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 e [SQLITE_OPEN_D
15ea0 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c ELETEONCLOSE] fl
15eb0 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c ag means the fil
15ec0 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 e should be.** d
15ed0 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 eleted when it i
15ee0 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 s closed. ^The
15ef0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c [SQLITE_OPEN_DEL
15f00 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 ETEONCLOSE].** w
15f10 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 ill be set for T
15f20 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e EMP databases an
15f30 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 d their journals
15f40 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 , transient.** d
15f50 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 atabases, and su
15f60 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a bjournals..**.**
15f70 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 ^The [SQLITE_OP
15f80 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c EN_EXCLUSIVE] fl
15f90 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 ag is always use
15fa0 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e d in conjunction
15fb0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 .** with the [SQ
15fc0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
15fd0 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 ] flag, which ar
15fe0 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a e both directly.
15ff0 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 ** analogous to
16000 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f the O_EXCL and O
16010 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 _CREAT flags of
16020 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 the POSIX open()
16030 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 .** API. The SQ
16040 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 LITE_OPEN_EXCLUS
16050 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 IVE flag, when p
16060 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a aired with the .
16070 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 ** SQLITE_OPEN_C
16080 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 REATE, is used t
16090 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 o indicate that
160a0 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 file should alwa
160b0 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 ys.** be created
160c0 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 , and that it is
160d0 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 an error if it
160e0 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a already exists..
160f0 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c ** It is <i>not<
16100 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 /i> used to indi
16110 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 cate the file sh
16120 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a ould be opened .
16130 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 ** for exclusive
16140 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e access..**.** ^
16150 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c At least szOsFil
16160 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 e bytes of memor
16170 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 y are allocated
16180 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 by SQLite.** to
16190 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 hold the [sqlit
161a0 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 e3_file] structu
161b0 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 re passed as the
161c0 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 third.** argume
161d0 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 nt to xOpen. Th
161e0 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 e xOpen method d
161f0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a oes not have to.
16200 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 ** allocate the
16210 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 structure; it sh
16220 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 ould just fill i
16230 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 t in. Note that
16240 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 .** the xOpen me
16250 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 thod must set th
16260 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 e sqlite3_file.p
16270 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 Methods to eithe
16280 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 r.** a valid [sq
16290 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
162a0 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e ] object or to N
162b0 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 ULL. xOpen must
162c0 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e do.** this even
162d0 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 if the open fai
162e0 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 ls. SQLite expe
162f0 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c cts that the sql
16300 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
16310 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 ds.** element wi
16320 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 ll be valid afte
16330 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 r xOpen returns
16340 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 regardless of th
16350 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 e success.** or
16360 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 failure of the x
16370 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a Open call..**.**
16380 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 [[sqlite3_vfs.x
16390 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 Access]].** ^The
163a0 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
163b0 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 to xAccess() may
163c0 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 be [SQLITE_ACCE
163d0 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f SS_EXISTS].** to
163e0 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 test for the ex
163f0 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c istence of a fil
16400 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 e, or [SQLITE_AC
16410 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 CESS_READWRITE]
16420 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 to.** test wheth
16430 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 er a file is rea
16440 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 dable and writab
16450 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 le, or [SQLITE_A
16460 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 CCESS_READ].** t
16470 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 o test whether a
16480 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 file is at leas
16490 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 t readable. Th
164a0 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a e file can be a.
164b0 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a ** directory..**
164c0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c .** ^SQLite will
164d0 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 always allocate
164e0 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 at least mxPath
164f0 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 name+1 bytes for
16500 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 the.** output b
16510 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e uffer xFullPathn
16520 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 ame. The exact
16530 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 size of the outp
16540 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 ut buffer.** is
16550 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 also passed as a
16560 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f parameter to bo
16570 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 th methods. If
16580 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 the output buffe
16590 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 r.** is not larg
165a0 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 e enough, [SQLIT
165b0 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 E_CANTOPEN] shou
165c0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 ld be returned.
165d0 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a Since this is.**
165e0 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 handled as a fa
165f0 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c tal error by SQL
16600 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 ite, vfs impleme
16610 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 ntations should
16620 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 endeavor.** to p
16630 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 revent this by s
16640 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d etting mxPathnam
16650 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e e to a sufficien
16660 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e tly large value.
16670 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 .**.** The xRand
16680 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 omness(), xSleep
16690 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 (), xCurrentTime
166a0 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 (), and xCurrent
166b0 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 TimeInt64().** i
166c0 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f nterfaces are no
166d0 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 t strictly a par
166e0 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 t of the filesys
166f0 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 tem, but they ar
16700 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e e.** included in
16710 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 the VFS structu
16720 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e re for completen
16730 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e ess..** The xRan
16740 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 domness() functi
16750 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 on attempts to r
16760 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 eturn nBytes byt
16770 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 es.** of good-qu
16780 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 ality randomness
16790 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 into zOut. The
167a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 return value is
167b0 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e .** the actual n
167c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f umber of bytes o
167d0 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 f randomness obt
167e0 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 ained..** The xS
167f0 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 leep() method ca
16800 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 uses the calling
16810 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 thread to sleep
16820 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 for at.** least
16830 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d the number of m
16840 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 icroseconds give
16850 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e n. ^The xCurren
16860 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f tTime().** metho
16870 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 d returns a Juli
16880 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f an Day Number fo
16890 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 r the current da
168a0 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a te and time as.*
168b0 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 * a floating poi
168c0 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 nt value..** ^Th
168d0 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e e xCurrentTimeIn
168e0 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 t64() method ret
168f0 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 urns, as an inte
16900 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a ger, the Julian.
16910 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 ** Day Number mu
16920 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 ltiplied by 8640
16930 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 0000 (the number
16940 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 of milliseconds
16950 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 in .** a 24-hou
16960 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 r day). .** ^SQ
16970 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 Lite will use th
16980 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e e xCurrentTimeIn
16990 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 t64() method to
169a0 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a get the current.
169b0 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 ** date and time
169c0 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 if that method
169d0 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 is available (if
169e0 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f iVersion is 2 o
169f0 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e r .** greater an
16a00 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 d the function p
16a10 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 ointer is not NU
16a20 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c LL) and will fal
16a30 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 l back.** to xCu
16a40 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 rrentTime() if x
16a50 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 CurrentTimeInt64
16a60 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c () is unavailabl
16a70 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 e..**.** ^The xS
16a80 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 etSystemCall(),
16a90 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 xGetSystemCall()
16aa0 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 , and xNestSyste
16ab0 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 mCall() interfac
16ac0 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 es.** are not us
16ad0 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 ed by the SQLite
16ae0 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 core. These op
16af0 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 tional interface
16b00 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a s are provided.*
16b10 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 * by some VFSes
16b20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 to facilitate te
16b30 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 sting of the VFS
16b40 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 code. By overri
16b50 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 ding .** system
16b60 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 calls with funct
16b70 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 ions under its c
16b80 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 ontrol, a test p
16b90 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 rogram can.** si
16ba0 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e mulate faults an
16bb0 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f d error conditio
16bc0 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 ns that would ot
16bd0 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 herwise be diffi
16be0 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 cult.** or impos
16bf0 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e sible to induce.
16c00 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 The set of sys
16c10 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 tem calls that c
16c20 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e an be overridden
16c30 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 .** varies from
16c40 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 one VFS to anoth
16c50 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 er, and from one
16c60 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 version of the
16c70 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a same VFS to the.
16c80 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 ** next. Applic
16c90 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 ations that use
16ca0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 these interfaces
16cb0 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 must be prepare
16cc0 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 d for any.** or
16cd0 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 all of these int
16ce0 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 erfaces to be NU
16cf0 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 LL or for their
16d00 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e behavior to chan
16d10 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 ge.** from one r
16d20 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 elease to the ne
16d30 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e xt. Application
16d40 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d s must not attem
16d50 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 pt to access.**
16d60 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 any of these met
16d70 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 hods if the iVer
16d80 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 sion of the VFS
16d90 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a is less than 3..
16da0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 */.typedef struc
16db0 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 t sqlite3_vfs sq
16dc0 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 lite3_vfs;.typed
16dd0 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 ef void (*sqlite
16de0 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 3_syscall_ptr)(v
16df0 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c oid);.struct sql
16e00 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 ite3_vfs {. int
16e10 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 iVersion;
16e20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 /* Structu
16e30 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 re version numbe
16e40 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 r (currently 3)
16e50 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c */. int szOsFil
16e60 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a e; /*
16e70 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 Size of subclas
16e80 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 sed sqlite3_file
16e90 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 */. int mxPath
16ea0 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f name; /
16eb0 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 * Maximum file p
16ec0 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a athname length *
16ed0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 /. sqlite3_vfs
16ee0 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 *pNext; /*
16ef0 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 Next registered
16f00 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 VFS */. const c
16f10 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 har *zName;
16f20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 /* Name of thi
16f30 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 s virtual file s
16f40 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 ystem */. void
16f50 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 *pAppData;
16f60 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 /* Pointer t
16f70 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 o application-sp
16f80 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 ecific data */.
16f90 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 int (*xOpen)(sq
16fa0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
16fb0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 t char *zName, s
16fc0 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 qlite3_file*,.
16fd0 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 int
16fe0 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 flags, int *pOu
16ff0 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 tFlags);. int (
17000 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 *xDelete)(sqlite
17010 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
17020 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 ar *zName, int s
17030 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 yncDir);. int (
17040 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 *xAccess)(sqlite
17050 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
17060 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 ar *zName, int f
17070 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f lags, int *pResO
17080 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 ut);. int (*xFu
17090 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 llPathname)(sqli
170a0 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 te3_vfs*, const
170b0 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 char *zName, int
170c0 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 nOut, char *zOu
170d0 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 t);. void *(*xD
170e0 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 lOpen)(sqlite3_v
170f0 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
17100 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 *zFilename);. v
17110 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 oid (*xDlError)(
17120 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e sqlite3_vfs*, in
17130 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a t nByte, char *z
17140 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 ErrMsg);. void
17150 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 (*(*xDlSym)(sqli
17160 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 te3_vfs*,void*,
17170 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d const char *zSym
17180 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 bol))(void);. v
17190 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 oid (*xDlClose)(
171a0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f sqlite3_vfs*, vo
171b0 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 id*);. int (*xR
171c0 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 andomness)(sqlit
171d0 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 e3_vfs*, int nBy
171e0 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b te, char *zOut);
171f0 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 . int (*xSleep)
17200 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 (sqlite3_vfs*, i
17210 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 nt microseconds)
17220 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 ;. int (*xCurre
17230 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f ntTime)(sqlite3_
17240 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a vfs*, double*);.
17250 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 int (*xGetLast
17260 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 Error)(sqlite3_v
17270 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a fs*, int, char *
17280 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 );. /*. ** The
17290 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 methods above a
172a0 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 re in version 1
172b0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 of the sqlite_vf
172c0 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 s object. ** de
172d0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 finition. Those
172e0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 that follow are
172f0 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f added in versio
17300 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a n 2 or later. *
17310 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 /. int (*xCurre
17320 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c ntTimeInt64)(sql
17330 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 ite3_vfs*, sqlit
17340 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a e3_int64*);. /*
17350 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 . ** The method
17360 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 s above are in v
17370 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 ersions 1 and 2
17380 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 of the sqlite_vf
17390 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 s object.. ** T
173a0 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 hose below are f
173b0 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 or version 3 and
173c0 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 greater.. */.
173d0 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 int (*xSetSyste
173e0 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 mCall)(sqlite3_v
173f0 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 fs*, const char
17400 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f *zName, sqlite3_
17410 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 syscall_ptr);.
17420 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f sqlite3_syscall_
17430 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d ptr (*xGetSystem
17440 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 Call)(sqlite3_vf
17450 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a s*, const char *
17460 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 zName);. const
17470 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 char *(*xNextSys
17480 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 temCall)(sqlite3
17490 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 _vfs*, const cha
174a0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a r *zName);. /*.
174b0 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 ** The methods
174c0 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 above are in ve
174d0 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 rsions 1 through
174e0 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 3 of the sqlite
174f0 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a _vfs object.. *
17500 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 * New fields may
17510 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 be appended in
17520 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 2e future versions.
17530 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 The iVersion.
17540 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 ** value will i
17550 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 ncrement wheneve
17560 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 r this happens.
17570 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 . */.};../*.**
17580 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 CAPI3REF: Flags
17590 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 for the xAccess
175a0 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a VFS method.**.**
175b0 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 These integer c
175c0 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 onstants can be
175d0 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 used as the thir
175e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a d parameter to.*
175f0 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 * the xAccess me
17600 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 thod of an [sqli
17610 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e te3_vfs] object.
17620 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 They determine
17630 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 .** what kind of
17640 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 permissions the
17650 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 xAccess method
17660 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a is looking for..
17670 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
17680 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 CCESS_EXISTS, th
17690 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 e xAccess method
176a0 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b .** simply check
176b0 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 s whether the fi
176c0 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 le exists..** Wi
176d0 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 th SQLITE_ACCESS
176e0 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 _READWRITE, the
176f0 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
17700 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 * checks whether
17710 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 the named direc
17720 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 tory is both rea
17730 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 dable and writab
17740 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 le.** (in other
17750 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 words, if files
17760 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 can be added, re
17770 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d moved, and renam
17780 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 ed within.** the
17790 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 directory)..**
177a0 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 The SQLITE_ACCES
177b0 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 S_READWRITE cons
177c0 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c tant is currentl
177d0 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 y used only by t
177e0 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 he.** [temp_stor
177f0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 e_directory prag
17800 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 ma], though this
17810 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e could change in
17820 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c a future.** rel
17830 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a ease of SQLite..
17840 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 ** With SQLITE_A
17850 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 CCESS_READ, the
17860 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a xAccess method.*
17870 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 * checks whether
17880 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 the file is rea
17890 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 dable. The SQLI
178a0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 TE_ACCESS_READ c
178b0 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 onstant is.** cu
178c0 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 rrently unused,
178d0 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 though it might
178e0 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 be used in a fut
178f0 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a ure release of.*
17900 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 * SQLite..*/.#de
17910 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
17920 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 SS_EXISTS 0.#
17930 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 define SQLITE_AC
17940 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 CESS_READWRITE 1
17950 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 /* Used by PR
17960 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f AGMA temp_store_
17970 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 directory */.#de
17980 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 fine SQLITE_ACCE
17990 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 SS_READ 2
179a0 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f /* Unused */../
179b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 *.** CAPI3REF: F
179c0 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 lags for the xSh
179d0 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 mLock VFS method
179e0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 .**.** These int
179f0 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 eger constants d
17a00 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 efine the variou
17a10 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 s locking operat
17a20 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 ions.** allowed
17a30 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 by the xShmLock
17a40 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 method of [sqlit
17a50 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 e3_io_methods].
17a60 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e The.** followin
17a70 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c g are the only l
17a80 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e egal combination
17a90 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 s of flags to th
17aa0 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 e.** xShmLock me
17ab0 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e thod:.**.** <ul>
17ac0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
17ad0 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 _SHM_LOCK | SQLI
17ae0 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a TE_SHM_SHARED.**
17af0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
17b00 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f M_LOCK | SQLITE_
17b10 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a SHM_EXCLUSIVE.**
17b20 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 <li> SQLITE_SH
17b30 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 M_UNLOCK | SQLIT
17b40 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 E_SHM_SHARED.**
17b50 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d <li> SQLITE_SHM
17b60 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 _UNLOCK | SQLITE
17b70 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a _SHM_EXCLUSIVE.*
17b80 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 * </ul>.**.** Wh
17b90 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 en unlocking, th
17ba0 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 e same SHARED or
17bb0 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 EXCLUSIVE flag
17bc0 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 must be supplied
17bd0 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e as.** was given
17be0 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f on the correspo
17bf0 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a nding lock. .**
17c00 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b .** The xShmLock
17c10 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e method can tran
17c20 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 sition between u
17c30 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 nlocked and SHAR
17c40 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e ED or.** between
17c50 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 unlocked and EX
17c60 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e CLUSIVE. It can
17c70 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 not transition b
17c80 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a etween SHARED.**
17c90 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a and EXCLUSIVE..
17ca0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
17cb0 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 E_SHM_UNLOCK
17cc0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 1.#define SQL
17cd0 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 ITE_SHM_LOCK
17ce0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 2.#define S
17cf0 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
17d00 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 4.#define
17d10 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c SQLITE_SHM_EXCL
17d20 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a USIVE 8../*.*
17d30 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 * CAPI3REF: Maxi
17d40 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 mum xShmLock ind
17d50 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 ex.**.** The xSh
17d60 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 mLock method on
17d70 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
17d80 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c ods] may use val
17d90 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 ues.** between 0
17da0 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 and this upper
17db0 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 bound as its "of
17dc0 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a fset" argument..
17dd0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f ** The SQLite co
17de0 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 re will never at
17df0 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 tempt to acquire
17e00 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a or release a.**
17e10 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 lock outside of
17e20 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 this range.*/.#
17e30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 define SQLITE_SH
17e40 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 M_NLOCK 8
17e50 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 .../*.** CAPI3RE
17e60 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 F: Initialize Th
17e70 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 e SQLite Library
17e80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
17e90 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
17ea0 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c routine initial
17eb0 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 izes the.** SQLi
17ec0 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 te library. ^Th
17ed0 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f e sqlite3_shutdo
17ee0 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 wn() routine.**
17ef0 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 deallocates any
17f00 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 resources that w
17f10 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 ere allocated by
17f20 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
17f30 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 ize()..** These
17f40 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 routines are des
17f50 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 igned to aid in
17f60 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 process initiali
17f70 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 zation and.** sh
17f80 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 utdown on embedd
17f90 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 ed systems. Wor
17fa0 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 kstation applica
17fb0 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 tions using.** S
17fc0 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 QLite normally d
17fd0 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e o not need to in
17fe0 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 voke either of t
17ff0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a hese routines..*
18000 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 *.** A call to s
18010 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
18020 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 e() is an "effec
18030 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 tive" call if it
18040 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 is.** the first
18050 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e time sqlite3_in
18060 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e itialize() is in
18070 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 voked during the
18080 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 lifetime of.**
18090 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 the process, or
180a0 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 if it is the fir
180b0 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f st time sqlite3_
180c0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 initialize() is
180d0 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f invoked.** follo
180e0 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 wing a call to s
180f0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
18100 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 ). ^(Only an ef
18110 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 fective call.**
18120 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 of sqlite3_initi
18130 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 alize() does any
18140 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e initialization.
18150 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c All other call
18160 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 s.** are harmles
18170 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a s no-ops.)^.**.*
18180 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 * A call to sqli
18190 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 te3_shutdown() i
181a0 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 s an "effective"
181b0 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 call if it is t
181c0 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c he first.** call
181d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 to sqlite3_shut
181e0 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 down() since the
181f0 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e last sqlite3_in
18200 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f itialize(). ^(O
18210 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 nly.** an effect
18220 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 ive call to sqli
18230 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 te3_shutdown() d
18240 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 oes any deinitia
18250 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c lization..** All
18260 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c other valid cal
18270 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 ls to sqlite3_sh
18280 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 utdown() are har
18290 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a mless no-ops.)^.
182a0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
182b0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
182c0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 nterface is thre
182d0 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 adsafe, but sqli
182e0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a te3_shutdown().*
182f0 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 * is not. The s
18300 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 qlite3_shutdown(
18310 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 ) interface must
18320 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 only be called
18330 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 from a.** single
18340 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 thread. All op
18350 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e en [database con
18360 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 nections] must b
18370 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c e closed and all
18380 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 .** other SQLite
18390 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 resources must
183a0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 be deallocated p
183b0 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 rior to invoking
183c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 .** sqlite3_shut
183d0 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d down()..**.** Am
183e0 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 ong other things
183f0 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 , ^sqlite3_initi
18400 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 alize() will inv
18410 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f oke.** sqlite3_o
18420 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c s_init(). Simil
18430 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 arly, ^sqlite3_s
18440 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c hutdown().** wil
18450 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 l invoke sqlite3
18460 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a _os_end()..**.**
18470 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e ^The sqlite3_in
18480 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 itialize() routi
18490 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ne returns [SQLI
184a0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
184b0 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f s..** ^If for so
184c0 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 me reason, sqlit
184d0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 e3_initialize()
184e0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 is unable to ini
184f0 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c tialize.** the l
18500 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 ibrary (perhaps
18510 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 it is unable to
18520 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 allocate a neede
18530 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a d resource such.
18540 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 ** as a mutex) i
18550 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 t returns an [er
18560 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 ror code] other
18570 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d than [SQLITE_OK]
18580 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
18590 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 ite3_initialize(
185a0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c ) routine is cal
185b0 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 led internally b
185c0 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 y many other.**
185d0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 SQLite interface
185e0 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 s so that an app
185f0 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 lication usually
18600 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
18610 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 o.** invoke sqli
18620 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
18630 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 directly. For
18640 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 example, [sqlite
18650 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 3_open()].** cal
18660 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ls sqlite3_initi
18670 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 alize() so the S
18680 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 QLite library wi
18690 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 ll be automatica
186a0 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a lly.** initializ
186b0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
186c0 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c _open()] is call
186d0 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 ed if it has not
186e0 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a be initialized.
186f0 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f ** already. ^Ho
18700 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 wever, if SQLite
18710 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
18720 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d h the [SQLITE_OM
18730 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 IT_AUTOINIT].**
18740 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
18750 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 ion, then the au
18760 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f tomatic calls to
18770 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
18780 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 ize().** are omi
18790 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 tted and the app
187a0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 lication must ca
187b0 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 ll sqlite3_initi
187c0 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 alize() directly
187d0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 .** prior to usi
187e0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c ng any other SQL
187f0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 ite interface.
18800 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 For maximum port
18810 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 ability,.** it i
18820 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 s recommended th
18830 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 at applications
18840 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 always invoke sq
18850 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
18860 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 ().** directly p
18870 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e rior to using an
18880 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 y other SQLite i
18890 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 nterface. Futur
188a0 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 e releases.** of
188b0 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 SQLite may requ
188c0 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 ire this. In ot
188d0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 her words, the b
188e0 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 ehavior exhibite
188f0 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 d.** when SQLite
18900 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
18910 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 h [SQLITE_OMIT_A
18920 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 UTOINIT] might b
18930 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 ecome the.** def
18940 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e ault behavior in
18950 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c some future rel
18960 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a ease of SQLite..
18970 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 **.** The sqlite
18980 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 3_os_init() rout
18990 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 ine does operati
189a0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 ng-system specif
189b0 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 ic.** initializa
189c0 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 tion of the SQLi
189d0 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 te library. The
189e0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
189f0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 ).** routine und
18a00 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f oes the effect o
18a10 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 f sqlite3_os_ini
18a20 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 t(). Typical ta
18a30 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 sks.** performed
18a40 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e by these routin
18a50 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 es include alloc
18a60 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 ation or dealloc
18a70 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 ation.** of stat
18a80 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e ic resources, in
18a90 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 itialization of
18aa0 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 global variables
18ab0 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 ,.** setting up
18ac0 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 a default [sqlit
18ad0 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 e3_vfs] module,
18ae0 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a or setting up.**
18af0 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 a default confi
18b00 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b guration using [
18b10 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
18b20 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 ]..**.** The app
18b30 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 lication should
18b40 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 never invoke eit
18b50 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 her sqlite3_os_i
18b60 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 nit().** or sqli
18b70 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 te3_os_end() dir
18b80 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c ectly. The appl
18b90 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f ication should o
18ba0 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 nly invoke.** sq
18bb0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
18bc0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 () and sqlite3_s
18bd0 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 hutdown(). The
18be0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
18bf0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 ).** interface i
18c00 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 s called automat
18c10 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 ically by sqlite
18c20 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 3_initialize() a
18c30 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 nd.** sqlite3_os
18c40 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 _end() is called
18c50 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 by sqlite3_shut
18c60 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 down(). Appropr
18c70 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e iate.** implemen
18c80 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 tations for sqli
18c90 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e te3_os_init() an
18ca0 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 d sqlite3_os_end
18cb0 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 ().** are built
18cc0 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e into SQLite when
18cd0 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 it is compiled
18ce0 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 for Unix, Window
18cf0 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 s, or OS/2..** W
18d00 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c hen [custom buil
18d10 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f ds | built for o
18d20 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a ther platforms].
18d30 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 ** (using the [S
18d40 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 QLITE_OS_OTHER=1
18d50 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a ] compile-time.*
18d60 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 * option) the ap
18d70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 plication must s
18d80 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 upply a suitable
18d90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 implementation
18da0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f for.** sqlite3_o
18db0 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c s_init() and sql
18dc0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 ite3_os_end().
18dd0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 An application-s
18de0 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 upplied.** imple
18df0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c mentation of sql
18e00 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f ite3_os_init() o
18e10 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 r sqlite3_os_end
18e20 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 ().** must retur
18e30 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e n [SQLITE_OK] on
18e40 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d success and som
18e50 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 e other [error c
18e60 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 ode] upon.** fai
18e70 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f lure..*/.SQLITE_
18e80 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
18e90 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 initialize(void)
18ea0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
18eb0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 sqlite3_shutdow
18ec0 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f n(void);.SQLITE_
18ed0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
18ee0 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 os_init(void);.S
18ef0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
18f00 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 lite3_os_end(voi
18f10 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 d);../*.** CAPI3
18f20 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 REF: Configuring
18f30 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 The SQLite Libr
18f40 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 ary.**.** The sq
18f50 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
18f60 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 nterface is used
18f70 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 to make global
18f80 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a configuration.**
18f90 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 changes to SQLi
18fa0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 te in order to t
18fb0 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 une SQLite to th
18fc0 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 e specific needs
18fd0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 of.** the appli
18fe0 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 cation. The def
18ff0 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 ault configurati
19000 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 on is recommende
19010 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 d for most.** ap
19020 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 plications and s
19030 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 o this routine i
19040 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 s usually not ne
19050 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a cessary. It is.
19060 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 ** provided to s
19070 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c upport rare appl
19080 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e ications with un
19090 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a usual needs..**.
190a0 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74 65 ** <b>The sqlite
190b0 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 3_config() inter
190c0 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 face is not thre
190d0 61 64 73 61 66 65 2e 20 54 68 65 20 61 70 70 6c adsafe. The appl
190e0 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 ication.** must
190f0 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f ensure that no o
19100 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 ther SQLite inte
19110 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b rfaces are invok
19120 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 ed by other.** t
19130 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c hreads while sql
19140 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 ite3_config() is
19150 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a running.</b>.**
19160 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
19170 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 config() interfa
19180 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 ce.** may only b
19190 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 e invoked prior
191a0 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 to library initi
191b0 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a alization using.
191c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 ** [sqlite3_init
191d0 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 ialize()] or aft
191e0 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b er shutdown by [
191f0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
19200 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 ()]..** ^If sqli
19210 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 te3_config() is
19220 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 called after [sq
19230 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
19240 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a ()] and before.*
19250 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 * [sqlite3_shutd
19260 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 own()] then it w
19270 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 ill return SQLIT
19280 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 E_MISUSE..** Not
19290 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 e, however, that
192a0 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 ^sqlite3_config
192b0 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 () can be called
192c0 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a as part of the.
192d0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f ** implementatio
192e0 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 n of an applicat
192f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c ion-defined [sql
19300 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e ite3_os_init()].
19310 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 .**.** The first
19320 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c argument to sql
19330 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 ite3_config() is
19340 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b an integer.** [
19350 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
19360 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 tion] that deter
19370 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 mines.** what pr
19380 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 operty of SQLite
19390 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 is to be config
193a0 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e ured. Subsequen
193b0 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 t arguments.** v
193c0 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e ary depending on
193d0 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 the [configurat
193e0 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 ion option].** i
193f0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 n the first argu
19400 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 ment..**.** ^Whe
19410 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f n a configuratio
19420 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c n option is set,
19430 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
19440 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 ) returns [SQLIT
19450 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 E_OK]..** ^If th
19460 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e e option is unkn
19470 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 own or SQLite is
19480 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 unable to set t
19490 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 he option.** the
194a0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 n this routine r
194b0 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 eturns a non-zer
194c0 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a o [error code]..
194d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
194e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 t sqlite3_config
194f0 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a (int, ...);../*.
19500 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e ** CAPI3REF: Con
19510 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 figure database
19520 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d connections.** M
19530 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
19540 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 *.** The sqlite3
19550 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 _db_config() int
19560 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
19570 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 o make configura
19580 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 tion.** changes
19590 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 to a [database c
195a0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 onnection]. The
195b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 interface is si
195c0 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c milar to.** [sql
195d0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 ite3_config()] e
195e0 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 xcept that the c
195f0 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 hanges apply to
19600 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 a single.** [dat
19610 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
19620 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 ] (specified in
19630 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 the first argume
19640 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 nt)..**.** The s
19650 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 econd argument t
19660 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
19670 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 fig(D,V,...) is
19680 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f the.** [SQLITE_
19690 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
196a0 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 DE | configurati
196b0 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e on verb] - an in
196c0 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 teger code .** t
196d0 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 hat indicates wh
196e0 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 at aspect of the
196f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
19700 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 ction] is being
19710 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 configured..** S
19720 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 ubsequent argume
19730 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 nts vary dependi
19740 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 ng on the config
19750 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a uration verb..**
19760 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 .** ^Calls to sq
19770 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
19780 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f ) return SQLITE_
19790 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 OK if and only i
197a0 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 f.** the call is
197b0 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 considered succ
197c0 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 essful..*/.SQLIT
197d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
197e0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 3_db_config(sqli
197f0 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e te3*, int op, ..
19800 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .);../*.** CAPI3
19810 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f REF: Memory Allo
19820 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a cation Routines.
19830 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 **.** An instanc
19840 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
19850 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 defines the int
19860 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 erface between S
19870 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 QLite.** and low
19880 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c -level memory al
19890 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
198a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 s..**.** This ob
198b0 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 ject is used in
198c0 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 only one place i
198d0 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 n the SQLite int
198e0 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 erface..** A poi
198f0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
19900 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
19910 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 ct is the argume
19920 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 nt to.** [sqlite
19930 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 3_config()] when
19940 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 the configurati
19950 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 on option is.**
19960 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
19970 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 ALLOC] or [SQLIT
19980 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c E_CONFIG_GETMALL
19990 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 OC]. .** By cre
199a0 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 ating an instanc
199b0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 e of this object
199c0 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 .** and passing
199d0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 it to [sqlite3_c
199e0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 onfig]([SQLITE_C
199f0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a ONFIG_MALLOC]).*
19a00 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 * during configu
19a10 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 ration, an appli
19a20 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 cation can speci
19a30 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 fy an alternativ
19a40 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f e.** memory allo
19a50 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d cation subsystem
19a60 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 for SQLite to u
19a70 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 se for all of it
19a80 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d s.** dynamic mem
19a90 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a ory needs..**.**
19aa0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 Note that SQLit
19ab0 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 e comes with sev
19ac0 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d eral [built-in m
19ad0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 emory allocators
19ae0 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 ].** that are pe
19af0 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 rfectly adequate
19b00 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 for the overwhe
19b10 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f lming majority o
19b20 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a f applications.*
19b30 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 * and that this
19b40 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 object is only u
19b50 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 seful to a tiny
19b60 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c minority of appl
19b70 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 ications.** with
19b80 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d specialized mem
19b90 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 ory allocation r
19ba0 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 equirements. Th
19bb0 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 is object is.**
19bc0 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 also used during
19bd0 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 testing of SQLi
19be0 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 te in order to s
19bf0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
19c00 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
19c10 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 allocator that s
19c20 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 imulates memory
19c30 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f out-of-memory co
19c40 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f nditions in.** o
19c50 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 rder to verify t
19c60 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 hat SQLite recov
19c70 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 ers gracefully f
19c80 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 rom such.** cond
19c90 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 itions..**.** Th
19ca0 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c e xMalloc, xReal
19cb0 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d loc, and xFree m
19cc0 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b ethods must work
19cd0 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c like the.** mal
19ce0 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 loc(), realloc()
19cf0 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 and free() func
19d00 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 tions from the s
19d10 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 tandard C librar
19d20 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 y..** ^SQLite gu
19d30 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 arantees that th
19d40 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
19d50 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 t to.** xRealloc
19d60 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c is always a val
19d70 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 ue returned by a
19d80 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 prior call to x
19d90 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 Roundup..**.** x
19da0 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 Size should retu
19db0 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 rn the allocated
19dc0 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 size of a memor
19dd0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 y allocation.**
19de0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 previously obtai
19df0 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 ned from xMalloc
19e00 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 or xRealloc. T
19e10 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a he allocated siz
19e20 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 e.** is always a
19e30 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 t least as big a
19e40 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 s the requested
19e50 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 size but may be
19e60 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 larger..**.** Th
19e70 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f e xRoundup metho
19e80 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 d returns what w
19e90 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f ould be the allo
19ea0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a cated size of.**
19eb0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 a memory alloca
19ec0 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 tion given a par
19ed0 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 ticular requeste
19ee0 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 d size. Most me
19ef0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
19f00 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f rs round up memo
19f10 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 ry allocations a
19f20 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e t least to the n
19f30 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 ext multiple.**
19f40 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f of 8. Some allo
19f50 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
19f60 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 to a larger mult
19f70 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 iple or to a pow
19f80 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 er of 2..** Ever
19f90 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 y memory allocat
19fa0 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 ion request comi
19fb0 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 ng in through [s
19fc0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
19fd0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f .** or [sqlite3_
19fe0 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 realloc()] first
19ff0 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e calls xRoundup.
1a000 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 If xRoundup re
1a010 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 turns 0, .** tha
1a020 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 t causes the cor
1a030 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 responding memor
1a040 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 y allocation to
1a050 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 fail..**.** The
1a060 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 xInit method ini
1a070 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d tializes the mem
1a080 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 ory allocator.
1a090 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 For example,.**
1a0a0 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 it might allocat
1a0b0 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 e any require mu
1a0c0 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c texes or initial
1a0d0 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 ize internal dat
1a0e0 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e a.** structures.
1a0f0 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 The xShutdown
1a100 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 method is invoke
1a110 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 d (indirectly) b
1a120 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 y.** [sqlite3_sh
1a130 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 utdown()] and sh
1a140 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 ould deallocate
1a150 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 any resources ac
1a160 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e quired.** by xIn
1a170 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 it. The pAppDat
1a180 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 a pointer is use
1a190 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 d as the only pa
1a1a0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 rameter to.** xI
1a1b0 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 nit and xShutdow
1a1c0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 n..**.** SQLite
1a1d0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 holds the [SQLIT
1a1e0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d E_MUTEX_STATIC_M
1a1f0 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 ASTER] mutex whe
1a200 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 n it invokes.**
1a210 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 the xInit method
1a220 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d , so the xInit m
1a230 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 ethod need not b
1a240 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 e threadsafe. T
1a250 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 he.** xShutdown
1a260 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 method is only c
1a270 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 alled from [sqli
1a280 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 te3_shutdown()]
1a290 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f so it does.** no
1a2a0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 t need to be thr
1a2b0 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 eadsafe either.
1a2c0 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d For all other m
1a2d0 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a ethods, SQLite.*
1a2e0 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c * holds the [SQL
1a2f0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 ITE_MUTEX_STATIC
1a300 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c _MEM] mutex as l
1a310 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 ong as the.** [S
1a320 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
1a330 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 STATUS] configur
1a340 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
1a350 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 turned on (which
1a360 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 .** it is by def
1a370 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 ault) and so the
1a380 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 methods are aut
1a390 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 omatically seria
1a3a0 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 lized..** Howeve
1a3b0 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f r, if [SQLITE_CO
1a3c0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 NFIG_MEMSTATUS]
1a3d0 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 is disabled, the
1a3e0 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d n the other.** m
1a3f0 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 ethods must be t
1a400 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 hreadsafe or els
1a410 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e e make their own
1a420 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f arrangements fo
1a430 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 r.** serializati
1a440 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 on..**.** SQLite
1a450 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f will never invo
1a460 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 ke xInit() more
1a470 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 than once withou
1a480 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 t an intervening
1a490 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 .** call to xShu
1a4a0 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 tdown()..*/.type
1a4b0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
1a4c0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 e3_mem_methods s
1a4d0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
1a4e0 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 ds;.struct sqlit
1a4f0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b e3_mem_methods {
1a500 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c . void *(*xMall
1a510 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 oc)(int);
1a520 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f /* Memory allo
1a530 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 cation function
1a540 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 */. void (*xFre
1a550 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 e)(void*);
1a560 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 /* Free a pr
1a570 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a ior allocation *
1a580 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 /. void *(*xRea
1a590 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 lloc)(void*,int)
1a5a0 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 ; /* Resize an
1a5b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 allocation */.
1a5c0 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 int (*xSize)(voi
1a5d0 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f d*); /
1a5e0 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a * Return the siz
1a5f0 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 e of an allocati
1a600 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 on */. int (*xR
1a610 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 oundup)(int);
1a620 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 /* Round
1a630 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 up request size
1a640 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 to allocation si
1a650 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 ze */. int (*xI
1a660 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 nit)(void*);
1a670 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 /* Initia
1a680 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 lize the memory
1a690 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 allocator */. v
1a6a0 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 oid (*xShutdown)
1a6b0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a (void*); /*
1a6c0 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 Deinitialize th
1a6d0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
1a6e0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 or */. void *pA
1a6f0 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 ppData;
1a700 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 /* Argume
1a710 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e nt to xInit() an
1a720 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f d xShutdown() */
1a730 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 .};../*.** CAPI3
1a740 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 REF: Configurati
1a750 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 on Options.** KE
1a760 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 YWORDS: {configu
1a770 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a ration option}.*
1a780 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 *.** These const
1a790 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 ants are the ava
1a7a0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 ilable integer c
1a7b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 onfiguration opt
1a7c0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e ions that.** can
1a7d0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 be passed as th
1a7e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
1a7f0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
1a800 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 _config()] inter
1a810 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 face..**.** New
1a820 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
1a830 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 tions may be add
1a840 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
1a850 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
1a860 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e .** Existing con
1a870 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
1a880 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 ns might be disc
1a890 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 ontinued. Appli
1a8a0 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c cations.** shoul
1a8b0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 d check the retu
1a8c0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 rn code from [sq
1a8d0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
1a8e0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 to make sure tha
1a8f0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f t.** the call wo
1a900 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 rked. The [sqli
1a910 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e te3_config()] in
1a920 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 terface will ret
1a930 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 urn a.** non-zer
1a940 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 o [error code] i
1a950 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 f a discontinued
1a960 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 or unsupported
1a970 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
1a980 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b tion.** is invok
1a990 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a ed..**.** <dl>.*
1a9a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
1a9b0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d G_SINGLETHREAD]]
1a9c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
1a9d0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c IG_SINGLETHREAD<
1a9e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 /dt>.** <dd>Ther
1a9f0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e e are no argumen
1aa00 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f ts to this optio
1aa10 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e n. ^This option
1aa20 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 sets the.** [th
1aa30 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f reading mode] to
1aa40 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 Single-thread.
1aa50 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c In other words,
1aa60 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 it disables.**
1aa70 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 all mutexing and
1aa80 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 puts SQLite int
1aa90 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 o a mode where i
1aaa0 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 t can only be us
1aab0 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c ed.** by a singl
1aac0 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 e thread. ^If
1aad0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c SQLite is compil
1aae0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b ed with.** the [
1aaf0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 SQLITE_THREADSAF
1ab00 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 E | SQLITE_THREA
1ab10 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 DSAFE=0] compile
1ab20 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 -time option the
1ab30 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 n.** it is not p
1ab40 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 ossible to chang
1ab50 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 e the [threading
1ab60 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 mode] from its
1ab70 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 default.** value
1ab80 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 of Single-threa
1ab90 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 d and so [sqlite
1aba0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 3_config()] will
1abb0 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c return .** [SQL
1abc0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 ITE_ERROR] if ca
1abd0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 lled with the SQ
1abe0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
1abf0 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 LETHREAD.** conf
1ac00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
1ac10 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
1ac20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
1ac30 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 TITHREAD]] <dt>S
1ac40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
1ac50 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a TITHREAD</dt>.**
1ac60 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e <dd>There are n
1ac70 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 o arguments to t
1ac80 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 his option. ^Th
1ac90 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 is option sets t
1aca0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 he.** [threading
1acb0 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d mode] to Multi-
1acc0 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 thread. In othe
1acd0 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 r words, it disa
1ace0 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 bles.** mutexing
1acf0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
1ad00 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 nnection] and [p
1ad10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
1ad20 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 t] objects..** T
1ad30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 he application i
1ad40 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f s responsible fo
1ad50 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 r serializing ac
1ad60 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 cess to.** [data
1ad70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 base connections
1ad80 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 ] and [prepared
1ad90 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 statements]. Bu
1ada0 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a t other mutexes.
1adb0 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 ** are enabled s
1adc0 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 o that SQLite wi
1add0 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 ll be safe to us
1ade0 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 e in a multi-thr
1adf0 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e eaded.** environ
1ae00 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 ment as long as
1ae10 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 no two threads a
1ae20 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 ttempt to use th
1ae30 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 e same.** [datab
1ae40 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
1ae50 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
1ae60 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 . ^If SQLite is
1ae70 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
1ae80 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
1ae90 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
1aea0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
1aeb0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
1aec0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 ion then.** it i
1aed0 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 s not possible t
1aee0 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d o set the Multi-
1aef0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e thread [threadin
1af00 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b g mode] and.** [
1af10 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
1af20 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 ] will return [S
1af30 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
1af40 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a called with the.
1af50 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ** SQLITE_CONFIG
1af60 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e _MULTITHREAD con
1af70 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
1af80 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b n.</dd>.**.** [[
1af90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
1afa0 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 RIALIZED]] <dt>S
1afb0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
1afc0 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 IALIZED</dt>.**
1afd0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f <dd>There are no
1afe0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 arguments to th
1aff0 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 is option. ^Thi
1b000 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 s option sets th
1b010 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 e.** [threading
1b020 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 mode] to Seriali
1b030 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f zed. In other wo
1b040 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e rds, this option
1b050 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 enables.** all
1b060 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e mutexes includin
1b070 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a g the recursive.
1b080 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 ** mutexes on [d
1b090 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1b0a0 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 on] and [prepare
1b0b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a d statement] obj
1b0c0 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 ects..** In this
1b0d0 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 mode (which is
1b0e0 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e the default when
1b0f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 SQLite is compi
1b100 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c led with.** [SQL
1b110 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 ITE_THREADSAFE=1
1b120 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 ]) the SQLite li
1b130 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c brary will itsel
1b140 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 f serialize acce
1b150 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 ss.** to [databa
1b160 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 se connections]
1b170 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 and [prepared st
1b180 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 atements] so tha
1b190 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 t the.** applica
1b1a0 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 tion is free to
1b1b0 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 use the same [da
1b1c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1b1d0 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d n] or the.** sam
1b1e0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
1b1f0 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 ement] in differ
1b200 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 ent threads at t
1b210 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a he same time..**
1b220 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 ^If SQLite is c
1b230 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
1b240 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 the [SQLITE_THRE
1b250 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f ADSAFE | SQLITE_
1b260 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f THREADSAFE=0] co
1b270 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
1b280 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 n then.** it is
1b290 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 not possible to
1b2a0 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a set the Serializ
1b2b0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
1b2c0 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 de] and.** [sqli
1b2d0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 te3_config()] wi
1b2e0 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 ll return [SQLIT
1b2f0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c E_ERROR] if call
1b300 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 ed with the.** S
1b310 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 QLITE_CONFIG_SER
1b320 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 IALIZED configur
1b330 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 ation option.</d
1b340 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
1b350 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
1b360 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
1b370 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a FIG_MALLOC</dt>.
1b380 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 ** <dd> ^(The SQ
1b390 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c LITE_CONFIG_MALL
1b3a0 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 OC option takes
1b3b0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
1b3c0 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 t which is .** a
1b3d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
1b3e0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b nstance of the [
1b3f0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 sqlite3_mem_meth
1b400 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a ods] structure..
1b410 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 ** The argument
1b420 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 specifies.** alt
1b430 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 ernative low-lev
1b440 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 el memory alloca
1b450 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f tion routines to
1b460 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 be used in plac
1b470 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f e of.** the memo
1b480 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f ry allocation ro
1b490 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 utines built int
1b4a0 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c o SQLite.)^ ^SQL
1b4b0 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 ite makes.** its
1b4c0 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
1b4d0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 y of the content
1b4e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
1b4f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 _mem_methods] st
1b500 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 ructure.** befor
1b510 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 e the [sqlite3_c
1b520 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 onfig()] call re
1b530 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a turns.</dd>.**.*
1b540 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
1b550 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 G_GETMALLOC]] <d
1b560 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
1b570 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a GETMALLOC</dt>.*
1b580 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
1b590 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 ITE_CONFIG_GETMA
1b5a0 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 LLOC option take
1b5b0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
1b5c0 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 ent which.** is
1b5d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 a pointer to an
1b5e0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 instance of the
1b5f0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 [sqlite3_mem_met
1b600 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e hods] structure.
1b610 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
1b620 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a _mem_methods].**
1b630 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 structure is fi
1b640 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 lled with the cu
1b650 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 rrently defined
1b660 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1b670 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a n routines.)^.**
1b680 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
1b690 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
1b6a0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
1b6b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
1b6c0 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 on.** routines w
1b6d0 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 ith a wrapper th
1b6e0 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d at simulations m
1b6f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1b700 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 failure or.** t
1b710 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 racks memory usa
1b720 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ge, for example.
1b730 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
1b740 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 QLITE_CONFIG_SMA
1b750 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e LL_MALLOC]] <dt>
1b760 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d SQLITE_CONFIG_SM
1b770 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a ALL_MALLOC</dt>.
1b780 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c ** <dd> ^The SQL
1b790 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c ITE_CONFIG_SMALL
1b7a0 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 _MALLOC option t
1b7b0 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 akes single argu
1b7c0 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 79 70 65 20 ment of.** type
1b7d0 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 int, interpreted
1b7e0 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 as a boolean, w
1b7f0 68 69 63 68 20 69 66 20 74 72 75 65 20 70 72 6f hich if true pro
1b800 76 69 64 65 73 20 61 20 68 69 6e 74 20 74 6f 0a vides a hint to.
1b810 2a 2a 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 ** SQLite that i
1b820 74 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 20 6c t should avoid l
1b830 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f arge memory allo
1b840 63 61 74 69 6f 6e 73 20 69 66 20 70 6f 73 73 69 cations if possi
1b850 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 77 ble..** SQLite w
1b860 69 6c 6c 20 72 75 6e 20 66 61 73 74 65 72 20 69 ill run faster i
1b870 66 20 69 74 20 69 73 20 66 72 65 65 20 74 6f 20 f it is free to
1b880 6d 61 6b 65 20 6c 61 72 67 65 20 6d 65 6d 6f 72 make large memor
1b890 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2c 0a 2a y allocations,.*
1b8a0 2a 20 62 75 74 20 73 6f 6d 65 20 61 70 70 6c 69 * but some appli
1b8b0 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 70 72 65 cation might pre
1b8c0 66 65 72 20 74 6f 20 72 75 6e 20 73 6c 6f 77 65 fer to run slowe
1b8d0 72 20 69 6e 20 65 78 63 68 61 6e 67 65 20 66 6f r in exchange fo
1b8e0 72 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 r.** guarantees
1b8f0 61 62 6f 75 74 20 6d 65 6d 6f 72 79 20 66 72 61 about memory fra
1b900 67 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 gmentation that
1b910 61 72 65 20 70 6f 73 73 69 62 6c 65 20 69 66 20 are possible if
1b920 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 large.** allocat
1b930 69 6f 6e 73 20 61 72 65 20 61 76 6f 69 64 65 64 ions are avoided
1b940 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 . This hint is
1b950 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 2e 0a 2a 2a normally off..**
1b960 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 </dd>.**.** [[S
1b970 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
1b980 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c STATUS]] <dt>SQL
1b990 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 ITE_CONFIG_MEMST
1b9a0 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 ATUS</dt>.** <dd
1b9b0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f > ^The SQLITE_CO
1b9c0 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f NFIG_MEMSTATUS o
1b9d0 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 ption takes sing
1b9e0 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 le argument of t
1b9f0 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 ype int,.** inte
1ba00 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f rpreted as a boo
1ba10 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 lean, which enab
1ba20 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 les or disables
1ba30 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f the collection o
1ba40 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f f.** memory allo
1ba50 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 cation statistic
1ba60 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 s. ^(When memory
1ba70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 allocation stat
1ba80 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 istics are.** di
1ba90 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c sabled, the foll
1baa0 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 owing SQLite int
1bab0 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e erfaces become n
1bac0 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a on-operational:.
1bad0 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c ** <ul>.** <
1bae0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d li> [sqlite3_mem
1baf0 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 ory_used()].**
1bb00 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d <li> [sqlite3_m
1bb10 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 emory_highwater(
1bb20 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 )].** <li> [sq
1bb30 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f lite3_soft_heap_
1bb40 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 limit64()].**
1bb50 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 <li> [sqlite3_st
1bb60 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c atus64()].** <
1bb70 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 /ul>)^.** ^Memor
1bb80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 y allocation sta
1bb90 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 tistics are enab
1bba0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 led by default u
1bbb0 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a nless SQLite is.
1bbc0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 ** compiled with
1bbd0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 [SQLITE_DEFAULT
1bbe0 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e _MEMSTATUS]=0 in
1bbf0 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f which case memo
1bc00 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e ry.** allocation
1bc10 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 statistics are
1bc20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
1bc30 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a ult..** </dd>.**
1bc40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
1bc50 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 FIG_SCRATCH]] <d
1bc60 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f t>SQLITE_CONFIG_
1bc70 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 SCRATCH</dt>.**
1bc80 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f <dd> The SQLITE_
1bc90 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f CONFIG_SCRATCH o
1bca0 70 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 ption is no long
1bcb0 65 72 20 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 64 er used..** </dd
1bcc0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
1bcd0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 _CONFIG_PAGECACH
1bce0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 E]] <dt>SQLITE_C
1bcf0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c ONFIG_PAGECACHE<
1bd00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
1bd10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
1bd20 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e PAGECACHE option
1bd30 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65 6d specifies a mem
1bd40 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 ory pool.** that
1bd50 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 SQLite can use
1bd60 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 for the database
1bd70 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 page cache with
1bd80 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 the default pag
1bd90 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 e.** cache imple
1bda0 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 mentation. .**
1bdb0 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 This configurati
1bdc0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e on option is a n
1bdd0 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c 69 o-op if an appli
1bde0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 cation-define pa
1bdf0 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c ge.** cache impl
1be00 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f ementation is lo
1be10 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b aded using the [
1be20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
1be30 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 ACHE2]..** ^Ther
1be40 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 e are three argu
1be50 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f ments to SQLITE_
1be60 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 CONFIG_PAGECACHE
1be70 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a : A pointer to.*
1be80 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 * 8-byte aligned
1be90 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 memory (pMem),
1bea0 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 the size of each
1beb0 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 page cache line
1bec0 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 (sz),.** and th
1bed0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63 68 e number of cach
1bee0 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 e lines (N)..**
1bef0 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 The sz argument
1bf00 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 should be the si
1bf10 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 ze of the larges
1bf20 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a t database page.
1bf30 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 ** (a power of t
1bf40 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 wo between 512 a
1bf50 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73 nd 65536) plus s
1bf60 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20 ome extra bytes
1bf70 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 for each.** page
1bf80 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e header. ^The n
1bf90 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62 umber of extra b
1bfa0 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74 ytes needed by t
1bfb0 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a he page header.*
1bfc0 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 * can be determi
1bfd0 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 ned using [SQLIT
1bfe0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f E_CONFIG_PCACHE_
1bff0 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 HDRSZ]..** ^It i
1c000 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 s harmless, apar
1c010 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 t from the waste
1c020 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 d memory,.** for
1c030 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74 65 the sz paramete
1c040 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20 74 r to be larger t
1c050 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20 20 han necessary.
1c060 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 The pMem.** argu
1c070 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69 74 ment must be eit
1c080 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 her a NULL point
1c090 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 er or a pointer
1c0a0 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 to an 8-byte.**
1c0b0 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 aligned block of
1c0c0 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 memory of at le
1c0d0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 ast sz*N bytes,
1c0e0 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 otherwise.** sub
1c0f0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 sequent behavior
1c100 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a is undefined..*
1c110 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 * ^When pMem is
1c120 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 not NULL, SQLite
1c130 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 will strive to
1c140 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 use the memory p
1c150 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 rovided.** to sa
1c160 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68 65 tisfy page cache
1c170 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 needs, falling
1c180 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 back to [sqlite3
1c190 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a _malloc()] if.**
1c1a0 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 a page cache li
1c1b0 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68 61 ne is larger tha
1c1c0 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69 66 n sz bytes or if
1c1d0 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d all of the pMem
1c1e0 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 buffer.** is ex
1c1f0 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 hausted..** ^If
1c200 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 pMem is NULL and
1c210 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 N is non-zero,
1c220 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62 61 then each databa
1c230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
1c240 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61 6c does an initial
1c250 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e bulk allocation
1c260 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 for page cache
1c270 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b memory.** from [
1c280 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
1c290 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f 72 ] sufficient for
1c2a0 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20 69 N cache lines i
1c2b0 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 20 f N is positive
1c2c0 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e or.** of -1024*N
1c2d0 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20 6e bytes if N is n
1c2e0 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 egative, . ^If a
1c2f0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 dditional.** pag
1c300 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 e cache memory i
1c310 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 s needed beyond
1c320 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 what is provided
1c330 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c 0a by the initial.
1c340 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 ** allocation, t
1c350 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73 20 hen SQLite goes
1c360 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c to [sqlite3_mall
1c370 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c 79 oc()] separately
1c380 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 for each.** add
1c390 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 itional cache li
1c3a0 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ne. </dd>.**.**
1c3b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
1c3c0 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 HEAP]] <dt>SQLIT
1c3d0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 E_CONFIG_HEAP</d
1c3e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 t>.** <dd> ^The
1c3f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 SQLITE_CONFIG_HE
1c400 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 AP option specif
1c410 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d ies a static mem
1c420 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 ory buffer .** t
1c430 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 hat SQLite will
1c440 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 use for all of i
1c450 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 ts dynamic memor
1c460 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 y allocation nee
1c470 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f ds.** beyond tho
1c480 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 se provided for
1c490 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 by [SQLITE_CONFI
1c4a0 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a G_PAGECACHE]..**
1c4b0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^The SQLITE_CON
1c4c0 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 FIG_HEAP option
1c4d0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c is only availabl
1c4e0 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 e if SQLite is c
1c4f0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 ompiled.** with
1c500 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 either [SQLITE_E
1c510 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f NABLE_MEMSYS3] o
1c520 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 r [SQLITE_ENABLE
1c530 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 _MEMSYS5] and re
1c540 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 turns.** [SQLITE
1c550 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b _ERROR] if invok
1c560 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a ed otherwise..**
1c570 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 ^There are thre
1c580 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 e arguments to S
1c590 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
1c5a0 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 P:.** An 8-byte
1c5b0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 aligned pointer
1c5c0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a to the memory,.*
1c5d0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 * the number of
1c5e0 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d bytes in the mem
1c5f0 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 ory buffer, and
1c600 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f the minimum allo
1c610 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 cation size..**
1c620 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f ^If the first po
1c630 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 inter (the memor
1c640 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 y pointer) is NU
1c650 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 LL, then SQLite
1c660 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 reverts.** to us
1c670 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 ing its default
1c680 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
1c690 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c (the system mal
1c6a0 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 loc() implementa
1c6b0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e tion),.** undoin
1c6c0 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f g any prior invo
1c6d0 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 cation of [SQLIT
1c6e0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d E_CONFIG_MALLOC]
1c6f0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 . ^If the.** me
1c700 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 mory pointer is
1c710 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 not NULL then th
1c720 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 e alternative me
1c730 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f mory.** allocato
1c740 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 r is engaged to
1c750 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 handle all of SQ
1c760 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c Lites memory all
1c770 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a ocation needs..*
1c780 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e * The first poin
1c790 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 ter (the memory
1c7a0 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 pointer) must be
1c7b0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 aligned to an 8
1c7c0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 -byte.** boundar
1c7d0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 y or subsequent
1c7e0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 behavior of SQLi
1c7f0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 te will be undef
1c800 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e ined..** The min
1c810 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 imum allocation
1c820 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 size is capped a
1c830 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 t 2**12. Reasona
1c840 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f ble values.** fo
1c850 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c r the minimum al
1c860 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 location size ar
1c870 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 e 2**5 through 2
1c880 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 **8.</dd>.**.**
1c890 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
1c8a0 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 MUTEX]] <dt>SQLI
1c8b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c TE_CONFIG_MUTEX<
1c8c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
1c8d0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
1c8e0 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 _MUTEX option ta
1c8f0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
1c900 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 ument which is a
1c910 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 .** pointer to a
1c920 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 n instance of th
1c930 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
1c940 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
1c950 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 ure..** The argu
1c960 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 ment specifies a
1c970 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c lternative low-l
1c980 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 evel mutex routi
1c990 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a nes to be used.*
1c9a0 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d * in place the m
1c9b0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 utex routines bu
1c9c0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e ilt into SQLite.
1c9d0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 )^ ^SQLite make
1c9e0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 s a copy of.** t
1c9f0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
1ca00 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 e [sqlite3_mutex
1ca10 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
1ca20 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 ure before the c
1ca30 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 all to.** [sqlit
1ca40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 e3_config()] ret
1ca50 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 urns. ^If SQLite
1ca60 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
1ca70 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 h.** the [SQLITE
1ca80 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 _THREADSAFE | SQ
1ca90 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d LITE_THREADSAFE=
1caa0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 0] compile-time
1cab0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 option then.** t
1cac0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 he entire mutexi
1cad0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 ng subsystem is
1cae0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 omitted from the
1caf0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 build and hence
1cb00 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 calls to.** [sq
1cb10 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
1cb20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f with the SQLITE_
1cb30 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e CONFIG_MUTEX con
1cb40 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
1cb50 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e n will.** return
1cb60 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e [SQLITE_ERROR].
1cb70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
1cb80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d LITE_CONFIG_GETM
1cb90 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 UTEX]] <dt>SQLIT
1cba0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 E_CONFIG_GETMUTE
1cbb0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e X</dt>.** <dd> ^
1cbc0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 (The SQLITE_CONF
1cbd0 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 IG_GETMUTEX opti
1cbe0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c on takes a singl
1cbf0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 e argument which
1cc00 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 .** is a pointer
1cc10 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 to an instance
1cc20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
1cc30 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 mutex_methods] s
1cc40 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a tructure. The.*
1cc50 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 * [sqlite3_mutex
1cc60 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 _methods].** str
1cc70 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 ucture is filled
1cc80 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e with the curren
1cc90 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 tly defined mute
1cca0 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a x routines.)^.**
1ccb0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e This option can
1ccc0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 be used to over
1ccd0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 load the default
1cce0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f mutex allocatio
1ccf0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 n.** routines wi
1cd00 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 th a wrapper use
1cd10 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 d to track mutex
1cd20 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f usage for perfo
1cd30 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c rmance.** profil
1cd40 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 ing or testing,
1cd50 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e for example. ^
1cd60 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d If SQLite is com
1cd70 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 piled with.** th
1cd80 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 e [SQLITE_THREAD
1cd90 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 SAFE | SQLITE_TH
1cda0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 READSAFE=0] comp
1cdb0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 ile-time option
1cdc0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 then.** the enti
1cdd0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 re mutexing subs
1cde0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 ystem is omitted
1cdf0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 from the build
1ce00 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 and hence calls
1ce10 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 to.** [sqlite3_c
1ce20 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 onfig()] with th
1ce30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
1ce40 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 GETMUTEX configu
1ce50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 ration option wi
1ce60 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 ll.** return [SQ
1ce70 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 LITE_ERROR].</dd
1ce80 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
1ce90 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
1cea0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 E]] <dt>SQLITE_C
1ceb0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c ONFIG_LOOKASIDE<
1cec0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
1ced0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
1cee0 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f _LOOKASIDE optio
1cef0 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 n takes two argu
1cf00 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 ments that deter
1cf10 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 mine.** the defa
1cf20 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b ult size of look
1cf30 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 aside memory on
1cf40 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 each [database c
1cf50 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 onnection]..** T
1cf60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
1cf70 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 t is the.** size
1cf80 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 of each lookasi
1cf90 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 de buffer slot a
1cfa0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 nd the second is
1cfb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
1cfc0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 * slots allocate
1cfd0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 d to each databa
1cfe0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e se connection.)^
1cff0 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ^(SQLITE_CONFI
1d000 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 G_LOOKASIDE.** s
1d010 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 ets the <i>defau
1d020 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 lt</i> lookaside
1d030 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 size. The [SQLI
1d040 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
1d050 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e ASIDE].** option
1d060 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f to [sqlite3_db_
1d070 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 config()] can be
1d080 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 used to change
1d090 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a the lookaside.**
1d0a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
1d0b0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e n individual con
1d0c0 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 nections.)^ </dd
1d0d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
1d0e0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d _CONFIG_PCACHE2]
1d0f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
1d100 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e FIG_PCACHE2</dt>
1d110 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 .** <dd> ^(The S
1d120 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
1d130 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 CHE2 option take
1d140 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
1d150 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a ent which is .**
1d160 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
1d170 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
1d180 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 _methods2] objec
1d190 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 t. This object
1d1a0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 specifies.** the
1d1b0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 interface to a
1d1c0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 custom page cach
1d1d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e e implementation
1d1e0 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d .)^.** ^SQLite m
1d1f0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 akes a copy of t
1d200 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 he [sqlite3_pcac
1d210 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a he_methods2] obj
1d220 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ect.</dd>.**.**
1d230 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
1d240 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 GETPCACHE2]] <dt
1d250 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 >SQLITE_CONFIG_G
1d260 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a ETPCACHE2</dt>.*
1d270 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c * <dd> ^(The SQL
1d280 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
1d290 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b ACHE2 option tak
1d2a0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 es a single argu
1d2b0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 ment which.** is
1d2c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
1d2d0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 [sqlite3_pcache
1d2e0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 _methods2] objec
1d2f0 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 t. SQLite copie
1d300 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 s of.** the curr
1d310 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 ent page cache i
1d320 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e mplementation in
1d330 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 to that object.)
1d340 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b ^ </dd>.**.** [[
1d350 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f SQLITE_CONFIG_LO
1d360 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 G]] <dt>SQLITE_C
1d370 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a ONFIG_LOG</dt>.*
1d380 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 * <dd> The SQLIT
1d390 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 E_CONFIG_LOG opt
1d3a0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 ion is used to c
1d3b0 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c onfigure the SQL
1d3c0 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 ite.** global [e
1d3d0 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e rror log]..** (^
1d3e0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
1d3f0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b G_LOG option tak
1d400 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 es two arguments
1d410 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 : a pointer to a
1d420 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 .** function wit
1d430 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 h a call signatu
1d440 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f re of void(*)(vo
1d450 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 id*,int,const ch
1d460 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 ar*), .** and a
1d470 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e pointer to void.
1d480 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f ^If the functio
1d490 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 n pointer is not
1d4a0 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 NULL, it is.**
1d4b0 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 invoked by [sqli
1d4c0 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 te3_log()] to pr
1d4d0 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 ocess each loggi
1d4e0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 ng event. ^If t
1d4f0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 he.** function p
1d500 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 ointer is NULL,
1d510 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 the [sqlite3_log
1d520 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 ()] interface be
1d530 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a comes a no-op..*
1d540 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e * ^The void poin
1d550 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 ter that is the
1d560 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 second argument
1d570 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 to SQLITE_CONFIG
1d580 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 _LOG is.** passe
1d590 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 d through as the
1d5a0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
1d5b0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 to the applicat
1d5c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 ion-defined logg
1d5d0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 er.** function w
1d5e0 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e henever that fun
1d5f0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 ction is invoked
1d600 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 . ^The second p
1d610 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 arameter to.** t
1d620 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 he logger functi
1d630 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 on is a copy of
1d640 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 the first parame
1d650 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 ter to the corre
1d660 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c sponding.** [sql
1d670 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c ite3_log()] call
1d680 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 and is intended
1d690 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 to be a [result
1d6a0 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 code] or an.**
1d6b0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
1d6c0 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 code]. ^The th
1d6d0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 ird parameter pa
1d6e0 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 ssed to the logg
1d6f0 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 er is.** log mes
1d700 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 sage after forma
1d710 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 tting via [sqlit
1d720 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a e3_snprintf()]..
1d730 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f ** The SQLite lo
1d740 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 gging interface
1d750 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 is not reentrant
1d760 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e ; the logger fun
1d770 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 ction.** supplie
1d780 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 d by the applica
1d790 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e tion must not in
1d7a0 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 voke any SQLite
1d7b0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e interface..** In
1d7c0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 a multi-threade
1d7d0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 d application, t
1d7e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 he application-d
1d7f0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a efined logger.**
1d800 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 function must b
1d810 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f e threadsafe. </
1d820 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 dd>.**.** [[SQLI
1d830 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 TE_CONFIG_URI]]
1d840 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
1d850 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 G_URI.** <dd>^(T
1d860 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
1d870 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 _URI option take
1d880 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d s a single argum
1d890 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e ent of type int.
1d8a0 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c .** If non-zero,
1d8b0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 then URI handli
1d8c0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 ng is globally e
1d8d0 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 nabled. If the p
1d8e0 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f arameter is zero
1d8f0 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 ,.** then URI ha
1d900 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c ndling is global
1d910 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e ly disabled.)^ ^
1d920 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 If URI handling
1d930 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 is globally.** e
1d940 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 nabled, all file
1d950 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 names passed to
1d960 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d [sqlite3_open()]
1d970 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f , [sqlite3_open_
1d980 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 v2()],.** [sqlit
1d990 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a e3_open16()] or.
1d9a0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 ** specified as
1d9b0 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d part of [ATTACH]
1d9c0 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e commands are in
1d9d0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 terpreted as URI
1d9e0 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a s, regardless.**
1d9f0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
1da00 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f ot the [SQLITE_O
1da10 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 PEN_URI] flag is
1da20 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 set when the da
1da30 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 tabase.** connec
1da40 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 tion is opened.
1da50 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c ^If it is global
1da60 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c ly disabled, fil
1da70 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e enames are.** on
1da80 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 ly interpreted a
1da90 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 s URIs if the SQ
1daa0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c LITE_OPEN_URI fl
1dab0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 ag is set when t
1dac0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 he.** database c
1dad0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 onnection is ope
1dae0 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c ned. ^(By defaul
1daf0 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 t, URI handling
1db00 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 is globally.** d
1db10 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 isabled. The def
1db20 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 ault value may b
1db30 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d e changed by com
1db40 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a piling with the.
1db50 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 ** [SQLITE_USE_U
1db60 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e RI] symbol defin
1db70 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 ed.)^.**.** [[SQ
1db80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 LITE_CONFIG_COVE
1db90 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d RING_INDEX_SCAN]
1dba0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
1dbb0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 FIG_COVERING_IND
1dbc0 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e EX_SCAN.** <dd>^
1dbd0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
1dbe0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 G_COVERING_INDEX
1dbf0 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b _SCAN option tak
1dc00 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 es a single inte
1dc10 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 ger.** argument
1dc20 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 which is interpr
1dc30 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 eted as a boolea
1dc40 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e n in order to en
1dc50 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a able or disable.
1dc60 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f ** the use of co
1dc70 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 vering indices f
1dc80 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 or full table sc
1dc90 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 ans in the query
1dca0 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e optimizer..** ^
1dcb0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 The default sett
1dcc0 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 ing is determine
1dcd0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c d.** by the [SQL
1dce0 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 ITE_ALLOW_COVERI
1dcf0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 NG_INDEX_SCAN] c
1dd00 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 ompile-time opti
1dd10 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a on, or is "on".*
1dd20 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c * if that compil
1dd30 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 e-time option is
1dd40 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 omitted..** The
1dd50 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 ability to disa
1dd60 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 ble the use of c
1dd70 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 overing indices
1dd80 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 for full table s
1dd90 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 cans.** is becau
1dda0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 se some incorrec
1ddb0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 tly coded legacy
1ddc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 applications mi
1ddd0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a ght malfunction.
1dde0 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 ** when the opti
1ddf0 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 mization is enab
1de00 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 led. Providing
1de10 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a the ability to.*
1de20 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 * disable the op
1de30 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 timization allow
1de40 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 s the older, bug
1de50 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 gy application c
1de60 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 ode to work.** w
1de70 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 ithout change ev
1de80 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 en with newer ve
1de90 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 rsions of SQLite
1dea0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ..**.** [[SQLITE
1deb0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d _CONFIG_PCACHE]]
1dec0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
1ded0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 _GETPCACHE]].**
1dee0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
1def0 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c G_PCACHE and SQL
1df00 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 ITE_CONFIG_GETPC
1df10 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 ACHE.** <dd> The
1df20 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f se options are o
1df30 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 bsolete and shou
1df40 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 ld not be used b
1df50 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 y new code..** T
1df60 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 hey are retained
1df70 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 for backwards c
1df80 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 ompatibility but
1df90 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e are now no-ops.
1dfa0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
1dfb0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
1dfc0 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e SQLLOG]].** <dt>
1dfd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 SQLITE_CONFIG_SQ
1dfe0 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 LLOG.** <dd>This
1dff0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 option is only
1e000 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c available if sql
1e010 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 ite is compiled
1e020 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c with the.** [SQL
1e030 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f ITE_ENABLE_SQLLO
1e040 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 G] pre-processor
1e050 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 macro defined.
1e060 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
1e070 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 nt should.** be
1e080 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 a pointer to a f
1e090 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 unction of type
1e0a0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 void(*)(void*,sq
1e0b0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 lite3*,const cha
1e0c0 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 r*, int)..** The
1e0d0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 second should b
1e0e0 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a e of type (void*
1e0f0 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 ). The callback
1e100 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 is invoked by th
1e110 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 e library.** in
1e120 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 three separate c
1e130 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 ircumstances, id
1e140 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 entified by the
1e150 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 value passed as
1e160 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 the.** fourth pa
1e170 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 rameter. If the
1e180 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
1e190 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 is 0, then the
1e1a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1e1b0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 ion.** passed as
1e1c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 the second argu
1e1d0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 ment has just be
1e1e0 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 en opened. The t
1e1f0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a hird argument.**
1e200 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 points to a buf
1e210 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 fer containing t
1e220 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d he name of the m
1e230 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c ain database fil
1e240 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 e. If the.** fou
1e250 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 rth parameter is
1e260 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 1, then the SQL
1e270 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 statement that
1e280 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
1e290 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f ter.** points to
1e2a0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 has just been e
1e2b0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 xecuted. Or, if
1e2c0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
1e2d0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a eter is 2, then.
1e2e0 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f ** the connectio
1e2f0 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 n being passed a
1e300 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 s the second par
1e310 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 ameter is being
1e320 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 closed. The.** t
1e330 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 hird parameter i
1e340 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e s passed NULL In
1e350 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 this case. An
1e360 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 example of using
1e370 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 this.** configu
1e380 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 ration option ca
1e390 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 n be seen in the
1e3a0 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 "test_sqllog.c"
1e3b0 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a source file in.
1e3c0 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c ** the canonical
1e3d0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 SQLite source t
1e3e0 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 ree.</dd>.**.**
1e3f0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
1e400 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c MMAP_SIZE]].** <
1e410 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
1e420 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 _MMAP_SIZE.** <d
1e430 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 d>^SQLITE_CONFIG
1e440 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 _MMAP_SIZE takes
1e450 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 two 64-bit inte
1e460 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 ger (sqlite3_int
1e470 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 64) values.** th
1e480 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 at are the defau
1e490 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d lt mmap size lim
1e4a0 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 it (the default
1e4b0 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b setting for.** [
1e4c0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 PRAGMA mmap_size
1e4d0 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d ]) and the maxim
1e4e0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 um allowed mmap
1e4f0 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e size limit..** ^
1e500 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 The default sett
1e510 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 ing can be overr
1e520 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 idden by each da
1e530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1e540 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 n using.** eithe
1e550 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d r the [PRAGMA mm
1e560 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 ap_size] command
1e570 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 , or by using th
1e580 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e e.** [SQLITE_FCN
1e590 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 TL_MMAP_SIZE] fi
1e5a0 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 le control. ^(T
1e5b0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 he maximum allow
1e5c0 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 ed mmap size.**
1e5d0 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 will be silently
1e5e0 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 truncated if ne
1e5f0 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 cessary so that
1e600 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 it does not exce
1e610 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c ed the.** compil
1e620 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d e-time maximum m
1e630 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 map size set by
1e640 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d the.** [SQLITE_M
1e650 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f AX_MMAP_SIZE] co
1e660 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
1e670 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 n.)^.** ^If eith
1e680 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 er argument to t
1e690 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 his option is ne
1e6a0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 gative, then tha
1e6b0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a t argument is.**
1e6c0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 changed to its
1e6d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 compile-time def
1e6e0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 ault..**.** [[SQ
1e6f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 LITE_CONFIG_WIN3
1e700 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 2_HEAPSIZE]].**
1e710 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
1e720 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 G_WIN32_HEAPSIZE
1e730 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c .** <dd>^The SQL
1e740 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 ITE_CONFIG_WIN32
1e750 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e _HEAPSIZE option
1e760 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 is only availab
1e770 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a le if SQLite is.
1e780 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 ** compiled for
1e790 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 Windows with the
1e7a0 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d [SQLITE_WIN32_M
1e7b0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 ALLOC] pre-proce
1e7c0 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 ssor macro.** de
1e7d0 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 fined. ^SQLITE_C
1e7e0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 ONFIG_WIN32_HEAP
1e7f0 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d SIZE takes a 32-
1e800 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 bit unsigned int
1e810 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 eger value.** th
1e820 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 at specifies the
1e830 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 maximum size of
1e840 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 the created hea
1e850 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 p..**.** [[SQLIT
1e860 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f E_CONFIG_PCACHE_
1e870 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 HDRSZ]].** <dt>S
1e880 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
1e890 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 CHE_HDRSZ.** <dd
1e8a0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e >^The SQLITE_CON
1e8b0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a FIG_PCACHE_HDRSZ
1e8c0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 option takes a
1e8d0 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 single parameter
1e8e0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 which.** is a p
1e8f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
1e900 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 eger and writes
1e910 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 into that intege
1e920 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 r the number of
1e930 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 extra.** bytes p
1e940 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 er page required
1e950 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 for each page i
1e960 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 n [SQLITE_CONFIG
1e970 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 _PAGECACHE]..**
1e980 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 The amount of ex
1e990 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 tra space requir
1e9a0 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 ed can change de
1e9b0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 pending on the c
1e9c0 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 ompiler,.** targ
1e9d0 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 et platform, and
1e9e0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e SQLite version.
1e9f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
1ea00 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a CONFIG_PMASZ]].*
1ea10 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e * <dt>SQLITE_CON
1ea20 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 FIG_PMASZ.** <dd
1ea30 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e >^The SQLITE_CON
1ea40 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e FIG_PMASZ option
1ea50 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
1ea60 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a parameter which.
1ea70 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 ** is an unsigne
1ea80 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 d integer and se
1ea90 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 ts the "Minimum
1eaa0 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 PMA Size" for th
1eab0 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a e multithreaded.
1eac0 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 ** sorter to tha
1ead0 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 t integer. The
1eae0 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 default minimum
1eaf0 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 PMA Size is set
1eb00 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 by the.** [SQLIT
1eb10 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 E_SORTER_PMASZ]
1eb20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
1eb30 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 ion. New thread
1eb40 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a s are launched.*
1eb50 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 * to help with s
1eb60 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 ort operations w
1eb70 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 hen multithreade
1eb80 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 d sorting.** is
1eb90 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 enabled (using t
1eba0 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 he [PRAGMA threa
1ebb0 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 ds] command) and
1ebc0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 the amount of c
1ebd0 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 ontent.** to be
1ebe0 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 sorted exceeds t
1ebf0 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d he page size tim
1ec00 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f es the minimum o
1ec10 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 f the.** [PRAGMA
1ec20 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 cache_size] set
1ec30 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 ting and this va
1ec40 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c lue..**.** [[SQL
1ec50 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a ITE_CONFIG_STMTJ
1ec60 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c RNL_SPILL]].** <
1ec70 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
1ec80 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a _STMTJRNL_SPILL.
1ec90 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 ** <dd>^The SQLI
1eca0 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 TE_CONFIG_STMTJR
1ecb0 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 NL_SPILL option
1ecc0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 takes a single p
1ecd0 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a arameter which.*
1ece0 2a 20 62 65 63 6f 6d 65 73 20 74 68 65 20 5b 73 * becomes the [s
1ecf0 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c tatement journal
1ed00 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 ] spill-to-disk
1ed10 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 threshold. .**
1ed20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e [Statement journ
1ed30 61 6c 73 5d 20 61 72 65 20 68 65 6c 64 20 69 6e als] are held in
1ed40 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c 20 74 68 memory until th
1ed50 65 69 72 20 73 69 7a 65 20 28 69 6e 20 62 79 74 eir size (in byt
1ed60 65 73 29 0a 2a 2a 20 65 78 63 65 65 64 73 20 74 es).** exceeds t
1ed70 68 69 73 20 74 68 72 65 73 68 6f 6c 64 2c 20 61 his threshold, a
1ed80 74 20 77 68 69 63 68 20 70 6f 69 6e 74 20 74 68 t which point th
1ed90 65 79 20 61 72 65 20 77 72 69 74 74 65 6e 20 74 ey are written t
1eda0 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 o disk..** Or if
1edb0 20 74 68 65 20 74 68 72 65 73 68 6f 6c 64 20 69 the threshold i
1edc0 73 20 2d 31 2c 20 73 74 61 74 65 6d 65 6e 74 20 s -1, statement
1edd0 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20 61 6c 77 journals are alw
1ede0 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65 78 63 6c ays held.** excl
1edf0 75 73 69 76 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 usively in memor
1ee00 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d 61 6e 79 y..** Since many
1ee10 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e statement journ
1ee20 61 6c 73 20 6e 65 76 65 72 20 62 65 63 6f 6d 65 als never become
1ee30 20 6c 61 72 67 65 2c 20 73 65 74 74 69 6e 67 20 large, setting
1ee40 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 the spill.** thr
1ee50 65 73 68 6f 6c 64 20 74 6f 20 61 20 76 61 6c 75 eshold to a valu
1ee60 65 20 73 75 63 68 20 61 73 20 36 34 4b 69 42 20 e such as 64KiB
1ee70 63 61 6e 20 67 72 65 61 74 6c 79 20 72 65 64 75 can greatly redu
1ee80 63 65 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 ce the amount of
1ee90 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69 72 65 64 .** I/O required
1eea0 20 74 6f 20 73 75 70 70 6f 72 74 20 73 74 61 74 to support stat
1eeb0 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a ement rollback..
1eec0 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 ** The default v
1eed0 61 6c 75 65 20 66 6f 72 20 74 68 69 73 20 73 65 alue for this se
1eee0 74 74 69 6e 67 20 69 73 20 63 6f 6e 74 72 6f 6c tting is control
1eef0 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 led by the.** [S
1ef00 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 QLITE_STMTJRNL_S
1ef10 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 PILL] compile-ti
1ef20 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a me option..**.**
1ef30 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
1ef40 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 5d _SORTERREF_SIZE]
1ef50 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f ].** <dt>SQLITE_
1ef60 43 4f 4e 46 49 47 5f 53 4f 52 54 45 52 52 45 46 CONFIG_SORTERREF
1ef70 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 54 68 65 _SIZE.** <dd>The
1ef80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
1ef90 4f 52 54 45 52 52 45 46 5f 53 49 5a 45 20 6f 70 ORTERREF_SIZE op
1efa0 74 69 6f 6e 20 61 63 63 65 70 74 73 20 61 20 73 tion accepts a s
1efb0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 0a ingle parameter.
1efc0 2a 2a 20 6f 66 20 74 79 70 65 20 28 69 6e 74 29 ** of type (int)
1efd0 20 2d 20 74 68 65 20 6e 65 77 20 76 61 6c 75 65 - the new value
1efe0 20 6f 66 20 74 68 65 20 73 6f 72 74 65 72 2d 72 of the sorter-r
1eff0 65 66 65 72 65 6e 63 65 20 73 69 7a 65 20 74 68 eference size th
1f000 72 65 73 68 6f 6c 64 2e 0a 2a 2a 20 55 73 75 61 reshold..** Usua
1f010 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c 69 74 65 lly, when SQLite
1f020 20 75 73 65 73 20 61 6e 20 65 78 74 65 72 6e 61 uses an externa
1f030 6c 20 73 6f 72 74 20 74 6f 20 6f 72 64 65 72 20 l sort to order
1f040 72 65 63 6f 72 64 73 20 61 63 63 6f 72 64 69 6e records accordin
1f050 67 0a 2a 2a 20 74 6f 20 61 6e 20 4f 52 44 45 52 g.** to an ORDER
1f060 20 42 59 20 63 6c 61 75 73 65 2c 20 61 6c 6c 20 BY clause, all
1f070 66 69 65 6c 64 73 20 72 65 71 75 69 72 65 64 20 fields required
1f080 62 79 20 74 68 65 20 63 61 6c 6c 65 72 20 61 72 by the caller ar
1f090 65 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65 e present in the
1f0a0 0a 2a 2a 20 73 6f 72 74 65 64 20 72 65 63 6f 72 .** sorted recor
1f0b0 64 73 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 ds. However, if
1f0c0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 SQLite determine
1f0d0 73 20 62 61 73 65 64 20 6f 6e 20 74 68 65 20 64 s based on the d
1f0e0 65 63 6c 61 72 65 64 20 74 79 70 65 0a 2a 2a 20 eclared type.**
1f0f0 6f 66 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d of a table colum
1f100 6e 20 74 68 61 74 20 69 74 73 20 76 61 6c 75 65 n that its value
1f110 73 20 61 72 65 20 6c 69 6b 65 6c 79 20 74 6f 20 s are likely to
1f120 62 65 20 76 65 72 79 20 6c 61 72 67 65 20 2d 20 be very large -
1f130 6c 61 72 67 65 72 0a 2a 2a 20 74 68 61 6e 20 74 larger.** than t
1f140 68 65 20 63 6f 6e 66 69 67 75 72 65 64 20 73 6f he configured so
1f150 72 74 65 72 2d 72 65 66 65 72 65 6e 63 65 20 73 rter-reference s
1f160 69 7a 65 20 74 68 72 65 73 68 6f 6c 64 20 2d 20 ize threshold -
1f170 74 68 65 6e 20 61 20 72 65 66 65 72 65 6e 63 65 then a reference
1f180 0a 2a 2a 20 69 73 20 73 74 6f 72 65 64 20 69 6e .** is stored in
1f190 20 65 61 63 68 20 73 6f 72 74 65 64 20 72 65 63 each sorted rec
1f1a0 6f 72 64 20 61 6e 64 20 74 68 65 20 72 65 71 75 ord and the requ
1f1b0 69 72 65 64 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 ired column valu
1f1c0 65 73 20 6c 6f 61 64 65 64 0a 2a 2a 20 66 72 6f es loaded.** fro
1f1d0 6d 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 m the database a
1f1e0 73 20 72 65 63 6f 72 64 73 20 61 72 65 20 72 65 s records are re
1f1f0 74 75 72 6e 65 64 20 69 6e 20 73 6f 72 74 65 64 turned in sorted
1f200 20 6f 72 64 65 72 2e 20 54 68 65 20 64 65 66 61 order. The defa
1f210 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 66 6f 72 ult.** value for
1f220 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 this option is
1f230 74 6f 20 6e 65 76 65 72 20 75 73 65 20 74 68 69 to never use thi
1f240 73 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2e 20 s optimization.
1f250 53 70 65 63 69 66 79 69 6e 67 20 61 20 0a 2a 2a Specifying a .**
1f260 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 negative value
1f270 66 6f 72 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 for this option
1f280 72 65 73 74 6f 72 65 73 20 74 68 65 20 64 65 66 restores the def
1f290 61 75 6c 74 20 62 65 68 61 76 69 6f 75 72 2e 0a ault behaviour..
1f2a0 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 ** This option i
1f2b0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 s only available
1f2c0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f if SQLite is co
1f2d0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a mpiled with the.
1f2e0 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c ** [SQLITE_ENABL
1f2f0 45 5f 53 4f 52 54 45 52 5f 52 45 46 45 52 45 4e E_SORTER_REFEREN
1f300 43 45 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d CES] compile-tim
1f310 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 e option..** </d
1f320 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
1f330 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
1f340 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 LETHREAD 1 /*
1f350 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nil */.#define S
1f360 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c QLITE_CONFIG_MUL
1f370 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a TITHREAD 2 /*
1f380 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 nil */.#define
1f390 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 SQLITE_CONFIG_SE
1f3a0 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f RIALIZED 3 /
1f3b0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 * nil */.#define
1f3c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d SQLITE_CONFIG_M
1f3d0 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 ALLOC 4
1f3e0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d /* sqlite3_mem_m
1f3f0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
1f400 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
1f410 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 _GETMALLOC 5
1f420 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d /* sqlite3_mem
1f430 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 _methods* */.#de
1f440 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
1f450 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 IG_SCRATCH
1f460 20 36 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 6 /* No longer
1f470 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 used */.#define
1f480 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 SQLITE_CONFIG_P
1f490 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 AGECACHE 7
1f4a0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a /* void*, int sz
1f4b0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 , int N */.#defi
1f4c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
1f4d0 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 _HEAP 8
1f4e0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 /* void*, int
1f4f0 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a nByte, int min *
1f500 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1f510 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 _CONFIG_MEMSTATU
1f520 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c S 9 /* bool
1f530 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ean */.#define S
1f540 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 QLITE_CONFIG_MUT
1f550 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a EX 10 /*
1f560 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d sqlite3_mutex_m
1f570 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 ethods* */.#defi
1f580 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
1f590 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 _GETMUTEX 11
1f5a0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 /* sqlite3_mut
1f5b0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f ex_methods* */./
1f5c0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c * previously SQL
1f5d0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b ITE_CONFIG_CHUNK
1f5e0 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 ALLOC 12 which i
1f5f0 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f s now unused. */
1f600 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 .#define SQLITE
1f610 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
1f620 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 E 13 /* int
1f630 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
1f640 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
1f650 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a CHE 14 /*
1f660 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e no-op */.#defin
1f670 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
1f680 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 GETPCACHE 15
1f690 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 /* no-op */.#de
1f6a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
1f6b0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 IG_LOG
1f6c0 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 16 /* xFunc, vo
1f6d0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 id* */.#define S
1f6e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 QLITE_CONFIG_URI
1f6f0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 17 /*
1f700 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int */.#define
1f710 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 SQLITE_CONFIG_PC
1f720 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f ACHE2 18 /
1f730 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 * sqlite3_pcache
1f740 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 _methods2* */.#d
1f750 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
1f760 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 FIG_GETPCACHE2
1f770 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 19 /* sqlite3_
1f780 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a pcache_methods2*
1f790 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1f7a0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 TE_CONFIG_COVERI
1f7b0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 NG_INDEX_SCAN 20
1f7c0 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 /* int */.#def
1f7d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
1f7e0 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 G_SQLLOG 2
1f7f0 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 1 /* xSqllog, v
1f800 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 oid* */.#define
1f810 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d SQLITE_CONFIG_MM
1f820 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f AP_SIZE 22 /
1f830 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c * sqlite3_int64,
1f840 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a sqlite3_int64 *
1f850 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1f860 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 _CONFIG_WIN32_HE
1f870 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 APSIZE 23
1f880 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a /* int nByte */.
1f890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1f8a0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 ONFIG_PCACHE_HDR
1f8b0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a SZ 24 /*
1f8c0 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 int *psz */.#de
1f8d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
1f8e0 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 IG_PMASZ
1f8f0 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 25 /* un
1f900 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 signed int szPma
1f910 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
1f920 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 TE_CONFIG_STMTJR
1f930 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36 NL_SPILL 26
1f940 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a /* int nByte *
1f950 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1f960 5f 43 4f 4e 46 49 47 5f 53 4d 41 4c 4c 5f 4d 41 _CONFIG_SMALL_MA
1f970 4c 4c 4f 43 20 20 20 20 20 20 20 20 32 37 20 20 LLOC 27
1f980 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 /* boolean */.#d
1f990 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
1f9a0 46 49 47 5f 53 4f 52 54 45 52 52 45 46 5f 53 49 FIG_SORTERREF_SI
1f9b0 5a 45 20 20 20 20 20 20 32 38 20 20 2f 2a 20 69 ZE 28 /* i
1f9c0 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a nt nByte */../*.
1f9d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 ** CAPI3REF: Dat
1f9e0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e abase Connection
1f9f0 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f Configuration O
1fa00 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 ptions.**.** The
1fa10 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 se constants are
1fa20 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 the available i
1fa30 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 nteger configura
1fa40 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 tion options tha
1fa50 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 t.** can be pass
1fa60 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
1fa70 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
1fa80 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e [sqlite3_db_con
1fa90 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 fig()] interface
1faa0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 ..**.** New conf
1fab0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
1fac0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 s may be added i
1fad0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 n future release
1fae0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 s of SQLite..**
1faf0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 Existing configu
1fb00 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d ration options m
1fb10 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 ight be disconti
1fb20 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 nued. Applicati
1fb30 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 ons.** should ch
1fb40 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 eck the return c
1fb50 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 ode from [sqlite
1fb60 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 3_db_config()] t
1fb70 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 o make sure that
1fb80 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 .** the call wor
1fb90 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 ked. ^The [sqli
1fba0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d te3_db_config()]
1fbb0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 interface will
1fbc0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d return a.** non-
1fbd0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 zero [error code
1fbe0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e ] if a discontin
1fbf0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 ued or unsupport
1fc00 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ed configuration
1fc10 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e option.** is in
1fc20 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c voked..**.** <dl
1fc30 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
1fc40 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 DBCONFIG_LOOKASI
1fc50 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 DE</dt>.** <dd>
1fc60 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b ^This option tak
1fc70 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f es three additio
1fc80 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 nal arguments th
1fc90 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 at determine the
1fca0 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 .** [lookaside
1fcb0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 memory allocator
1fcc0 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 ] configuration
1fcd0 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 for the [databas
1fce0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a e connection]..*
1fcf0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 * ^The first arg
1fd00 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 ument (the third
1fd10 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 parameter to [s
1fd20 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 qlite3_db_config
1fd30 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e ()] is a.** poin
1fd40 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 ter to a memory
1fd50 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f buffer to use fo
1fd60 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f r lookaside memo
1fd70 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 ry..** ^The firs
1fd80 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 t argument after
1fd90 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f the SQLITE_DBCO
1fda0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 NFIG_LOOKASIDE v
1fdb0 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 erb.** may be NU
1fdc0 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 LL in which case
1fdd0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c SQLite will all
1fde0 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f ocate the.** loo
1fdf0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 kaside buffer it
1fe00 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 self using [sqli
1fe10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e te3_malloc()]. ^
1fe20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
1fe30 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 ent is the.** si
1fe40 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 ze of each looka
1fe50 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 side buffer slot
1fe60 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 . ^The third ar
1fe70 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 gument is the nu
1fe80 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 mber of.** slots
1fe90 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 . The size of t
1fea0 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 he buffer in the
1feb0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
1fec0 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 must be greater
1fed0 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c than.** or equal
1fee0 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 to the product
1fef0 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e of the second an
1ff00 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 d third argument
1ff10 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a s. The buffer.*
1ff20 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 * must be aligne
1ff30 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 d to an 8-byte b
1ff40 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 oundary. ^If th
1ff50 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e e second argumen
1ff60 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 t to.** SQLITE_D
1ff70 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
1ff80 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 E is not a multi
1ff90 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 ple of 8, it is
1ffa0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f internally.** ro
1ffb0 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 unded down to th
1ffc0 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d e next smaller m
1ffd0 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e ultiple of 8. ^
1ffe0 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d (The lookaside m
1fff0 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 emory.** configu
20000 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 ration for a dat
20010 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
20020 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 can only be cha
20030 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a nged when that.*
20040 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 * connection is
20050 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 not currently us
20060 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 ing lookaside me
20070 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 mory, or in othe
20080 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 r words.** when
20090 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c the "current val
200a0 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a ue" returned by.
200b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 ** [sqlite3_db_s
200c0 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 tatus](D,[SQLITE
200d0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 _CONFIG_LOOKASID
200e0 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e E],...) is zero.
200f0 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 .** Any attempt
20100 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f to change the lo
20110 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 okaside memory c
20120 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 onfiguration whe
20130 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d n lookaside.** m
20140 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 emory is in use
20150 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 leaves the confi
20160 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 guration unchang
20170 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a ed and returns .
20180 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d ** [SQLITE_BUSY]
20190 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c .)^</dd>.**.** <
201a0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 dt>SQLITE_DBCONF
201b0 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f IG_ENABLE_FKEY</
201c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
201d0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 s option is used
201e0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 to enable or di
201f0 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 sable the enforc
20200 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 ement of.** [for
20210 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 eign key constra
20220 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 ints]. There sh
20230 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 ould be two addi
20240 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
20250 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
20260 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e rgument is an in
20270 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 teger which is 0
20280 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 to disable FK e
20290 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 nforcement,.** p
202a0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c ositive to enabl
202b0 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 e FK enforcement
202c0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 or negative to
202d0 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 leave FK enforce
202e0 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 ment.** unchange
202f0 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 d. The second p
20300 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f arameter is a po
20310 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
20320 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a ger into which.*
20330 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f * is written 0 o
20340 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 r 1 to indicate
20350 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 whether FK enfor
20360 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 cement is off or
20370 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 on.** following
20380 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 this call. The
20390 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
203a0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 r may be a NULL
203b0 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 pointer, in.** w
203c0 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b hich case the FK
203d0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 enforcement set
203e0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f ting is not repo
203f0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e rted back. </dd>
20400 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 .**.** <dt>SQLIT
20410 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c E_DBCONFIG_ENABL
20420 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a E_TRIGGER</dt>.*
20430 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
20440 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 ion is used to e
20450 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 nable or disable
20460 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
20470 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a | triggers]..**
20480 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 There should be
20490 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 two additional
204a0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 arguments..** Th
204b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
204c0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 is an integer w
204d0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 hich is 0 to dis
204e0 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a able triggers,.*
204f0 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e * positive to en
20500 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 able triggers or
20510 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 negative to lea
20520 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 ve the setting u
20530 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 nchanged..** The
20540 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
20550 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 r is a pointer t
20560 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 o an integer int
20570 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 o which.** is wr
20580 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 itten 0 or 1 to
20590 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 indicate whether
205a0 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 triggers are di
205b0 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 sabled or enable
205c0 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 d.** following t
205d0 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 his call. The s
205e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
205f0 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f may be a NULL po
20600 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 inter, in.** whi
20610 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 ch case the trig
20620 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e ger setting is n
20630 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b ot reported back
20640 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 . </dd>.**.** <d
20650 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
20660 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f G_ENABLE_FTS3_TO
20670 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20 KENIZER</dt>.**
20680 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f <dd> ^This optio
20690 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 n is used to ena
206a0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 ble or disable t
206b0 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a he two-argument.
206c0 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 ** version of th
206d0 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 e [fts3_tokenize
206e0 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68 r()] function wh
206f0 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74 ich is part of t
20700 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c he.** [FTS3] ful
20710 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e l-text search en
20720 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a gine extension..
20730 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 ** There should
20740 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 be two additiona
20750 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 l arguments..**
20760 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 The first argume
20770 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 nt is an integer
20780 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 which is 0 to d
20790 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 isable fts3_toke
207a0 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f nizer() or.** po
207b0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 sitive to enable
207c0 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 fts3_tokenizer(
207d0 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f ) or negative to
207e0 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 leave the setti
207f0 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e ng.** unchanged.
20800 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 .** The second p
20810 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f arameter is a po
20820 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
20830 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a ger into which.*
20840 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f * is written 0 o
20850 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 r 1 to indicate
20860 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b whether fts3_tok
20870 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c enizer is disabl
20880 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a ed or enabled.**
20890 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 following this
208a0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e call. The secon
208b0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 d parameter may
208c0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 be a NULL pointe
208d0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 r, in.** which c
208e0 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 ase the new sett
208f0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 ing is not repor
20900 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a ted back. </dd>.
20910 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
20920 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
20930 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c _LOAD_EXTENSION<
20940 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 /dt>.** <dd> ^Th
20950 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 is option is use
20960 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 d to enable or d
20970 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69 isable the [sqli
20980 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 te3_load_extensi
20990 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 on()].** interfa
209a0 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 ce independently
209b0 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 of the [load_ex
209c0 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66 tension()] SQL f
209d0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 unction..** The
209e0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f [sqlite3_enable_
209f0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
20a00 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72 ] API enables or
20a10 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74 disables both t
20a20 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c he.** C-API [sql
20a30 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 ite3_load_extens
20a40 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53 ion()] and the S
20a50 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61 QL function [loa
20a60 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a d_extension()]..
20a70 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 ** There should
20a80 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 be two additiona
20a90 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 l arguments..**
20aa0 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61 When the first a
20ab0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 rgument to this
20ac0 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20 interface is 1,
20ad0 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d then only the C-
20ae0 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65 API is.** enable
20af0 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 d and the SQL fu
20b00 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64 nction remains d
20b10 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65 isabled. If the
20b20 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 first argument
20b30 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 to.** this inter
20b40 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20 face is 0, then
20b50 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61 both the C-API a
20b60 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 nd the SQL funct
20b70 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64 ion are disabled
20b80 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 ..** If the firs
20b90 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31 t argument is -1
20ba0 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65 , then no change
20bb0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74 s are made to st
20bc0 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68 ate of either th
20bd0 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68 e.** C-API or th
20be0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a e SQL function..
20bf0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 ** The second pa
20c00 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 rameter is a poi
20c10 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 nter to an integ
20c20 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a er into which.**
20c30 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 is written 0 or
20c40 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 1 to indicate w
20c50 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f hether [sqlite3_
20c60 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
20c70 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 ] interface.** i
20c80 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e s disabled or en
20c90 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20 abled following
20ca0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 this call. The
20cb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 second parameter
20cc0 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c may.** be a NUL
20cd0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68 L pointer, in wh
20ce0 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 ich case the new
20cf0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 setting is not
20d00 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a reported back..*
20d10 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 * </dd>.**.** <d
20d20 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
20d30 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74 G_MAINDBNAME</dt
20d40 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 >.** <dd> ^This
20d50 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 option is used t
20d60 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d o change the nam
20d70 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20 e of the "main"
20d80 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65 database.** sche
20d90 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61 ma. ^The sole a
20da0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
20db0 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61 nter to a consta
20dc0 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a nt UTF8 string.*
20dd0 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63 * which will bec
20de0 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65 ome the new sche
20df0 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65 ma name in place
20e00 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51 of "main". ^SQ
20e10 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 Lite.** does not
20e20 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 make a copy of
20e30 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68 the new main sch
20e40 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c ema name string,
20e50 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 so the applicat
20e60 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 ion.** must ensu
20e70 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75 re that the argu
20e80 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f ment passed into
20e90 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f this DBCONFIG o
20ea0 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67 ption is unchang
20eb0 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65 ed.** until afte
20ec0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 r the database c
20ed0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 onnection closes
20ee0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
20ef0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f <dt>SQLITE_DBCO
20f00 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f NFIG_NO_CKPT_ON_
20f10 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 CLOSE</dt>.** <d
20f20 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e d> Usually, when
20f30 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77 a database in w
20f40 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65 al mode is close
20f50 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72 d or detached fr
20f60 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73 om a .** databas
20f70 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65 e handle, SQLite
20f80 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20 checks if this
20f90 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74 will mean that t
20fa0 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20 here are now no
20fb0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 .** connections
20fc0 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61 at all to the da
20fd0 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69 tabase. If so, i
20fe0 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 t performs a che
20ff0 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72 ckpoint .** oper
21000 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f ation before clo
21010 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74 sing the connect
21020 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e ion. This option
21030 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a may be used to.
21040 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73 ** override this
21050 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20 behaviour. The
21060 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
21070 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f passed to this o
21080 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61 peration.** is a
21090 6e 20 69 6e 74 65 67 65 72 20 2d 20 70 6f 73 69 n integer - posi
210a0 74 69 76 65 20 74 6f 20 64 69 73 61 62 6c 65 20 tive to disable
210b0 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63 checkpoints-on-c
210c0 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74 lose, or zero (t
210d0 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74 he.** default) t
210e0 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2c 20 61 o enable them, a
210f0 6e 64 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c nd negative to l
21100 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 eave the setting
21110 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 unchanged..** T
21120 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 he second parame
21130 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 ter is a pointer
21140 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a to an integer.*
21150 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20 * into which is
21160 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 written 0 or 1 t
21170 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 o indicate wheth
21180 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f er checkpoints-o
21190 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20 n-close.** have
211a0 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20 been disabled -
211b0 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f 0 if they are no
211c0 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66 t disabled, 1 if
211d0 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f they are..** </
211e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 dd>.**.** <dt>SQ
211f0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
21200 41 42 4c 45 5f 51 50 53 47 3c 2f 64 74 3e 0a 2a ABLE_QPSG</dt>.*
21210 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 * <dd>^(The SQLI
21220 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
21230 4c 45 5f 51 50 53 47 20 6f 70 74 69 6f 6e 20 61 LE_QPSG option a
21240 63 74 69 76 61 74 65 73 20 6f 72 20 64 65 61 63 ctivates or deac
21250 74 69 76 61 74 65 73 0a 2a 2a 20 74 68 65 20 5b tivates.** the [
21260 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 73 74 query planner st
21270 61 62 69 6c 69 74 79 20 67 75 61 72 61 6e 74 65 ability guarante
21280 65 5d 20 28 51 50 53 47 29 2e 20 20 57 68 65 6e e] (QPSG). When
21290 20 74 68 65 20 51 50 53 47 20 69 73 20 61 63 74 the QPSG is act
212a0 69 76 65 2c 0a 2a 2a 20 61 20 73 69 6e 67 6c 65 ive,.** a single
212b0 20 53 51 4c 20 71 75 65 72 79 20 73 74 61 74 65 SQL query state
212c0 6d 65 6e 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 ment will always
212d0 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 61 6c use the same al
212e0 67 6f 72 69 74 68 6d 20 72 65 67 61 72 64 6c 65 gorithm regardle
212f0 73 73 0a 2a 2a 20 6f 66 20 76 61 6c 75 65 73 20 ss.** of values
21300 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 of [bound parame
21310 74 65 72 73 5d 2e 29 5e 20 54 68 65 20 51 50 53 ters].)^ The QPS
21320 47 20 64 69 73 61 62 6c 65 73 20 73 6f 6d 65 20 G disables some
21330 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 61 74 69 query optimizati
21340 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 6c 6f 6f 6b ons.** that look
21350 20 61 74 20 74 68 65 20 76 61 6c 75 65 73 20 6f at the values o
21360 66 20 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 f bound paramete
21370 72 73 2c 20 77 68 69 63 68 20 63 61 6e 20 6d 61 rs, which can ma
21380 6b 65 20 73 6f 6d 65 20 71 75 65 72 69 65 73 0a ke some queries.
21390 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 42 75 74 20 ** slower. But
213a0 74 68 65 20 51 50 53 47 20 68 61 73 20 74 68 65 the QPSG has the
213b0 20 61 64 76 61 6e 74 61 67 65 20 6f 66 20 6d 6f advantage of mo
213c0 72 65 20 70 72 65 64 69 63 74 61 62 6c 65 20 62 re predictable b
213d0 65 68 61 76 69 6f 72 2e 20 20 57 69 74 68 0a 2a ehavior. With.*
213e0 2a 20 74 68 65 20 51 50 53 47 20 61 63 74 69 76 * the QPSG activ
213f0 65 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 e, SQLite will a
21400 6c 77 61 79 73 20 75 73 65 20 74 68 65 20 73 61 lways use the sa
21410 6d 65 20 71 75 65 72 79 20 70 6c 61 6e 20 69 6e me query plan in
21420 20 74 68 65 20 66 69 65 6c 64 20 61 73 0a 2a 2a the field as.**
21430 20 77 61 73 20 75 73 65 64 20 64 75 72 69 6e 67 was used during
21440 20 74 65 73 74 69 6e 67 20 69 6e 20 74 68 65 20 testing in the
21450 6c 61 62 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 lab..** The firs
21460 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 t argument to th
21470 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 61 6e is setting is an
21480 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 integer which i
21490 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 0a s 0 to disable .
214a0 2a 2a 20 74 68 65 20 51 50 53 47 2c 20 70 6f 73 ** the QPSG, pos
214b0 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 itive to enable
214c0 51 50 53 47 2c 20 6f 72 20 6e 65 67 61 74 69 76 QPSG, or negativ
214d0 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 e to leave the s
214e0 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e etting.** unchan
214f0 67 65 64 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 ged. The second
21500 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
21510 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
21520 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a eger into which.
21530 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 ** is written 0
21540 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 or 1 to indicate
21550 20 77 68 65 74 68 65 72 20 74 68 65 20 51 50 53 whether the QPS
21560 47 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 G is disabled or
21570 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c enabled.** foll
21580 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e owing this call.
21590 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 .** </dd>.**.**
215a0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e <dt>SQLITE_DBCON
215b0 46 49 47 5f 54 52 49 47 47 45 52 5f 45 51 50 3c FIG_TRIGGER_EQP<
215c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 42 79 20 /dt>.** <dd> By
215d0 64 65 66 61 75 6c 74 2c 20 74 68 65 20 6f 75 74 default, the out
215e0 70 75 74 20 6f 66 20 45 58 50 4c 41 49 4e 20 51 put of EXPLAIN Q
215f0 55 45 52 59 20 50 4c 41 4e 20 63 6f 6d 6d 61 6e UERY PLAN comman
21600 64 73 20 64 6f 65 73 20 6e 6f 74 20 0a 2a 2a 20 ds does not .**
21610 69 6e 63 6c 75 64 65 20 6f 75 74 70 75 74 20 66 include output f
21620 6f 72 20 61 6e 79 20 6f 70 65 72 61 74 69 6f 6e or any operation
21630 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 s performed by t
21640 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2e rigger programs.
21650 20 54 68 69 73 0a 2a 2a 20 6f 70 74 69 6f 6e 20 This.** option
21660 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f is used to set o
21670 72 20 63 6c 65 61 72 20 28 74 68 65 20 64 65 66 r clear (the def
21680 61 75 6c 74 29 20 61 20 66 6c 61 67 20 74 68 61 ault) a flag tha
21690 74 20 67 6f 76 65 72 6e 73 20 74 68 69 73 0a 2a t governs this.*
216a0 2a 20 62 65 68 61 76 69 6f 72 2e 20 54 68 65 20 * behavior. The
216b0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
216c0 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f passed to this o
216d0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 69 peration is an i
216e0 6e 74 65 67 65 72 20 2d 0a 2a 2a 20 70 6f 73 69 nteger -.** posi
216f0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 6f tive to enable o
21700 75 74 70 75 74 20 66 6f 72 20 74 72 69 67 67 65 utput for trigge
21710 72 20 70 72 6f 67 72 61 6d 73 2c 20 6f 72 20 7a r programs, or z
21720 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20 69 ero to disable i
21730 74 2c 0a 2a 2a 20 6f 72 20 6e 65 67 61 74 69 76 t,.** or negativ
21740 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 e to leave the s
21750 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 etting unchanged
21760 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 ..** The second
21770 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 parameter is a p
21780 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
21790 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 20 eger into which
217a0 69 73 20 77 72 69 74 74 65 6e 20 0a 2a 2a 20 30 is written .** 0
217b0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 or 1 to indicat
217c0 65 20 77 68 65 74 68 65 72 20 6f 75 74 70 75 74 e whether output
217d0 2d 66 6f 72 2d 74 72 69 67 67 65 72 73 20 68 61 -for-triggers ha
217e0 73 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 s been disabled
217f0 2d 20 30 20 69 66 20 0a 2a 2a 20 69 74 20 69 73 - 0 if .** it is
21800 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31 not disabled, 1
21810 20 69 66 20 69 74 20 69 73 2e 20 20 0a 2a 2a 20 if it is. .**
21820 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e </dd>.**.** <dt>
21830 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
21840 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 3c 2f RESET_DATABASE</
21850 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 53 65 74 20 dt>.** <dd> Set
21860 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e the SQLITE_DBCON
21870 46 49 47 5f 52 45 53 45 54 5f 44 41 54 41 42 41 FIG_RESET_DATABA
21880 53 45 20 66 6c 61 67 20 61 6e 64 20 74 68 65 6e SE flag and then
21890 20 72 75 6e 0a 2a 2a 20 5b 56 41 43 55 55 4d 5d run.** [VACUUM]
218a0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 72 65 73 in order to res
218b0 65 74 20 61 20 64 61 74 61 62 61 73 65 20 62 61 et a database ba
218c0 63 6b 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 64 ck to an empty d
218d0 61 74 61 62 61 73 65 0a 2a 2a 20 77 69 74 68 20 atabase.** with
218e0 6e 6f 20 73 63 68 65 6d 61 20 61 6e 64 20 6e 6f no schema and no
218f0 20 63 6f 6e 74 65 6e 74 2e 20 54 68 65 20 66 6f content. The fo
21900 6c 6c 6f 77 69 6e 67 20 70 72 6f 63 65 73 73 20 llowing process
21910 77 6f 72 6b 73 20 65 76 65 6e 20 66 6f 72 0a 2a works even for.*
21920 2a 20 61 20 62 61 64 6c 79 20 63 6f 72 72 75 70 * a badly corrup
21930 74 65 64 20 64 61 74 61 62 61 73 65 20 66 69 6c ted database fil
21940 65 3a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c e:.** <ol>.** <l
21950 69 3e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 i> If the databa
21960 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
21970 20 6e 65 77 6c 79 20 6f 70 65 6e 65 64 2c 20 6d newly opened, m
21980 61 6b 65 20 73 75 72 65 20 69 74 20 68 61 73 20 ake sure it has
21990 72 65 61 64 20 74 68 65 0a 2a 2a 20 20 20 20 20 read the.**
219a0 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 database schema
219b0 20 62 79 20 70 72 65 70 61 72 69 6e 67 20 74 68 by preparing th
219c0 65 6e 20 64 69 73 63 61 72 64 69 6e 67 20 73 6f en discarding so
219d0 6d 65 20 71 75 65 72 79 20 61 67 61 69 6e 73 74 me query against
219e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 64 61 74 the.** dat
219f0 61 62 61 73 65 2c 20 6f 72 20 63 61 6c 6c 69 6e abase, or callin
21a00 67 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65 5f g sqlite3_table_
21a10 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61 28 column_metadata(
21a20 29 2c 20 69 67 6e 6f 72 69 6e 67 20 61 6e 79 0a ), ignoring any.
21a30 2a 2a 20 20 20 20 20 20 65 72 72 6f 72 73 2e 20 ** errors.
21a40 20 54 68 69 73 20 73 74 65 70 20 69 73 20 6f 6e This step is on
21a50 6c 79 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 ly necessary if
21a60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 the application
21a70 64 65 73 69 72 65 73 20 74 6f 20 6b 65 65 70 0a desires to keep.
21a80 2a 2a 20 20 20 20 20 20 74 68 65 20 64 61 74 61 ** the data
21a90 62 61 73 65 20 69 6e 20 57 41 4c 20 6d 6f 64 65 base in WAL mode
21aa0 20 61 66 74 65 72 20 74 68 65 20 72 65 73 65 74 after the reset
21ab0 20 69 66 20 69 74 20 77 61 73 20 69 6e 20 57 41 if it was in WA
21ac0 4c 20 6d 6f 64 65 20 62 65 66 6f 72 65 0a 2a 2a L mode before.**
21ad0 20 20 20 20 20 20 74 68 65 20 72 65 73 65 74 2e the reset.
21ae0 20 20 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 .** <li> sqlit
21af0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 64 62 2c e3_db_config(db,
21b00 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
21b10 5f 52 45 53 45 54 5f 44 41 54 41 42 41 53 45 2c _RESET_DATABASE,
21b20 20 31 2c 20 30 29 3b 0a 2a 2a 20 3c 6c 69 3e 20 1, 0);.** <li>
21b30 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 5d 28 64 [sqlite3_exec](d
21b40 62 2c 20 22 5b 56 41 43 55 55 4d 5d 22 2c 20 30 b, "[VACUUM]", 0
21b50 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 3c 6c 69 3e , 0, 0);.** <li>
21b60 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 sqlite3_db_conf
21b70 69 67 28 64 62 2c 20 53 51 4c 49 54 45 5f 44 42 ig(db, SQLITE_DB
21b80 43 4f 4e 46 49 47 5f 52 45 53 45 54 5f 44 41 54 CONFIG_RESET_DAT
21b90 41 42 41 53 45 2c 20 30 2c 20 30 29 3b 0a 2a 2a ABASE, 0, 0);.**
21ba0 20 3c 2f 6f 6c 3e 0a 2a 2a 20 42 65 63 61 75 73 </ol>.** Becaus
21bb0 65 20 72 65 73 65 74 74 69 6e 67 20 61 20 64 61 e resetting a da
21bc0 74 61 62 61 73 65 20 69 73 20 64 65 73 74 72 75 tabase is destru
21bd0 63 74 69 76 65 20 61 6e 64 20 69 72 72 65 76 65 ctive and irreve
21be0 72 73 69 62 6c 65 2c 20 74 68 65 0a 2a 2a 20 70 rsible, the.** p
21bf0 72 6f 63 65 73 73 20 72 65 71 75 69 72 65 73 20 rocess requires
21c00 74 68 65 20 75 73 65 20 6f 66 20 74 68 69 73 20 the use of this
21c10 6f 62 73 63 75 72 65 20 41 50 49 20 61 6e 64 20 obscure API and
21c20 6d 75 6c 74 69 70 6c 65 20 73 74 65 70 73 20 74 multiple steps t
21c30 6f 20 68 65 6c 70 0a 2a 2a 20 65 6e 73 75 72 65 o help.** ensure
21c40 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f that it does no
21c50 74 20 68 61 70 70 65 6e 20 62 79 20 61 63 63 69 t happen by acci
21c60 64 65 6e 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a dent..** </dd>.*
21c70 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
21c80 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
21c90 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 IG_MAINDBNAME
21ca0 20 20 20 20 20 20 20 20 20 31 30 30 30 20 2f 2a 1000 /*
21cb0 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a const char* */.
21cc0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
21cd0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 BCONFIG_LOOKASID
21ce0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 E 10
21cf0 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 01 /* void* int
21d00 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 int */.#define S
21d10 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 QLITE_DBCONFIG_E
21d20 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 NABLE_FKEY
21d30 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 1002 /* int
21d40 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 int* */.#define
21d50 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 SQLITE_DBCONFIG
21d60 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 _ENABLE_TRIGGER
21d70 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69 1003 /* i
21d80 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 nt int* */.#defi
21d90 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 ne SQLITE_DBCONF
21da0 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 IG_ENABLE_FTS3_T
21db0 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a OKENIZER 1004 /*
21dc0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 int int* */.#de
21dd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
21de0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 NFIG_ENABLE_LOAD
21df0 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 _EXTENSION 1005
21e00 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 /* int int* */.#
21e10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 define SQLITE_DB
21e20 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f CONFIG_NO_CKPT_O
21e30 4e 5f 43 4c 4f 53 45 20 20 20 20 20 20 31 30 30 N_CLOSE 100
21e40 36 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 6 /* int int* */
21e50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
21e60 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
21e70 51 50 53 47 20 20 20 20 20 20 20 20 20 20 20 31 QPSG 1
21e80 30 30 37 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 007 /* int int*
21e90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
21ea0 45 5f 44 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 E_DBCONFIG_TRIGG
21eb0 45 52 5f 45 51 50 20 20 20 20 20 20 20 20 20 20 ER_EQP
21ec0 20 31 30 30 38 20 2f 2a 20 69 6e 74 20 69 6e 74 1008 /* int int
21ed0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c * */.#define SQL
21ee0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 52 45 53 ITE_DBCONFIG_RES
21ef0 45 54 5f 44 41 54 41 42 41 53 45 20 20 20 20 20 ET_DATABASE
21f00 20 20 20 31 30 30 39 20 2f 2a 20 69 6e 74 20 69 1009 /* int i
21f10 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 nt* */.#define S
21f20 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d QLITE_DBCONFIG_M
21f30 41 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AX
21f40 20 20 20 20 20 31 30 30 39 20 2f 2a 20 4c 61 72 1009 /* Lar
21f50 67 65 73 74 20 44 42 43 4f 4e 46 49 47 20 2a 2f gest DBCONFIG */
21f60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
21f70 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 : Enable Or Disa
21f80 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 ble Extended Res
21f90 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 ult Codes.** MET
21fa0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
21fb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
21fc0 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f extended_result_
21fd0 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 codes() routine
21fe0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
21ff0 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 les the.** [exte
22000 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 nded result code
22010 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 s] feature of SQ
22020 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e Lite. ^The exten
22030 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f ded result.** co
22040 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 des are disabled
22050 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 by default for
22060 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 historical compa
22070 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c tibility..*/.SQL
22080 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
22090 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 te3_extended_res
220a0 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 ult_codes(sqlite
220b0 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 3*, int onoff);.
220c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
220d0 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 Last Insert Row
220e0 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 id.** METHOD: sq
220f0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 lite3.**.** ^Eac
22100 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 h entry in most
22110 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 SQLite tables (e
22120 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f xcept for [WITHO
22130 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 UT ROWID] tables
22140 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 ).** has a uniqu
22150 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a e 64-bit signed.
22160 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 ** integer key c
22170 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 alled the [ROWID
22180 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 | "rowid"]. ^Th
22190 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 e rowid is alway
221a0 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 s available.** a
221b0 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 s an undeclared
221c0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 column named ROW
221d0 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 ID, OID, or _ROW
221e0 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 ID_ as long as t
221f0 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 hose.** names ar
22200 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 e not also used
22210 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 by explicitly de
22220 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 clared columns.
22230 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 ^If.** the table
22240 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 has a column of
22250 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 type [INTEGER P
22260 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e RIMARY KEY] then
22270 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 that column.**
22280 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 is another alias
22290 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a for the rowid..
222a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
222b0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
222c0 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 owid(D) interfac
222d0 65 20 75 73 75 61 6c 6c 79 20 72 65 74 75 72 6e e usually return
222e0 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 s the [rowid] of
222f0 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 .** the most rec
22300 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b ent successful [
22310 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 INSERT] into a r
22320 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 owid table or [v
22330 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a irtual table].**
22340 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e on database con
22350 6e 65 63 74 69 6f 6e 20 44 2e 20 5e 49 6e 73 65 nection D. ^Inse
22360 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 rts into [WITHOU
22370 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 T ROWID] tables
22380 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 72 are not.** recor
22390 64 65 64 2e 20 5e 49 66 20 6e 6f 20 73 75 63 63 ded. ^If no succ
223a0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 essful [INSERT]s
223b0 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c into rowid tabl
223c0 65 73 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 es have ever occ
223d0 75 72 72 65 64 20 0a 2a 2a 20 6f 6e 20 74 68 65 urred .** on the
223e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
223f0 74 69 6f 6e 20 44 2c 20 74 68 65 6e 20 73 71 6c tion D, then sql
22400 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 ite3_last_insert
22410 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e _rowid(D) return
22420 73 20 0a 2a 2a 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a s .** zero..**.*
22430 2a 20 41 73 20 77 65 6c 6c 20 61 73 20 62 65 69 * As well as bei
22440 6e 67 20 73 65 74 20 61 75 74 6f 6d 61 74 69 63 ng set automatic
22450 61 6c 6c 79 20 61 73 20 72 6f 77 73 20 61 72 65 ally as rows are
22460 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 64 inserted into d
22470 61 74 61 62 61 73 65 0a 2a 2a 20 74 61 62 6c 65 atabase.** table
22480 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 s, the value ret
22490 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 urned by this fu
224a0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 73 65 nction may be se
224b0 74 20 65 78 70 6c 69 63 69 74 6c 79 20 62 79 0a t explicitly by.
224c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f ** [sqlite3_set_
224d0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
224e0 64 28 29 5d 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 d()].**.** Some
224f0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d virtual table im
22500 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 plementations ma
22510 79 20 49 4e 53 45 52 54 20 72 6f 77 73 20 69 6e y INSERT rows in
22520 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 to rowid tables
22530 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 63 6f as.** part of co
22540 6d 6d 69 74 74 69 6e 67 20 61 20 74 72 61 6e 73 mmitting a trans
22550 61 63 74 69 6f 6e 20 28 65 2e 67 2e 20 74 6f 20 action (e.g. to
22560 66 6c 75 73 68 20 64 61 74 61 20 61 63 63 75 6d flush data accum
22570 75 6c 61 74 65 64 20 69 6e 20 6d 65 6d 6f 72 79 ulated in memory
22580 0a 2a 2a 20 74 6f 20 64 69 73 6b 29 2e 20 49 6e .** to disk). In
22590 20 74 68 69 73 20 63 61 73 65 20 73 75 62 73 65 this case subse
225a0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 74 quent calls to t
225b0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 his function ret
225c0 75 72 6e 20 74 68 65 20 72 6f 77 69 64 0a 2a 2a urn the rowid.**
225d0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 associated with
225e0 20 74 68 65 73 65 20 69 6e 74 65 72 6e 61 6c 20 these internal
225f0 49 4e 53 45 52 54 20 6f 70 65 72 61 74 69 6f 6e INSERT operation
22600 73 2c 20 77 68 69 63 68 20 6c 65 61 64 73 20 74 s, which leads t
22610 6f 20 0a 2a 2a 20 75 6e 69 6e 74 75 69 74 69 76 o .** unintuitiv
22620 65 20 72 65 73 75 6c 74 73 2e 20 56 69 72 74 75 e results. Virtu
22630 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 al table impleme
22640 6e 74 61 74 69 6f 6e 73 20 74 68 61 74 20 64 6f ntations that do
22650 20 77 72 69 74 65 20 74 6f 20 72 6f 77 69 64 0a write to rowid.
22660 2a 2a 20 74 61 62 6c 65 73 20 69 6e 20 74 68 69 ** tables in thi
22670 73 20 77 61 79 20 63 61 6e 20 61 76 6f 69 64 20 s way can avoid
22680 74 68 69 73 20 70 72 6f 62 6c 65 6d 20 62 79 20 this problem by
22690 72 65 73 74 6f 72 69 6e 67 20 74 68 65 20 6f 72 restoring the or
226a0 69 67 69 6e 61 6c 20 0a 2a 2a 20 72 6f 77 69 64 iginal .** rowid
226b0 20 76 61 6c 75 65 20 75 73 69 6e 67 20 5b 73 71 value using [sq
226c0 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 lite3_set_last_i
226d0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 62 nsert_rowid()] b
226e0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 efore returning
226f0 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 74 6f 20 74 .** control to t
22700 68 65 20 75 73 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e he user..**.** ^
22710 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 (If an [INSERT]
22720 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 occurs within a
22730 74 72 69 67 67 65 72 20 74 68 65 6e 20 74 68 69 trigger then thi
22740 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 0a s routine will .
22750 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 ** return the [r
22760 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 owid] of the ins
22770 65 72 74 65 64 20 72 6f 77 20 61 73 20 6c 6f 6e erted row as lon
22780 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 g as the trigger
22790 20 69 73 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 2e is .** running.
227a0 20 4f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 Once the trigge
227b0 72 20 70 72 6f 67 72 61 6d 20 65 6e 64 73 2c 20 r program ends,
227c0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
227d0 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 ed .** by this r
227e0 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 outine reverts t
227f0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 o what it was be
22800 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 fore the trigger
22810 20 77 61 73 20 66 69 72 65 64 2e 29 5e 0a 2a 2a was fired.)^.**
22820 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d .** ^An [INSERT]
22830 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 that fails due
22840 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 to a constraint
22850 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 violation is not
22860 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c a.** successful
22870 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f [INSERT] and do
22880 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 es not change th
22890 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
228a0 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 by this.** rout
228b0 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 ine. ^Thus INSE
228c0 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 RT OR FAIL, INSE
228d0 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e RT OR IGNORE, IN
228e0 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b SERT OR ROLLBACK
228f0 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 ,.** and INSERT
22900 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f OR ABORT make no
22910 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 changes to the
22920 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 return value of
22930 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 this.** routine
22940 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 when their inser
22950 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 tion fails. ^(W
22960 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 hen INSERT OR RE
22970 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 PLACE.** encount
22980 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 ers a constraint
22990 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 violation, it d
229a0 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 oes not fail. T
229b0 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e he.** INSERT con
229c0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 tinues to comple
229d0 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 tion after delet
229e0 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 ing rows that ca
229f0 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 used.** the cons
22a00 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 traint problem s
22a10 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c o INSERT OR REPL
22a20 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 ACE will always
22a30 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 change.** the re
22a40 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 turn value of th
22a50 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a is interface.)^.
22a60 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 **.** ^For the p
22a70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 urposes of this
22a80 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 routine, an [INS
22a90 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 ERT] is consider
22aa0 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 ed to.** be succ
22ab0 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 essful even if i
22ac0 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c t is subsequentl
22ad0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a y rolled back..*
22ae0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 *.** This functi
22af0 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 on is accessible
22b00 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e to SQL statemen
22b10 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c ts via the.** [l
22b20 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 ast_insert_rowid
22b30 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
22b40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 ..**.** If a sep
22b50 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 arate thread per
22b60 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 forms a new [INS
22b70 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 ERT] on the same
22b80 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e .** database con
22b90 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 nection while th
22ba0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f e [sqlite3_last_
22bb0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a insert_rowid()].
22bc0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 ** function is r
22bd0 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 unning and thus
22be0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 changes the last
22bf0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c insert [rowid],
22c00 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c .** then the val
22c10 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b ue returned by [
22c20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 sqlite3_last_ins
22c30 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a ert_rowid()] is.
22c40 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 ** unpredictable
22c50 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 and might not e
22c60 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 qual either the
22c70 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a old or the new.*
22c80 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 * last insert [r
22c90 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 owid]..*/.SQLITE
22ca0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 _API sqlite3_int
22cb0 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 64 sqlite3_last_
22cc0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c insert_rowid(sql
22cd0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ite3*);../*.** C
22ce0 41 50 49 33 52 45 46 3a 20 53 65 74 20 74 68 65 API3REF: Set the
22cf0 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 Last Insert Row
22d00 69 64 20 76 61 6c 75 65 2e 0a 2a 2a 20 4d 45 54 id value..** MET
22d10 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
22d20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 ** The sqlite3_s
22d30 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 et_last_insert_r
22d40 6f 77 69 64 28 44 2c 20 52 29 20 6d 65 74 68 6f owid(D, R) metho
22d50 64 20 61 6c 6c 6f 77 73 20 74 68 65 20 61 70 70 d allows the app
22d60 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 73 lication to.** s
22d70 65 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 et the value ret
22d80 75 72 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 urned by calling
22d90 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e sqlite3_last_in
22da0 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 74 6f sert_rowid(D) to
22db0 20 52 20 0a 2a 2a 20 77 69 74 68 6f 75 74 20 69 R .** without i
22dc0 6e 73 65 72 74 69 6e 67 20 61 20 72 6f 77 20 69 nserting a row i
22dd0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 nto the database
22de0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
22df0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 void sqlite3_set
22e00 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 _last_insert_row
22e10 69 64 28 73 71 6c 69 74 65 33 2a 2c 73 71 6c 69 id(sqlite3*,sqli
22e20 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a te3_int64);../*.
22e30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 ** CAPI3REF: Cou
22e40 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 nt The Number Of
22e50 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a Rows Modified.*
22e60 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
22e70 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 3.**.** ^This fu
22e80 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 nction returns t
22e90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 he number of row
22ea0 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73 65 s modified, inse
22eb0 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 rted or.** delet
22ec0 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 ed by the most r
22ed0 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 ecently complete
22ee0 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 d INSERT, UPDATE
22ef0 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 or DELETE.** st
22f00 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20 64 atement on the d
22f10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
22f20 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79 20 on specified by
22f30 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 the only paramet
22f40 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69 6e er..** ^Executin
22f50 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 g any other type
22f60 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e of SQL statemen
22f70 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69 66 t does not modif
22f80 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 y the value.** r
22f90 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 eturned by this
22fa0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 function..**.**
22fb0 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 ^Only changes ma
22fc0 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20 74 de directly by t
22fd0 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 he INSERT, UPDAT
22fe0 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 E or DELETE stat
22ff0 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f 6e ement are.** con
23000 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c 69 sidered - auxili
23010 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 ary changes caus
23020 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54 52 ed by [CREATE TR
23030 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 IGGER | triggers
23040 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 ], .** [foreign
23050 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72 20 key actions] or
23060 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 [REPLACE] constr
23070 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 aint resolution
23080 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e are not counted.
23090 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73 20 .** .** Changes
230a0 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 to a view that a
230b0 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62 re intercepted b
230c0 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20 4f y .** [INSTEAD O
230d0 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53 54 F trigger | INST
230e0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 5d EAD OF triggers]
230f0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 are not counted
23100 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a 2a . ^The value .**
23110 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c returned by sql
23120 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 ite3_changes() i
23130 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72 mmediately after
23140 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 an INSERT, UPDA
23150 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54 45 TE or .** DELETE
23160 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20 6f statement run o
23170 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77 61 n a view is alwa
23180 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 ys zero. Only ch
23190 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72 65 anges made to re
231a0 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61 72 al .** tables ar
231b0 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a e counted..**.**
231c0 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72 65 Things are more
231d0 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66 20 complicated if
231e0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e the sqlite3_chan
231f0 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 ges() function i
23200 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77 68 s.** executed wh
23210 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70 72 ile a trigger pr
23220 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e 67 ogram is running
23230 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70 65 . This may happe
23240 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f 67 n if the.** prog
23250 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63 68 ram uses the [ch
23260 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 anges() SQL func
23270 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f 6d tion], or if som
23280 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63 6b e other callback
23290 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e 76 .** function inv
232a0 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68 61 okes sqlite3_cha
232b0 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79 2e nges() directly.
232c0 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a Essentially:.**
232d0 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c .** <ul>.** <
232e0 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e 74 li> ^(Before ent
232f0 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72 20 ering a trigger
23300 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c 75 program the valu
23310 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a e returned by.**
23320 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f sqlite3_
23330 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 changes() functi
23340 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66 74 on is saved. Aft
23350 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20 70 er the trigger p
23360 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20 20 rogram .**
23370 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c 20 has finished,
23380 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61 6c the original val
23390 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e 29 ue is restored.)
233a0 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 ^.** .** <li>
233b0 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67 67 ^(Within a trigg
233c0 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68 20 er program each
233d0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 61 INSERT, UPDATE a
233e0 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20 20 nd DELETE .**
233f0 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20 73 statement s
23400 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72 65 ets the value re
23410 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
23420 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 3_changes() .**
23430 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d 70 upon comp
23440 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c letion as normal
23450 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68 69 . Of course, thi
23460 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 s value will not
23470 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20 20 include .**
23480 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73 20 any changes
23490 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75 62 performed by sub
234a0 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74 68 -triggers, as th
234b0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 e sqlite3_change
234c0 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 76 s() .** v
234d0 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61 76 alue will be sav
234e0 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64 20 ed and restored
234f0 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d 74 after each sub-t
23500 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e 29 rigger has run.)
23510 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a ^.** </ul>.** .*
23520 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74 68 * ^This means th
23530 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67 65 at if the change
23540 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e s() SQL function
23550 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69 73 (or similar) is
23560 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 used.** by the
23570 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55 50 first INSERT, UP
23580 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 DATE or DELETE s
23590 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 tatement within
235a0 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a 2a a trigger, it .*
235b0 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 * returns the va
235c0 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e 20 lue as set when
235d0 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61 74 the calling stat
235e0 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65 63 ement began exec
235f0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 uting..** ^If it
23600 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 is used by the
23610 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65 71 second or subseq
23620 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65 6d uent such statem
23630 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 ent within a tri
23640 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61 6d gger .** program
23650 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 , the value retu
23660 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74 68 rned reflects th
23670 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 e number of rows
23680 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68 65 modified by the
23690 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49 4e .** previous IN
236a0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
236b0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
236c0 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
236d0 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 trigger..**.**
236e0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
236f0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
23700 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
23710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
23720 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
23730 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 ite3_changes()]
23740 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 is running then
23750 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e the value return
23760 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 ed.** is unpredi
23770 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d ctable and not m
23780 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2a 0a 2a 2a eaningful..**.**
23790 20 53 65 65 20 61 6c 73 6f 3a 0a 2a 2a 20 3c 75 See also:.** <u
237a0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b l>.** <li> the [
237b0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 sqlite3_total_ch
237c0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 anges()] interfa
237d0 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b ce.** <li> the [
237e0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 count_changes pr
237f0 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 agma].** <li> th
23800 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c e [changes() SQL
23810 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c function].** <l
23820 69 3e 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72 i> the [data_ver
23830 73 69 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 sion pragma].**
23840 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f </ul>.*/.SQLITE_
23850 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
23860 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a changes(sqlite3*
23870 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
23880 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 EF: Total Number
23890 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 Of Rows Modifie
238a0 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c d.** METHOD: sql
238b0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 ite3.**.** ^This
238c0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e function return
238d0 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 s the total numb
238e0 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 er of rows inser
238f0 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 ted, modified or
23900 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 .** deleted by a
23910 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 ll [INSERT], [UP
23920 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 DATE] or [DELETE
23930 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d ] statements com
23940 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 pleted.** since
23950 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
23960 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e nection was open
23970 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 ed, including th
23980 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a ose executed as.
23990 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 ** part of trigg
239a0 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 er programs. ^Ex
239b0 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 ecuting any othe
239c0 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 r type of SQL st
239d0 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 atement.** does
239e0 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76 not affect the v
239f0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 alue returned by
23a00 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 sqlite3_total_c
23a10 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a hanges()..** .**
23a20 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 ^Changes made a
23a30 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 s part of [forei
23a40 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 gn key actions]
23a50 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 are included in
23a60 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 the.** count, bu
23a70 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 t those made as
23a80 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 part of REPLACE
23a90 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c constraint resol
23aa0 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 ution are.** not
23ab0 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 . ^Changes to a
23ac0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e view that are in
23ad0 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 tercepted by INS
23ae0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 TEAD OF triggers
23af0 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 .** are not cou
23b00 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 nted..**.** This
23b10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f the [sqlite3_to
23b20 74 61 6c 5f 63 68 61 6e 67 65 73 28 44 29 5d 20 tal_changes(D)]
23b30 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 interface only r
23b40 65 70 6f 72 74 73 20 74 68 65 20 6e 75 6d 62 65 eports the numbe
23b50 72 0a 2a 2a 20 6f 66 20 72 6f 77 73 20 74 68 61 r.** of rows tha
23b60 74 20 63 68 61 6e 67 65 64 20 64 75 65 20 74 6f t changed due to
23b70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 72 SQL statement r
23b80 75 6e 20 61 67 61 69 6e 73 74 20 64 61 74 61 62 un against datab
23b90 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f ase.** connectio
23ba0 6e 20 44 2e 20 20 41 6e 79 20 63 68 61 6e 67 65 n D. Any change
23bb0 73 20 62 79 20 6f 74 68 65 72 20 64 61 74 61 62 s by other datab
23bc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
23bd0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 20 are ignored..**
23be0 54 6f 20 64 65 74 65 63 74 20 63 68 61 6e 67 65 To detect change
23bf0 73 20 61 67 61 69 6e 73 74 20 61 20 64 61 74 61 s against a data
23c00 62 61 73 65 20 66 69 6c 65 20 66 72 6f 6d 20 6f base file from o
23c10 74 68 65 72 20 64 61 74 61 62 61 73 65 0a 2a 2a ther database.**
23c20 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 75 73 65 connections use
23c30 20 74 68 65 20 5b 50 52 41 47 4d 41 20 64 61 74 the [PRAGMA dat
23c40 61 5f 76 65 72 73 69 6f 6e 5d 20 63 6f 6d 6d 61 a_version] comma
23c50 6e 64 20 6f 72 20 74 68 65 0a 2a 2a 20 5b 53 51 nd or the.** [SQ
23c60 4c 49 54 45 5f 46 43 4e 54 4c 5f 44 41 54 41 5f LITE_FCNTL_DATA_
23c70 56 45 52 53 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 VERSION] [file c
23c80 6f 6e 74 72 6f 6c 5d 2e 0a 2a 2a 20 0a 2a 2a 20 ontrol]..** .**
23c90 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 If a separate th
23ca0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 read makes chang
23cb0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 es on the same d
23cc0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
23cd0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c on.** while [sql
23ce0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 ite3_total_chang
23cf0 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 es()] is running
23d00 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a then the value.
23d10 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 ** returned is u
23d20 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 npredictable and
23d30 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e not meaningful.
23d40 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a .**.** See also:
23d50 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ul>.** <li>
23d60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 the [sqlite3_ch
23d70 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 anges()] interfa
23d80 63 65 0a 2a 2a 20 3c 6c 69 3e 20 74 68 65 20 5b ce.** <li> the [
23d90 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 count_changes pr
23da0 61 67 6d 61 5d 0a 2a 2a 20 3c 6c 69 3e 20 74 68 agma].** <li> th
23db0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c e [changes() SQL
23dc0 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2a 20 3c 6c function].** <l
23dd0 69 3e 20 74 68 65 20 5b 64 61 74 61 5f 76 65 72 i> the [data_ver
23de0 73 69 6f 6e 20 70 72 61 67 6d 61 5d 0a 2a 2a 20 sion pragma].**
23df0 3c 6c 69 3e 20 74 68 65 20 5b 53 51 4c 49 54 45 <li> the [SQLITE
23e00 5f 46 43 4e 54 4c 5f 44 41 54 41 5f 56 45 52 53 _FCNTL_DATA_VERS
23e10 49 4f 4e 5d 20 5b 66 69 6c 65 20 63 6f 6e 74 72 ION] [file contr
23e20 6f 6c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a ol].** </ul>.*/.
23e30 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
23e40 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 qlite3_total_cha
23e50 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a nges(sqlite3*);.
23e60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
23e70 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e Interrupt A Lon
23e80 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a g-Running Query.
23e90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
23ea0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 e3.**.** ^This f
23eb0 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 unction causes a
23ec0 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 ny pending datab
23ed0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f ase operation to
23ee0 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 abort and.** re
23ef0 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c turn at its earl
23f00 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 iest opportunity
23f10 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 . This routine i
23f20 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 s typically.** c
23f30 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 alled in respons
23f40 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 e to a user acti
23f50 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73 on such as press
23f60 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 ing "Cancel".**
23f70 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 or Ctrl-C where
23f80 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 the user wants a
23f90 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 long query oper
23fa0 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a ation to halt.**
23fb0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a immediately..**
23fc0 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 .** ^It is safe
23fd0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 to call this rou
23fe0 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 tine from a thre
23ff0 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f ad different fro
24000 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 m the.** thread
24010 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c that is currentl
24020 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 y running the da
24030 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e tabase operation
24040 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 . But it.** is
24050 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c not safe to call
24060 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 this routine wi
24070 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 th a [database c
24080 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a onnection] that.
24090 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 ** is closed or
240a0 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f might close befo
240b0 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 re sqlite3_inter
240c0 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a rupt() returns..
240d0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c **.** ^If an SQL
240e0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 operation is ve
240f0 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 ry nearly finish
24100 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 ed at the time w
24110 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 hen.** sqlite3_i
24120 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61 nterrupt() is ca
24130 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 lled, then it mi
24140 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 ght not have an
24150 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 opportunity.** t
24160 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 o be interrupted
24170 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 and might conti
24180 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f nue to completio
24190 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c n..**.** ^An SQL
241a0 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 operation that
241b0 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 is interrupted w
241c0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 ill return [SQLI
241d0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a TE_INTERRUPT]..*
241e0 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 * ^If the interr
241f0 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 upted SQL operat
24200 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 ion is an INSERT
24210 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c , UPDATE, or DEL
24220 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 ETE.** that is i
24230 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 nside an explici
24240 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 t transaction, t
24250 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 hen the entire t
24260 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 ransaction.** wi
24270 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 ll be rolled bac
24280 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e k automatically.
24290 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
242a0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 te3_interrupt(D)
242b0 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 call is in effe
242c0 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 ct until all cur
242d0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a rently running.*
242e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 * SQL statements
242f0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f on [database co
24300 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 nnection] D comp
24310 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 lete. ^Any new
24320 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a SQL statements.*
24330 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 * that are start
24340 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c ed after the sql
24350 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 ite3_interrupt()
24360 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 call and before
24370 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 the .** running
24380 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 statements reac
24390 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 hes zero are int
243a0 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74 errupted as if t
243b0 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 hey had been.**
243c0 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f running prior to
243d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
243e0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 errupt() call.
243f0 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 ^New SQL stateme
24400 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
24410 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
24420 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d e running statem
24430 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 ent count reache
24440 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f s zero are.** no
24450 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68 t effected by th
24460 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
24470 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c upt()..** ^A cal
24480 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 l to sqlite3_int
24490 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f errupt(D) that o
244a0 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 ccurs when there
244b0 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a are no running.
244c0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ** SQL statement
244d0 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 s is a no-op and
244e0 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f has no effect o
244f0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 n SQL statements
24500 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 .** that are sta
24510 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 rted after the s
24520 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
24530 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e () call returns.
24540 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .*/.SQLITE_API v
24550 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 oid sqlite3_inte
24560 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b rrupt(sqlite3*);
24570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
24580 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 : Determine If A
24590 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 n SQL Statement
245a0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a Is Complete.**.*
245b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
245c0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 are useful duri
245d0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 ng command-line
245e0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 input to determi
245f0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 ne if the.** cur
24600 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 rently entered t
24610 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 ext seems to for
24620 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c m a complete SQL
24630 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a statement or.**
24640 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 if additional i
24650 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 nput is needed b
24660 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 efore sending th
24670 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 e text into.** S
24680 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e QLite for parsin
24690 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 g. ^These routi
246a0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 nes return 1 if
246b0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 the input string
246c0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 .** appears to b
246d0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c e a complete SQL
246e0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 statement. ^A
246f0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 statement is jud
24700 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d ged to be.** com
24710 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 plete if it ends
24720 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f with a semicolo
24730 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e n token and is n
24740 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 ot a prefix of a
24750 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 .** well-formed
24760 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 CREATE TRIGGER s
24770 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 tatement. ^Semi
24780 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 colons that are
24790 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a embedded within.
247a0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 ** string litera
247b0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 ls or quoted ide
247c0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 ntifier names or
247d0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f comments are no
247e0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 t.** independent
247f0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 tokens (they ar
24800 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f e part of the to
24810 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 ken in which the
24820 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 y are.** embedde
24830 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e d) and thus do n
24840 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 ot count as a st
24850 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 atement terminat
24860 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 or. ^Whitespace
24870 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 .** and comments
24880 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 that follow the
24890 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e final semicolon
248a0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a are ignored..**
248b0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 .** ^These routi
248c0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 nes return 0 if
248d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 the statement is
248e0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 incomplete. ^I
248f0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c f a.** memory al
24900 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 location fails,
24910 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 then SQLITE_NOME
24920 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a M is returned..*
24930 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 *.** ^These rout
24940 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 ines do not pars
24950 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d e the SQL statem
24960 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c ents thus.** wil
24970 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e l not detect syn
24980 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 tactically incor
24990 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 rect SQL..**.**
249a0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 ^(If SQLite has
249b0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c not been initial
249c0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ized using [sqli
249d0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
249e0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 ] prior .** to i
249f0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f nvoking sqlite3_
24a00 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 complete16() the
24a10 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 n sqlite3_initia
24a20 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 lize() is invoke
24a30 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c d.** automatical
24a40 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f ly by sqlite3_co
24a50 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 mplete16(). If
24a60 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 that initializat
24a70 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 ion fails,.** th
24a80 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 en the return va
24a90 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 lue from sqlite3
24aa0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 _complete16() wi
24ab0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a ll be non-zero.*
24ac0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 * regardless of
24ad0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
24ae0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 he input SQL is
24af0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a complete.)^.**.*
24b00 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b * The input to [
24b10 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 sqlite3_complete
24b20 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 ()] must be a ze
24b30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a ro-terminated.**
24b40 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a UTF-8 string..*
24b50 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 *.** The input t
24b60 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c o [sqlite3_compl
24b70 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 ete16()] must be
24b80 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 a zero-terminat
24b90 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 ed.** UTF-16 str
24ba0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 ing in native by
24bb0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c te order..*/.SQL
24bc0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
24bd0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e te3_complete(con
24be0 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 st char *sql);.S
24bf0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
24c00 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 lite3_complete16
24c10 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c (const void *sql
24c20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
24c30 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 EF: Register A C
24c40 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c allback To Handl
24c50 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 e SQLITE_BUSY Er
24c60 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 rors.** KEYWORDS
24c70 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 : {busy-handler
24c80 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 callback} {busy
24c90 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 handler}.** METH
24ca0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
24cb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 * ^The sqlite3_b
24cc0 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c usy_handler(D,X,
24cd0 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 P) routine sets
24ce0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
24cf0 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 ion X.** that mi
24d00 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 ght be invoked w
24d10 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 ith argument P w
24d20 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 henever.** an at
24d30 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f tempt is made to
24d40 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 access a databa
24d50 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 se table associa
24d60 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 ted with.** [dat
24d70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
24d80 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 ] D when another
24d90 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 thread.** or pr
24da0 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 ocess has the ta
24db0 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 ble locked..** T
24dc0 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f he sqlite3_busy_
24dd0 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 handler() interf
24de0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 ace is used to i
24df0 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c mplement.** [sql
24e00 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 ite3_busy_timeou
24e10 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 t()] and [PRAGMA
24e20 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a busy_timeout]..
24e30 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 **.** ^If the bu
24e40 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e sy callback is N
24e50 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 ULL, then [SQLIT
24e60 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 E_BUSY].** is re
24e70 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 turned immediate
24e80 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 ly upon encounte
24e90 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 ring the lock.
24ea0 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c ^If the busy cal
24eb0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 lback.** is not
24ec0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 NULL, then the c
24ed0 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 allback might be
24ee0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 invoked with tw
24ef0 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a o arguments..**.
24f00 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 ** ^The first ar
24f10 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 gument to the bu
24f20 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 sy handler is a
24f30 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 copy of the void
24f40 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a * pointer which.
24f50 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 ** is the third
24f60 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
24f70 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 te3_busy_handler
24f80 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 (). ^The second
24f90 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 argument to.**
24fa0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 the busy handler
24fb0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 callback is the
24fc0 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 number of times
24fd0 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 that the busy h
24fe0 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 andler has.** be
24ff0 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 en invoked previ
25000 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 ously for the sa
25010 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 me locking event
25020 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 . ^If the.** bu
25030 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 sy callback retu
25040 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 rns 0, then no a
25050 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 dditional attemp
25060 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a ts are made to.*
25070 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 * access the dat
25080 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 abase and [SQLIT
25090 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 E_BUSY] is retur
250a0 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 ned.** to the ap
250b0 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 plication..** ^I
250c0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 f the callback r
250d0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
250e0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 then another at
250f0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 tempt.** is made
25100 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 to access the d
25110 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 atabase and the
25120 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a cycle repeats..*
25130 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 *.** The presenc
25140 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 e of a busy hand
25150 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 ler does not gua
25160 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 rantee that it w
25170 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a ill be invoked.*
25180 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 * when there is
25190 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e lock contention.
251a0 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 ^If SQLite dete
251b0 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f rmines that invo
251c0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a king the busy.**
251d0 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 handler could r
251e0 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c esult in a deadl
251f0 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 ock, it will go
25200 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e ahead and return
25210 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a [SQLITE_BUSY].*
25220 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 * to the applica
25230 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 tion instead of
25240 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a invoking the .**
25250 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a busy handler..*
25260 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 * Consider a sce
25270 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 nario where one
25280 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 process is holdi
25290 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 ng a read lock t
252a0 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 hat.** it is try
252b0 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 ing to promote t
252c0 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 o a reserved loc
252d0 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e k and.** a secon
252e0 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c d process is hol
252f0 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 ding a reserved
25300 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 lock that it is
25310 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f trying.** to pro
25320 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 mote to an exclu
25330 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 sive lock. The
25340 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 first process ca
25350 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 nnot proceed.**
25360 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c because it is bl
25370 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 ocked by the sec
25380 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f ond and the seco
25390 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f nd process canno
253a0 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 t.** proceed bec
253b0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b ause it is block
253c0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e ed by the first.
253d0 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 If both proces
253e0 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 ses.** invoke th
253f0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c e busy handlers,
25400 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 neither will ma
25410 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e ke any progress.
25420 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 Therefore,.**
25430 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b SQLite returns [
25440 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 SQLITE_BUSY] for
25450 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 the first proce
25460 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 ss, hoping that
25470 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 this.** will ind
25480 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 uce the first pr
25490 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 ocess to release
254a0 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 its read lock a
254b0 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 nd allow.** the
254c0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 second process t
254d0 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a o proceed..**.**
254e0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 ^The default bu
254f0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e sy callback is N
25500 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 ULL..**.** ^(The
25510 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 re can only be a
25520 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e single busy han
25530 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 dler defined for
25540 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 each.** [databa
25550 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
25560 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 Setting a new b
25570 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 usy handler clea
25580 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f rs any.** previo
25590 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 usly set handler
255a0 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 .)^ ^Note that
255b0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 calling [sqlite3
255c0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d _busy_timeout()]
255d0 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e .** or evaluatin
255e0 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 g [PRAGMA busy_t
255f0 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 imeout=N] will c
25600 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 hange the.** bus
25610 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 y handler and th
25620 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 us clear any pre
25630 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 viously set busy
25640 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 handler..**.**
25650 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 The busy callbac
25660 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b k should not tak
25670 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 e any actions wh
25680 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a ich modify the.*
25690 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
256a0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b ction that invok
256b0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ed the busy hand
256c0 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 ler. In other w
256d0 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 ords,.** the bus
256e0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 y handler is not
256f0 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 reentrant. Any
25700 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a such actions.**
25710 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 result in undef
25720 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a ined behavior..*
25730 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e * .** A busy han
25740 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c dler must not cl
25750 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ose the database
25760 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f connection.** o
25770 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 r [prepared stat
25780 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f ement] that invo
25790 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e ked the busy han
257a0 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f dler..*/.SQLITE_
257b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
257c0 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c busy_handler(sql
257d0 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 ite3*,int(*)(voi
257e0 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a d*,int),void*);.
257f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
25800 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 Set A Busy Time
25810 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 out.** METHOD: s
25820 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 qlite3.**.** ^Th
25830 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 is routine sets
25840 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f a [sqlite3_busy_
25850 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 handler | busy h
25860 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 andler] that sle
25870 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 eps.** for a spe
25880 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 cified amount of
25890 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 time when a tab
258a0 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e le is locked. ^
258b0 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 The handler.** w
258c0 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 ill sleep multip
258d0 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 le times until a
258e0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c t least "ms" mil
258f0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 liseconds of sle
25900 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 eping.** have ac
25910 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 cumulated. ^Aft
25920 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 er at least "ms"
25930 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 milliseconds of
25940 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 sleeping,.** th
25950 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e e handler return
25960 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 s 0 which causes
25970 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
25980 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b ] to return.** [
25990 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a SQLITE_BUSY]..**
259a0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 .** ^Calling thi
259b0 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 s routine with a
259c0 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 n argument less
259d0 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f than or equal to
259e0 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f zero.** turns o
259f0 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 ff all busy hand
25a00 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 lers..**.** ^(Th
25a10 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 ere can only be
25a20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 a single busy ha
25a30 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 ndler for a part
25a40 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 icular.** [datab
25a50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
25a60 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d at any given mom
25a70 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 ent. If another
25a80 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a busy handler.**
25a90 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 was defined (u
25aa0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 sing [sqlite3_bu
25ab0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 sy_handler()]) p
25ac0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a rior to calling.
25ad0 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c ** this routine,
25ae0 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 that other busy
25af0 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 handler is clea
25b00 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 red.)^.**.** See
25b10 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 also: [PRAGMA
25b20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f busy_timeout].*/
25b30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
25b40 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
25b50 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 eout(sqlite3*, i
25b60 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 nt ms);../*.** C
25b70 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 API3REF: Conveni
25b80 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f ence Routines Fo
25b90 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 r Running Querie
25ba0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
25bb0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 ite3.**.** This
25bc0 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 is a legacy inte
25bd0 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 rface that is pr
25be0 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b eserved for back
25bf0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c wards compatibil
25c00 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 ity..** Use of t
25c10 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 his interface is
25c20 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 not recommended
25c30 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 ..**.** Definiti
25c40 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 on: A <b>result
25c50 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d table</b> is mem
25c60 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 ory data structu
25c70 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 re created by th
25c80 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 e.** [sqlite3_ge
25c90 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 t_table()] inter
25ca0 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 face. A result
25cb0 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 table records th
25cc0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 e.** complete qu
25cd0 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d ery results from
25ce0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 one or more que
25cf0 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ries..**.** The
25d00 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c table conceptual
25d10 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 ly has a number
25d20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 of rows and colu
25d30 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 mns. But.** the
25d40 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e se numbers are n
25d50 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 ot part of the r
25d60 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 esult table itse
25d70 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 lf. These.** nu
25d80 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e mbers are obtain
25d90 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 ed separately.
25da0 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d Let N be the num
25db0 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 ber of rows.** a
25dc0 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 nd M be the numb
25dd0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a er of columns..*
25de0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 *.** A result ta
25df0 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 ble is an array
25e00 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a of pointers to z
25e10 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 ero-terminated U
25e20 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a TF-8 strings..**
25e30 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 There are (N+1)
25e40 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 *M elements in t
25e50 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 he array. The f
25e60 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 irst M pointers
25e70 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f point.** to zero
25e80 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 -terminated stri
25e90 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 ngs that contai
25ea0 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 n the names of t
25eb0 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 he columns..** T
25ec0 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 he remaining ent
25ed0 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 ries all point t
25ee0 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e o query results.
25ef0 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 NULL values re
25f00 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 sult.** in NULL
25f10 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f pointers. All o
25f20 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 ther values are
25f30 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a in their UTF-8 z
25f40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a ero-terminated.*
25f50 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 * string represe
25f60 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 ntation as retur
25f70 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f ned by [sqlite3_
25f80 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a column_text()]..
25f90 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 **.** A result t
25fa0 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 able might consi
25fb0 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 st of one or mor
25fc0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 e memory allocat
25fd0 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e ions..** It is n
25fe0 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 ot safe to pass
25ff0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 a result table d
26000 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 irectly to [sqli
26010 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 te3_free()]..**
26020 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 A result table s
26030 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 hould be dealloc
26040 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 ated using [sqli
26050 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 te3_free_table()
26060 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e ]..**.** ^(As an
26070 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 example of the
26080 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 result table for
26090 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 mat, suppose a q
260a0 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 uery result.** i
260b0 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a s as follows:.**
260c0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e .** <blockquote>
260d0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 <pre>.**
260e0 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 Name | Ag
260f0 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d e.** ----
26100 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
26110 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c ---.** Al
26120 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a ice | 43.*
26130 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 * Bob
26140 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 | 28.**
26150 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 Cindy
26160 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f | 21.** </pre></
26170 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a blockquote>.**.*
26180 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 * There are two
26190 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e column (M==2) an
261a0 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d d three rows (N=
261b0 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a =3). Thus the.*
261c0 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 * result table h
261d0 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 as 8 entries. S
261e0 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c uppose the resul
261f0 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 t table is store
26200 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 d.** in an array
26210 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e names azResult.
26220 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 Then azResult
26230 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 holds this conte
26240 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b nt:.**.** <block
26250 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
26260 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 azResult&#
26270 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 91;0] = "Name";.
26280 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
26290 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 lt[1] = "Age
262a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
262b0 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 esult[2] = "
262c0 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 Alice";.**
262d0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 azResult[3
262e0 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 ] = "43";.**
262f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 azResult[
26300 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 ;4] = "Bob";.**
26310 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
26320 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a #91;5] = "28";.*
26330 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
26340 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 t[6] = "Cind
26350 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a y";.** az
26360 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 Result[7] =
26370 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c "21";.** </pre><
26380 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a /blockquote>)^.*
26390 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
263a0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 3_get_table() fu
263b0 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 nction evaluates
263c0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 one or more.**
263d0 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 semicolon-separa
263e0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e ted SQL statemen
263f0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 ts in the zero-t
26400 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a erminated UTF-8.
26410 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 ** string of its
26420 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 2nd parameter a
26430 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 nd returns a res
26440 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 ult table to the
26450 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 .** pointer give
26460 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 n in its 3rd par
26470 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 ameter..**.** Af
26480 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 ter the applicat
26490 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 ion has finished
264a0 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 with the result
264b0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 from sqlite3_ge
264c0 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 t_table(),.** it
264d0 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 must pass the r
264e0 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e esult table poin
264f0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 ter to sqlite3_f
26500 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f ree_table() in o
26510 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 rder to.** relea
26520 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 se the memory th
26530 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e at was malloced.
26540 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 Because of the
26550 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c way the.** [sql
26560 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 ite3_malloc()] h
26570 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 appens within sq
26580 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 lite3_get_table(
26590 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a ), the calling.*
265a0 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 * function must
265b0 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 not try to call
265c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d [sqlite3_free()]
265d0 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 directly. Only
265e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 .** [sqlite3_fre
265f0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 e_table()] is ab
26600 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 le to release th
26610 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c e memory properl
26620 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a y and safely..**
26630 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f .** The sqlite3_
26640 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 get_table() inte
26650 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 rface is impleme
26660 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 nted as a wrappe
26670 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c r around.** [sql
26680 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 ite3_exec()]. T
26690 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 he sqlite3_get_t
266a0 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 able() routine d
266b0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 oes not have acc
266c0 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e ess.** to any in
266d0 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 ternal data stru
266e0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 ctures of SQLite
266f0 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 . It uses only
26700 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e the public.** in
26710 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 terface defined
26720 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 here. As a cons
26730 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 equence, errors
26740 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 that occur in th
26750 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 e.** wrapper lay
26760 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 er outside of th
26770 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 e internal [sqli
26780 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c te3_exec()] call
26790 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c are not.** refl
267a0 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 ected in subsequ
267b0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 ent calls to [sq
267c0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d lite3_errcode()]
267d0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f or.** [sqlite3_
267e0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 errmsg()]..*/.SQ
267f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
26800 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a ite3_get_table(.
26810 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 sqlite3 *db,
26820 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 /* An op
26830 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 en database */.
26840 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 const char *zSq
26850 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f l, /* SQL to
26860 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f be evaluated */
26870 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 . char ***pazRe
26880 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 sult, /* Resu
26890 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 lts of the query
268a0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 */. int *pnRow
268b0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e , /* N
268c0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 umber of result
268d0 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 rows written her
268e0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f e */. int *pnCo
268f0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 lumn, /*
26900 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 Number of result
26910 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e columns written
26920 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 here */. char
26930 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 **pzErrmsg
26940 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 /* Error msg wr
26950 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b itten here */.);
26960 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 .SQLITE_API void
26970 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 sqlite3_free_ta
26980 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c ble(char **resul
26990 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 t);../*.** CAPI3
269a0 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 REF: Formatted S
269b0 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 tring Printing F
269c0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 unctions.**.** T
269d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 hese routines ar
269e0 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 e work-alikes of
269f0 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 the "printf()"
26a00 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 family of functi
26a10 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 ons.** from the
26a20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 standard C libra
26a30 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 ry..** These rou
26a40 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 tines understand
26a50 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d most of the com
26a60 6d 6f 6e 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f mon formatting o
26a70 70 74 69 6f 6e 73 20 66 72 6f 6d 0a 2a 2a 20 74 ptions from.** t
26a80 68 65 20 73 74 61 6e 64 61 72 64 20 6c 69 62 72 he standard libr
26a90 61 72 79 20 70 72 69 6e 74 66 28 29 20 0a 2a 2a ary printf() .**
26aa0 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 plus some addit
26ab0 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 ional non-standa
26ac0 72 64 20 66 6f 72 6d 61 74 73 20 28 5b 25 71 5d rd formats ([%q]
26ad0 2c 20 5b 25 51 5d 2c 20 5b 25 77 5d 2c 20 61 6e , [%Q], [%w], an
26ae0 64 20 5b 25 7a 5d 29 2e 0a 2a 2a 20 53 65 65 20 d [%z])..** See
26af0 74 68 65 20 5b 62 75 69 6c 74 2d 69 6e 20 70 72 the [built-in pr
26b00 69 6e 74 66 28 29 5d 20 64 6f 63 75 6d 65 6e 74 intf()] document
26b10 61 74 69 6f 6e 20 66 6f 72 20 64 65 74 61 69 6c ation for detail
26b20 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 s..**.** ^The sq
26b30 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 lite3_mprintf()
26b40 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 and sqlite3_vmpr
26b50 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 intf() routines
26b60 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 write their.** r
26b70 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f esults into memo
26b80 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d ry obtained from
26b90 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 [sqlite3_malloc
26ba0 36 34 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 64()]..** The st
26bb0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 rings returned b
26bc0 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74 y these two rout
26bd0 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a ines should be.*
26be0 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73 * released by [s
26bf0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 qlite3_free()].
26c00 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 ^Both routines
26c10 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c return a.** NULL
26c20 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c pointer if [sql
26c30 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 5d ite3_malloc64()]
26c40 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c is unable to al
26c50 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a locate enough.**
26c60 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 memory to hold
26c70 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 the resulting st
26c80 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 ring..**.** ^(Th
26c90 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e e sqlite3_snprin
26ca0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 tf() routine is
26cb0 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 similar to "snpr
26cc0 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 intf()" from.**
26cd0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c the standard C l
26ce0 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 ibrary. The res
26cf0 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 ult is written i
26d00 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 nto the.** buffe
26d10 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 r supplied as th
26d20 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
26d30 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 er whose size is
26d40 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 given by.** the
26d50 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 first parameter
26d60 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 . Note that the
26d70 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 order of the.**
26d80 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 first two parame
26d90 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 ters is reversed
26da0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 from snprintf()
26db0 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a .)^ This is an.
26dc0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 ** historical ac
26dd0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e cident that cann
26de0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 ot be fixed with
26df0 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 out breaking.**
26e00 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 backwards compat
26e10 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 ibility. ^(Note
26e20 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 also that sqlit
26e30 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
26e40 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
26e50 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 er to its buffer
26e60 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 instead of the
26e70 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 number of.** cha
26e80 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 racters actually
26e90 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 written into th
26ea0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 e buffer.)^ We
26eb0 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 admit that.** th
26ec0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 e number of char
26ed0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 acters written w
26ee0 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 ould be a more u
26ef0 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 seful return.**
26f00 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e value but we can
26f10 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 not change the i
26f20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
26f30 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
26f40 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f f().** now witho
26f50 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 ut breaking comp
26f60 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a atibility..**.**
26f70 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 ^As long as the
26f80 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 buffer size is
26f90 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 greater than zer
26fa0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 o, sqlite3_snpri
26fb0 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 ntf().** guarant
26fc0 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 ees that the buf
26fd0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 fer is always ze
26fe0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 ro-terminated.
26ff0 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 ^The first.** pa
27000 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 rameter "n" is t
27010 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 he total size of
27020 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 the buffer, inc
27030 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 luding space for
27040 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 .** the zero ter
27050 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 minator. So the
27060 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 longest string
27070 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 that can be comp
27080 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 letely.** writte
27090 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 n will be n-1 ch
270a0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 aracters..**.**
270b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e ^The sqlite3_vsn
270c0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 printf() routine
270d0 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 is a varargs ve
270e0 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 rsion of sqlite3
270f0 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a _snprintf()..**.
27100 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 62 ** See also: [b
27110 75 69 6c 74 2d 69 6e 20 70 72 69 6e 74 66 28 29 uilt-in printf()
27120 5d 2c 20 5b 70 72 69 6e 74 66 28 29 20 53 51 4c ], [printf() SQL
27130 20 66 75 6e 63 74 69 6f 6e 5d 0a 2a 2f 0a 53 51 function].*/.SQ
27140 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 LITE_API char *s
27150 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 qlite3_mprintf(c
27160 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b onst char*,...);
27170 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 .SQLITE_API char
27180 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e *sqlite3_vmprin
27190 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 tf(const char*,
271a0 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 va_list);.SQLITE
271b0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 _API char *sqlit
271c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c e3_snprintf(int,
271d0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
271e0 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f *, ...);.SQLITE_
271f0 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 API char *sqlite
27200 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 3_vsnprintf(int,
27210 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
27220 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a *, va_list);../*
27230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
27240 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 mory Allocation
27250 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 Subsystem.**.**
27260 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 The SQLite core
27270 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 uses these three
27280 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c routines for al
27290 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 l of its own.**
272a0 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 internal memory
272b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 allocation needs
272c0 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 . "Core" in the
272d0 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 previous sentenc
272e0 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e e.** does not in
272f0 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d clude operating-
27300 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 system specific
27310 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 VFS implementati
27320 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 on. The.** Wind
27330 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 ows VFS uses nat
27340 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 ive malloc() and
27350 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 free() for some
27360 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a operations..**.
27370 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
27380 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 malloc() routine
27390 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 returns a point
273a0 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a er to a block.**
273b0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 of memory at le
273c0 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c ast N bytes in l
273d0 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 ength, where N i
273e0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e s the parameter.
273f0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f .** ^If sqlite3_
27400 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 malloc() is unab
27410 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 le to obtain suf
27420 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 ficient free.**
27430 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 memory, it retur
27440 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 ns a NULL pointe
27450 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 r. ^If the para
27460 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 meter N to.** sq
27470 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 lite3_malloc() i
27480 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 s zero or negati
27490 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f ve then sqlite3_
274a0 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 malloc() returns
274b0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 .** a NULL point
274c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 er..**.** ^The s
274d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 qlite3_malloc64(
274e0 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 N) routine works
274f0 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 just like.** sq
27500 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 lite3_malloc(N)
27510 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 except that N is
27520 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34 2d an unsigned 64-
27530 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73 74 bit integer inst
27540 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e ead.** of a sign
27550 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65 ed 32-bit intege
27560 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e r..**.** ^Callin
27570 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 g sqlite3_free()
27580 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 with a pointer
27590 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 previously retur
275a0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 ned.** by sqlite
275b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 3_malloc() or sq
275c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 lite3_realloc()
275d0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 releases that me
275e0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 mory so.** that
275f0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 it might be reus
27600 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 ed. ^The sqlite
27610 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 3_free() routine
27620 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 is.** a no-op i
27630 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 f is called with
27640 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
27650 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c Passing a NULL
27660 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 pointer.** to s
27670 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 qlite3_free() is
27680 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 harmless. Afte
27690 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d r being freed, m
276a0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 emory.** should
276b0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 neither be read
276c0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 nor written. Ev
276d0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 en reading previ
276e0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d ously freed.** m
276f0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 emory might resu
27700 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 lt in a segmenta
27710 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 tion fault or ot
27720 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
27730 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 ..** Memory corr
27740 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e uption, a segmen
27750 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 tation fault, or
27760 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 other severe er
27770 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 ror.** might res
27780 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 ult if sqlite3_f
27790 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 ree() is called
277a0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 with a non-NULL
277b0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 pointer that.**
277c0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 was not obtained
277d0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 from sqlite3_ma
277e0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 lloc() or sqlite
277f0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 3_realloc()..**.
27800 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
27810 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 realloc(X,N) int
27820 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 erface attempts
27830 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 to resize a.** p
27840 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f rior memory allo
27850 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 cation X to be a
27860 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2e t least N bytes.
27870 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70 61 .** ^If the X pa
27880 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 rameter to sqlit
27890 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a e3_realloc(X,N).
278a0 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 ** is a NULL poi
278b0 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 nter then its be
278c0 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 havior is identi
278d0 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a cal to calling.*
278e0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 * sqlite3_malloc
278f0 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 (N)..** ^If the
27900 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 N parameter to s
27910 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
27920 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a ,N) is zero or.*
27930 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 * negative then
27940 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 the behavior is
27950 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 exactly the same
27960 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 as calling.** s
27970 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e 0a qlite3_free(X)..
27980 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c ** ^sqlite3_real
27990 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 loc(X,N) returns
279a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
279b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
279c0 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 n.** of at least
279d0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 N bytes in size
279e0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 or NULL if insu
279f0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 fficient memory
27a00 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a is available..**
27a10 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 ^If M is the si
27a20 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 ze of the prior
27a30 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e allocation, then
27a40 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a min(N,M) bytes.
27a50 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 ** of the prior
27a60 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 allocation are c
27a70 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 opied into the b
27a80 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 eginning of buff
27a90 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 er returned.** b
27aa0 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f y sqlite3_reallo
27ab0 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 c(X,N) and the p
27ac0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
27ad0 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 is freed..** ^If
27ae0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 sqlite3_realloc
27af0 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 (X,N) returns NU
27b00 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 LL and N is posi
27b10 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a tive, then the.*
27b20 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 * prior allocati
27b30 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e on is not freed.
27b40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
27b50 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c te3_realloc64(X,
27b60 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f N) interfaces wo
27b70 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73 0a rks the same as.
27b80 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c ** sqlite3_reall
27b90 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20 74 oc(X,N) except t
27ba0 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62 69 hat N is a 64-bi
27bb0 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 t unsigned integ
27bc0 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 er instead.** of
27bd0 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 a 32-bit signed
27be0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 integer..**.**
27bf0 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 ^If X is a memor
27c00 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 y allocation pre
27c10 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 viously obtained
27c20 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 from sqlite3_ma
27c30 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 lloc(),.** sqlit
27c40 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 e3_malloc64(), s
27c50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
27c60 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 , or sqlite3_rea
27c70 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a lloc64(), then.*
27c80 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 * sqlite3_msize(
27c90 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 X) returns the s
27ca0 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f ize of that memo
27cb0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e ry allocation in
27cc0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 bytes..** ^The
27cd0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 value returned b
27ce0 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 y sqlite3_msize(
27cf0 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72 67 X) might be larg
27d00 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 er than the numb
27d10 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 er.** of bytes r
27d20 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58 20 equested when X
27d30 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 was allocated.
27d40 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 ^If X is a NULL
27d50 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 pointer then.**
27d60 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 sqlite3_msize(X)
27d70 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 returns zero.
27d80 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 If X points to s
27d90 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69 73 omething that is
27da0 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 not.** the begi
27db0 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 nning of memory
27dc0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 allocation, or i
27dd0 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 f it points to a
27de0 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c formerly.** val
27df0 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 id memory alloca
27e00 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e 6f tion that has no
27e10 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74 68 w been freed, th
27e20 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a en the behavior.
27e30 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 ** of sqlite3_ms
27e40 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66 69 ize(X) is undefi
27e50 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 ned and possibly
27e60 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 harmful..**.**
27e70 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 ^The memory retu
27e80 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
27e90 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 malloc(), sqlite
27ea0 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 3_realloc(),.**
27eb0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 sqlite3_malloc64
27ec0 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f (), and sqlite3_
27ed0 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 realloc64().** i
27ee0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 s always aligned
27ef0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 to at least an
27f00 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 8 byte boundary,
27f10 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 or to a.** 4 by
27f20 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 te boundary if t
27f30 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 he [SQLITE_4_BYT
27f40 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 E_ALIGNED_MALLOC
27f50 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a ] compile-time.*
27f60 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 * option is used
27f70 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 ..**.** In SQLit
27f80 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 e version 3.5.0
27f90 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 and 3.5.1, it wa
27fa0 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 s possible to de
27fb0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 fine.** the SQLI
27fc0 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 TE_OMIT_MEMORY_A
27fd0 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 LLOCATION which
27fe0 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 would cause the
27ff0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c built-in.** impl
28000 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 ementation of th
28010 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 ese routines to
28020 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 be omitted. Tha
28030 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 t capability.**
28040 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f is no longer pro
28050 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 vided. Only bui
28060 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c lt-in memory all
28070 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 ocators can be u
28080 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 sed..**.** Prior
28090 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 to SQLite versi
280a0 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 on 3.7.10, the W
280b0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 indows OS interf
280c0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 ace layer called
280d0 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d .** the system m
280e0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 alloc() and free
280f0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e () directly when
28100 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 converting.** f
28110 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e ilenames between
28120 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 the UTF-8 encod
28130 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 ing used by SQLi
28140 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 te.** and whatev
28150 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f er filename enco
28160 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 ding is used by
28170 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 the particular W
28180 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c indows.** instal
28190 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 lation. Memory
281a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 allocation error
281b0 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c s were detected,
281c0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 but.** they wer
281d0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 e reported back
281e0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f as [SQLITE_CANTO
281f0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 PEN] or.** [SQLI
28200 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 TE_IOERR] rather
28210 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f than [SQLITE_NO
28220 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 MEM]..**.** The
28230 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 pointer argument
28240 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 s to [sqlite3_fr
28250 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 ee()] and [sqlit
28260 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a e3_realloc()].**
28270 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 must be either
28280 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 NULL or else poi
28290 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 nters obtained f
282a0 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 rom a prior.** i
282b0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 nvocation of [sq
282c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 lite3_malloc()]
282d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c or [sqlite3_real
282e0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 loc()] that have
282f0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e .** not yet been
28300 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a released..**.**
28310 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
28320 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f must not read o
28330 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 r write any part
28340 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f of.** a block o
28350 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 f memory after i
28360 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 t has been relea
28370 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 sed using.** [sq
28380 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 lite3_free()] or
28390 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f [sqlite3_reallo
283a0 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f c()]..*/.SQLITE_
283b0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 API void *sqlite
283c0 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 3_malloc(int);.S
283d0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
283e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 sqlite3_malloc64
283f0 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 (sqlite3_uint64)
28400 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 ;.SQLITE_API voi
28410 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c d *sqlite3_reall
28420 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a oc(void*, int);.
28430 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
28440 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 *sqlite3_realloc
28450 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 64(void*, sqlite
28460 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 3_uint64);.SQLIT
28470 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 E_API void sqlit
28480 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a e3_free(void*);.
28490 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
284a0 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 e3_uint64 sqlite
284b0 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 3_msize(void*);.
284c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
284d0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f Memory Allocato
284e0 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a r Statistics.**.
284f0 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 ** SQLite provid
28500 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 es these two int
28510 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f erfaces for repo
28520 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 rting on the sta
28530 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 tus.** of the [s
28540 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
28550 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 , [sqlite3_free(
28560 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 )], and [sqlite3
28570 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 _realloc()].** r
28580 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 outines, which f
28590 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e orm the built-in
285a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
285b0 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a on subsystem..**
285c0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 .** ^The [sqlite
285d0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 3_memory_used()]
285e0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 routine returns
285f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 the number of b
28600 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 ytes.** of memor
28610 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 y currently outs
28620 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 tanding (malloce
28630 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 d but not freed)
28640 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 ..** ^The [sqlit
28650 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
28660 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 ter()] routine r
28670 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d eturns the maxim
28680 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b um.** value of [
28690 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 sqlite3_memory_u
286a0 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 sed()] since the
286b0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b high-water mark
286c0 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 .** was last res
286d0 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 et. ^The values
286e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 returned by [sq
286f0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 lite3_memory_use
28700 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c d()] and.** [sql
28710 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
28720 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 water()] include
28730 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a any overhead.**
28740 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 added by SQLite
28750 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e in its implemen
28760 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 tation of [sqlit
28770 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a e3_malloc()],.**
28780 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 but not overhea
28790 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 d added by the a
287a0 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 ny underlying sy
287b0 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 stem library.**
287c0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 routines that [s
287d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
287e0 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a may call..**.**
287f0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 ^The memory hig
28800 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 h-water mark is
28810 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 reset to the cur
28820 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a rent value of.**
28830 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 [sqlite3_memory
28840 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 _used()] if and
28850 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 only if the para
28860 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c meter to.** [sql
28870 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 ite3_memory_high
28880 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 water()] is true
28890 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 . ^The value re
288a0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 turned.** by [sq
288b0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 lite3_memory_hig
288c0 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 hwater(1)] is th
288d0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 e high-water mar
288e0 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 k.** prior to th
288f0 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 e reset..*/.SQLI
28900 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 TE_API sqlite3_i
28910 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d nt64 sqlite3_mem
28920 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a ory_used(void);.
28930 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 SQLITE_API sqlit
28940 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 e3_int64 sqlite3
28950 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 _memory_highwate
28960 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 r(int resetFlag)
28970 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
28980 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d F: Pseudo-Random
28990 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f Number Generato
289a0 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 r.**.** SQLite c
289b0 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 ontains a high-q
289c0 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 uality pseudo-ra
289d0 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 ndom number gene
289e0 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 rator (PRNG) use
289f0 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 d to.** select r
28a00 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 andom [ROWID | R
28a10 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 OWIDs] when inse
28a20 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 rting new record
28a30 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 s into a table t
28a40 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 hat.** already u
28a50 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 ses the largest
28a60 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d possible [ROWID]
28a70 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 . The PRNG is a
28a80 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 lso used for.**
28a90 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e the build-in ran
28aa0 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d dom() and random
28ab0 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 blob() SQL funct
28ac0 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 ions. This inte
28ad0 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 rface allows.**
28ae0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 applications to
28af0 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 access the same
28b00 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 PRNG for other p
28b10 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e urposes..**.** ^
28b20 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 A call to this r
28b30 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 outine stores N
28b40 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e bytes of randomn
28b50 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 ess into buffer
28b60 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 P..** ^The P par
28b70 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 20 ameter can be a
28b80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a NULL pointer..**
28b90 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75 .** ^If this rou
28ba0 74 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65 tine has not bee
28bb0 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c n previously cal
28bc0 6c 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72 led or if the pr
28bd0 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 evious.** call h
28be0 61 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f ad N less than o
28bf0 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 ne or a NULL poi
28c00 6e 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e nter for P, then
28c10 20 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 the PRNG is.**
28c20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e seeded using ran
28c30 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 domness obtained
28c40 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f from the xRando
28c50 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a mness method of.
28c60 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b ** the default [
28c70 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
28c80 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ect..** ^If the
28c90 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f previous call to
28ca0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 this routine ha
28cb0 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d d an N of 1 or m
28cc0 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e ore and a.** non
28cd0 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 -NULL P then the
28ce0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 pseudo-randomne
28cf0 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a ss is generated.
28d00 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e ** internally an
28d10 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 d without recour
28d20 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 se to the [sqlit
28d30 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e e3_vfs] xRandomn
28d40 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a ess.** method..*
28d50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 /.SQLITE_API voi
28d60 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d d sqlite3_random
28d70 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 ness(int N, void
28d80 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 *P);../*.** CAP
28d90 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 I3REF: Compile-T
28da0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f ime Authorizatio
28db0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d n Callbacks.** M
28dc0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
28dd0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 * KEYWORDS: {aut
28de0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
28df0 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f }.**.** ^This ro
28e00 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 utine registers
28e10 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 an authorizer ca
28e20 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 llback with a pa
28e30 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 rticular.** [dat
28e40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
28e50 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 ], supplied in t
28e60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
28e70 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f t..** ^The autho
28e80 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
28e90 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c s invoked as SQL
28ea0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 statements are
28eb0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a being compiled.*
28ec0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 * by [sqlite3_pr
28ed0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 epare()] or its
28ee0 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 variants [sqlite
28ef0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
28f00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
28f10 70 61 72 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c pare_v3()], [sql
28f20 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 ite3_prepare16()
28f30 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ], [sqlite3_prep
28f40 61 72 65 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 are16_v2()],.**
28f50 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 and [sqlite3_pre
28f60 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e pare16_v3()]. ^
28f70 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f At various.** po
28f80 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 ints during the
28f90 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 compilation proc
28fa0 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 ess, as logic is
28fb0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a being created.*
28fc0 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 * to perform var
28fd0 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 ious actions, th
28fe0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
28ff0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
29000 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 to.** see if th
29010 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 ose actions are
29020 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 allowed. ^The a
29030 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
29040 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 ck should.** ret
29050 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
29060 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 to allow the act
29070 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e ion, [SQLITE_IGN
29080 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 ORE] to disallow
29090 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 the.** specific
290a0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f action but allo
290b0 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d w the SQL statem
290c0 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 ent to continue
290d0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 to be.** compile
290e0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 d, or [SQLITE_DE
290f0 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 NY] to cause the
29100 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 entire SQL stat
29110 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 ement to be.** r
29120 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 ejected with an
29130 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 error. ^If the
29140 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
29150 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 ack returns.** a
29160 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 ny value other t
29170 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f han [SQLITE_IGNO
29180 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d RE], [SQLITE_OK]
29190 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e , or [SQLITE_DEN
291a0 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b Y].** then the [
291b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
291c0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c v2()] or equival
291d0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 ent call that tr
291e0 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 iggered.** the a
291f0 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 uthorizer will f
29200 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f ail with an erro
29210 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a r message..**.**
29220 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 When the callba
29230 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ck returns [SQLI
29240 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 TE_OK], that mea
29250 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e ns the operation
29260 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 .** requested is
29270 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 ok. ^When the
29280 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 callback returns
29290 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 [SQLITE_DENY],
292a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f the.** [sqlite3_
292b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 prepare_v2()] or
292c0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c equivalent call
292d0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 that triggered
292e0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 the.** authorize
292f0 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 r will fail with
29300 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 an error messag
29310 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 e explaining tha
29320 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 t.** access is d
29330 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 enied. .**.** ^T
29340 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 he first paramet
29350 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 er to the author
29360 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
29370 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 a copy of the t
29380 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 hird.** paramete
29390 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 r to the sqlite3
293a0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
293b0 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 ) interface. ^Th
293c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
293d0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c er.** to the cal
293e0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 lback is an inte
293f0 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 ger [SQLITE_COPY
29400 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 | action code]
29410 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a that specifies.*
29420 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 * the particular
29430 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 action to be au
29440 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 thorized. ^The t
29450 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 hird through six
29460 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a th parameters.**
29470 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b to the callback
29480 20 61 72 65 20 65 69 74 68 65 72 20 4e 55 4c 4c are either NULL
29490 20 70 6f 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 pointers or zer
294a0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 o-terminated str
294b0 69 6e 67 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e ings.** that con
294c0 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 tain additional
294d0 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 details about th
294e0 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 e action to be a
294f0 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 uthorized..** Ap
29500 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 plications must
29510 61 6c 77 61 79 73 20 62 65 20 70 72 65 70 61 72 always be prepar
29520 65 64 20 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 ed to encounter
29530 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 a NULL pointer i
29540 6e 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 n any.** of the
29550 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 74 68 third through th
29560 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 e sixth paramete
29570 72 73 20 6f 66 20 74 68 65 20 61 75 74 68 6f 72 rs of the author
29580 69 7a 61 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b ization callback
29590 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
295a0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b action code is [
295b0 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 SQLITE_READ].**
295c0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
295d0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 returns [SQLITE
295e0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 _IGNORE] then th
295f0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 e.** [prepared s
29600 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d tatement] statem
29610 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 ent is construct
29620 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 ed to substitute
29630 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 .** a NULL value
29640 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 in place of the
29650 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 table column th
29660 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a at would have.**
29670 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 been read if [S
29680 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 QLITE_OK] had be
29690 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 en returned. Th
296a0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 e [SQLITE_IGNORE
296b0 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 ].** return can
296c0 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 be used to deny
296d0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 an untrusted use
296e0 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 r access to indi
296f0 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e vidual.** column
29700 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a s of a table..**
29710 20 5e 57 68 65 6e 20 61 20 74 61 62 6c 65 20 69 ^When a table i
29720 73 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 s referenced by
29730 61 20 5b 53 45 4c 45 43 54 5d 20 62 75 74 20 6e a [SELECT] but n
29740 6f 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 o column values
29750 61 72 65 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 are.** extracted
29760 20 66 72 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 from that table
29770 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e (for example in
29780 20 61 20 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a a query like.**
29790 20 22 53 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a "SELECT count(*
297a0 29 20 46 52 4f 4d 20 74 61 62 22 29 20 74 68 65 ) FROM tab") the
297b0 6e 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 n the [SQLITE_RE
297c0 41 44 5d 20 61 75 74 68 6f 72 69 7a 65 72 20 63 AD] authorizer c
297d0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e allback.** is in
297e0 76 6f 6b 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 voked once for t
297f0 68 61 74 20 74 61 62 6c 65 20 77 69 74 68 20 61 hat table with a
29800 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 column name tha
29810 74 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74 t is an empty st
29820 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 ring..** ^If the
29830 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 action code is
29840 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 [SQLITE_DELETE]
29850 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b and the callback
29860 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c returns.** [SQL
29870 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e ITE_IGNORE] then
29880 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 the [DELETE] op
29890 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 eration proceeds
298a0 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 but the.** [tru
298b0 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 ncate optimizati
298c0 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 on] is disabled
298d0 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 and all rows are
298e0 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 deleted individ
298f0 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 ually..**.** An
29900 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 authorizer is us
29910 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 ed when [sqlite3
29920 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 _prepare | prepa
29930 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 ring].** SQL sta
29940 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 tements from an
29950 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 untrusted source
29960 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 , to ensure that
29970 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
29980 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 nts.** do not tr
29990 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 y to access data
299a0 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c they are not al
299b0 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 lowed to see, or
299c0 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f that they do no
299d0 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 t.** try to exec
299e0 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 ute malicious st
299f0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 atements that da
29a00 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73 mage the databas
29a10 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 e. For.** examp
29a20 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 le, an applicati
29a30 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 on may allow a u
29a40 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 ser to enter arb
29a50 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 itrary.** SQL qu
29a60 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 eries for evalua
29a70 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 tion by a databa
29a80 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 se. But the app
29a90 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a lication does.**
29aa0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 not want the us
29ab0 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f er to be able to
29ac0 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 make arbitrary
29ad0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a changes to the.*
29ae0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 * database. An
29af0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 authorizer could
29b00 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 then be put in
29b10 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a place while the.
29b20 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 ** user-entered
29b30 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 SQL is being [sq
29b40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 lite3_prepare |
29b50 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a prepared] that.*
29b60 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 * disallows ever
29b70 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 ything except [S
29b80 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 ELECT] statement
29b90 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 s..**.** Applica
29ba0 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 tions that need
29bb0 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 to process SQL f
29bc0 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f rom untrusted so
29bd0 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 urces.** might a
29be0 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 lso consider low
29bf0 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c ering resource l
29c00 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c imits using [sql
29c10 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a ite3_limit()].**
29c20 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 and limiting da
29c30 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e tabase size usin
29c40 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f g the [max_page_
29c50 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a count] [PRAGMA].
29c60 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 ** in addition t
29c70 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f o using an autho
29c80 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f rizer..**.** ^(O
29c90 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 nly a single aut
29ca0 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 horizer can be i
29cb0 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 n place on a dat
29cc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
29cd0 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 .** at a time.
29ce0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c Each call to sql
29cf0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 ite3_set_authori
29d00 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 zer overrides th
29d10 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 e.** previous ca
29d20 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 ll.)^ ^Disable
29d30 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 the authorizer b
29d40 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e y installing a N
29d50 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a ULL callback..**
29d60 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 The authorizer
29d70 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 is disabled by d
29d80 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 efault..**.** Th
29d90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c e authorizer cal
29da0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 lback must not d
29db0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 o anything that
29dc0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 will modify.** t
29dd0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e he database conn
29de0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f ection that invo
29df0 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a ked the authoriz
29e00 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 er callback..**
29e10 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 Note that [sqlit
29e20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d e3_prepare_v2()]
29e30 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 and [sqlite3_st
29e40 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 ep()] both modif
29e50 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 y their.** datab
29e60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 ase connections
29e70 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 for the meaning
29e80 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 of "modify" in t
29e90 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a his paragraph..*
29ea0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 *.** ^When [sqli
29eb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
29ec0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 ] is used to pre
29ed0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 pare a statement
29ee0 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 , the.** stateme
29ef0 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 nt might be re-p
29f00 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b repared during [
29f10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
29f20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 due to a .** sch
29f30 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e ema change. Hen
29f40 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ce, the applicat
29f50 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 ion should ensur
29f60 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f e that the.** co
29f70 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 rrect authorizer
29f80 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e callback remain
29f90 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e s in place durin
29fa0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 g the [sqlite3_s
29fb0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e tep()]..**.** ^N
29fc0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74 ote that the aut
29fd0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
29fe0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 is invoked only
29ff0 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 during.** [sqli
2a000 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f te3_prepare()] o
2a010 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 r its variants.
2a020 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 Authorization i
2a030 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d s not.** perform
2a040 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d ed during statem
2a050 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 ent evaluation i
2a060 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 n [sqlite3_step(
2a070 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 )], unless.** as
2a080 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 stated in the p
2a090 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 revious paragrap
2a0a0 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 h, sqlite3_step(
2a0b0 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c ) invokes.** sql
2a0c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
2a0d0 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 ) to reprepare a
2a0e0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 statement after
2a0f0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 a schema change
2a100 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
2a110 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f int sqlite3_set_
2a120 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 authorizer(. sq
2a130 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a lite3*,. int (*
2a140 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 xAuth)(void*,int
2a150 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e ,const char*,con
2a160 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 st char*,const c
2a170 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a har*,const char*
2a180 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 ),. void *pUser
2a190 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 Data.);../*.** C
2a1a0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 API3REF: Authori
2a1b0 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 zer Return Codes
2a1c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
2a1d0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
2a1e0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 er | authorizer
2a1f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
2a200 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 n] must.** retur
2a210 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 n either [SQLITE
2a220 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 _OK] or one of t
2a230 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e hese two constan
2a240 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 ts in order.** t
2a250 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 o signal SQLite
2a260 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 whether or not t
2a270 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 he action is per
2a280 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 mitted. See the
2a290 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 .** [sqlite3_set
2a2a0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 _authorizer | au
2a2b0 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e thorizer documen
2a2c0 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 tation] for addi
2a2d0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d tional.** inform
2a2e0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 ation..**.** Not
2a2f0 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 e that SQLITE_IG
2a300 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 NORE is also use
2a310 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 d as a [conflict
2a320 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 resolution mode
2a330 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 ].** returned fr
2a340 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f om the [sqlite3_
2a350 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 vtab_on_conflict
2a360 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ()] interface..*
2a370 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2a380 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 _DENY 1 /* A
2a390 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 bort the SQL sta
2a3a0 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 tement with an e
2a3b0 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
2a3c0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 SQLITE_IGNORE 2
2a3d0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 /* Don't allow
2a3e0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e access, but don
2a3f0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 't generate an e
2a400 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 rror */../*.** C
2a410 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 API3REF: Authori
2a420 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 zer Action Codes
2a430 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 .**.** The [sqli
2a440 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
2a450 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 er()] interface
2a460 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c registers a call
2a470 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a back function.**
2a480 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 that is invoked
2a490 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 to authorize ce
2a4a0 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d rtain SQL statem
2a4b0 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 ent actions. Th
2a4c0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 e.** second para
2a4d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c meter to the cal
2a4e0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 lback is an inte
2a4f0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 ger code that sp
2a500 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 ecifies.** what
2a510 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 action is being
2a520 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 authorized. The
2a530 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 se are the integ
2a540 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 er action codes
2a550 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 that.** the auth
2a560 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
2a570 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a may be passed..*
2a580 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f *.** These actio
2a590 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 n code values si
2a5a0 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 gnify what kind
2a5b0 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 of operation is
2a5c0 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 to be.** authori
2a5d0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e zed. The 3rd an
2a5e0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 d 4th parameters
2a5f0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a to the authoriz
2a600 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 ation.** callbac
2a610 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 k function will
2a620 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 be parameters or
2a630 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 NULL depending
2a640 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 on which of thes
2a650 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 e.** codes is us
2a660 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
2a670 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 parameter. ^(T
2a680 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 he 5th parameter
2a690 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f to the.** autho
2a6a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 rizer callback i
2a6b0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 s the name of th
2a6c0 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 e database ("mai
2a6d0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 n", "temp",.** e
2a6e0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 tc.) if applicab
2a6f0 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 le.)^ ^The 6th
2a700 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 parameter to the
2a710 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
2a720 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e back.** is the n
2a730 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 ame of the inner
2a740 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 -most trigger or
2a750 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 view that is re
2a760 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a sponsible for.**
2a770 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 the access atte
2a780 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 mpt or NULL if t
2a790 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d his access attem
2a7a0 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 pt is directly f
2a7b0 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c rom.** top-level
2a7c0 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a SQL code..*/./*
2a7d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2a7e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
2a7f0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a ********** 3rd *
2a800 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 *********** 4th
2a810 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 ***********/.#de
2a820 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 fine SQLITE_CREA
2a830 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 TE_INDEX
2a840 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 1 /* Index N
2a850 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e ame Table N
2a860 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
2a870 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 ine SQLITE_CREAT
2a880 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 E_TABLE
2a890 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 2 /* Table Na
2a8a0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
2a8b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
2a8c0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 ne SQLITE_CREATE
2a8d0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 _TEMP_INDEX
2a8e0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 3 /* Index Nam
2a8f0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d e Table Nam
2a900 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
2a910 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
2a920 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 TEMP_TABLE 4
2a930 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
2a940 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
2a950 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
2a960 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
2a970 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 EMP_TRIGGER 5
2a980 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d /* Trigger Nam
2a990 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 e Table Name
2a9a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
2a9b0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
2a9c0 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 MP_VIEW 6
2a9d0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 /* View Name
2a9e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
2a9f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
2aa00 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 QLITE_CREATE_TRI
2aa10 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 GGER 7
2aa20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 /* Trigger Name
2aa30 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 Table Name
2aa40 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
2aa50 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 LITE_CREATE_VIEW
2aa60 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 8 /
2aa70 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 * View Name
2aa80 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
2aa90 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
2aaa0 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 ITE_DELETE
2aab0 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 9 /*
2aac0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 Table Name
2aad0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
2aae0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
2aaf0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 TE_DROP_INDEX
2ab00 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 10 /*
2ab10 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 Index Name
2ab20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
2ab30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2ab40 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 E_DROP_TABLE
2ab50 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 11 /* T
2ab60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e able Name N
2ab70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
2ab80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2ab90 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 _DROP_TEMP_INDEX
2aba0 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 12 /* In
2abb0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 dex Name Ta
2abc0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f ble Name */
2abd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2abe0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 DROP_TEMP_TABLE
2abf0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 13 /* Tab
2ac00 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c le Name NUL
2ac10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a L */.
2ac20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
2ac30 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 ROP_TEMP_TRIGGER
2ac40 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 14 /* Trig
2ac50 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c ger Name Tabl
2ac60 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 e Name */.#
2ac70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
2ac80 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 OP_TEMP_VIEW
2ac90 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 15 /* View
2aca0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
2acb0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
2acc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
2acd0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 P_TRIGGER
2ace0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 16 /* Trigge
2acf0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 r Name Table
2ad00 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
2ad10 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
2ad20 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 _VIEW
2ad30 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 17 /* View Na
2ad40 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 me NULL
2ad50 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 */.#def
2ad60 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 ine SQLITE_INSER
2ad70 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
2ad80 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 18 /* Table Na
2ad90 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 me NULL
2ada0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
2adb0 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 ne SQLITE_PRAGMA
2adc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 1
2add0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 9 /* Pragma Na
2ade0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f me 1st arg o
2adf0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e r NULL */.#defin
2ae00 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 e SQLITE_READ
2ae10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20
2ae20 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 /* Table Name
2ae30 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d Column Nam
2ae40 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 e */.#define
2ae50 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 SQLITE_SELECT
2ae60 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 21
2ae70 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 /* NULL
2ae80 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
2ae90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
2aea0 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 SQLITE_TRANSACTI
2aeb0 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 ON 22
2aec0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 /* Operation
2aed0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
2aee0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
2aef0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 QLITE_UPDATE
2af00 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 23
2af10 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
2af20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
2af30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
2af40 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 LITE_ATTACH
2af50 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 24 /
2af60 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 * Filename
2af70 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
2af80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
2af90 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 ITE_DETACH
2afa0 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 25 /*
2afb0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 Database Name
2afc0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
2afd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
2afe0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 TE_ALTER_TABLE
2aff0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 26 /*
2b000 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 Database Name
2b010 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
2b020 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2b030 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 E_REINDEX
2b040 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 27 /* I
2b050 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e ndex Name N
2b060 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
2b070 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2b080 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 _ANALYZE
2b090 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 28 /* Ta
2b0a0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
2b0b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
2b0c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2b0d0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 CREATE_VTABLE
2b0e0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 29 /* Tab
2b0f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 le Name Mod
2b100 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a ule Name */.
2b110 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
2b120 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ROP_VTABLE
2b130 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 30 /* Tabl
2b140 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 e Name Modu
2b150 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 le Name */.#
2b160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 define SQLITE_FU
2b170 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 NCTION
2b180 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 31 /* NULL
2b190 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 Funct
2b1a0 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 ion Name */.#d
2b1b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 efine SQLITE_SAV
2b1c0 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 EPOINT
2b1d0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 32 /* Operat
2b1e0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f ion Savepo
2b1f0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 int Name */.#de
2b200 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 fine SQLITE_COPY
2b210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
2b220 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 0 /* No long
2b230 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 er used */.#defi
2b240 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 ne SQLITE_RECURS
2b250 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 IVE 3
2b260 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 3 /* NULL
2b270 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 NULL
2b280 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a */../*.**
2b290 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 CAPI3REF: Traci
2b2a0 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 ng And Profiling
2b2b0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 Functions.** ME
2b2c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
2b2d0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e .** These routin
2b2e0 65 73 20 61 72 65 20 64 65 70 72 65 63 61 74 65 es are deprecate
2b2f0 64 2e 20 55 73 65 20 74 68 65 20 5b 73 71 6c 69 d. Use the [sqli
2b300 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 te3_trace_v2()]
2b310 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 interface.** ins
2b320 74 65 61 64 20 6f 66 20 74 68 65 20 72 6f 75 74 tead of the rout
2b330 69 6e 65 73 20 64 65 73 63 72 69 62 65 64 20 68 ines described h
2b340 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 ere..**.** These
2b350 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 routines regist
2b360 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 er callback func
2b370 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 tions that can b
2b380 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 e used for.** tr
2b390 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c acing and profil
2b3a0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f ing the executio
2b3b0 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 n of SQL stateme
2b3c0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
2b3d0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
2b3e0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 n registered by
2b3f0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
2b400 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a is invoked at.**
2b410 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 various times w
2b420 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 hen an SQL state
2b430 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 ment is being ru
2b440 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 n by [sqlite3_st
2b450 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 ep()]..** ^The s
2b460 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 qlite3_trace() c
2b470 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
2b480 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 ed with a UTF-8
2b490 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 rendering of the
2b4a0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e .** SQL statemen
2b4b0 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74 t text as the st
2b4c0 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 atement first be
2b4d0 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a gins executing..
2b4e0 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 ** ^(Additional
2b4f0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 sqlite3_trace()
2b500 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 callbacks might
2b510 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 occur.** as each
2b520 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72 triggered subpr
2b530 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 ogram is entered
2b540 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 . The callbacks
2b550 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a for triggers.**
2b560 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 contain a UTF-8
2b570 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 SQL comment tha
2b580 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 t identifies the
2b590 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a trigger.)^.**.*
2b5a0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 * The [SQLITE_TR
2b5b0 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 ACE_SIZE_LIMIT]
2b5c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
2b5d0 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 ion can be used
2b5e0 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 to limit.** the
2b5f0 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 length of [bound
2b600 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 parameter] expa
2b610 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 nsion in the out
2b620 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 put of sqlite3_t
2b630 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 race()..**.** ^T
2b640 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 he callback func
2b650 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 tion registered
2b660 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 by sqlite3_profi
2b670 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a le() is invoked.
2b680 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 ** as each SQL s
2b690 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 tatement finishe
2b6a0 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 s. ^The profile
2b6b0 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 callback contai
2b6c0 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e ns.** the origin
2b6d0 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 al statement tex
2b6e0 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 t and an estimat
2b6f0 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 e of wall-clock
2b700 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c time.** of how l
2b710 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 ong that stateme
2b720 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 nt took to run.
2b730 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 ^The profile ca
2b740 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 llback.** time i
2b750 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 s in units of na
2b760 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 noseconds, howev
2b770 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 er the current i
2b780 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a mplementation.**
2b790 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 is only capable
2b7a0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 of millisecond
2b7b0 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 resolution so th
2b7c0 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e e six least sign
2b7d0 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 ificant.** digit
2b7e0 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 s in the time ar
2b7f0 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 e meaningless.
2b800 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 Future versions
2b810 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 of SQLite.** mig
2b820 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 ht provide great
2b830 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e er resolution on
2b840 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 the profiler ca
2b850 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 llback. The.**
2b860 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
2b870 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f ) function is co
2b880 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d nsidered experim
2b890 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 ental and is.**
2b8a0 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 subject to chang
2b8b0 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 e in future vers
2b8c0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a ions of SQLite..
2b8d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 */.SQLITE_API SQ
2b8e0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 LITE_DEPRECATED
2b8f0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 void *sqlite3_tr
2b900 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 ace(sqlite3*,.
2b910 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 void(*xTrace)(v
2b920 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a oid*,const char*
2b930 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 ), void*);.SQLIT
2b940 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 E_API SQLITE_DEP
2b950 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71 RECATED void *sq
2b960 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 lite3_profile(sq
2b970 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 lite3*,. void(
2b980 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a *xProfile)(void*
2b990 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c ,const char*,sql
2b9a0 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f ite3_uint64), vo
2b9b0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 id*);../*.** CAP
2b9c0 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 I3REF: SQL Trace
2b9d0 20 45 76 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 Event Codes.**
2b9e0 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 KEYWORDS: SQLITE
2b9f0 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 _TRACE.**.** The
2ba00 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 se constants ide
2ba10 6e 74 69 66 79 20 63 6c 61 73 73 65 73 20 6f 66 ntify classes of
2ba20 20 65 76 65 6e 74 73 20 74 68 61 74 20 63 61 6e events that can
2ba30 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a be monitored.**
2ba40 20 75 73 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 using the [sqli
2ba50 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 te3_trace_v2()]
2ba60 74 72 61 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 tracing logic.
2ba70 54 68 65 20 4d 20 61 72 67 75 6d 65 6e 74 0a 2a The M argument.*
2ba80 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 * to [sqlite3_tr
2ba90 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 5d ace_v2(D,M,X,P)]
2baa0 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d is an OR-ed com
2bab0 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 bination of one
2bac0 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 or more of.** th
2bad0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 e following cons
2bae0 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72 tants. ^The fir
2baf0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 st argument to t
2bb00 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 he trace callbac
2bb10 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 k.** is one of t
2bb20 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e he following con
2bb30 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 stants..**.** Ne
2bb40 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 w tracing consta
2bb50 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 nts may be added
2bb60 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 in future relea
2bb70 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 ses..**.** ^A tr
2bb80 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 ace callback has
2bb90 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a four arguments:
2bba0 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 xCallback(T,C,P
2bbb0 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 ,X)..** ^The T a
2bbc0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f rgument is one o
2bbd0 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79 f the integer ty
2bbe0 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a pe codes above..
2bbf0 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 ** ^The C argume
2bc00 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 nt is a copy of
2bc10 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e the context poin
2bc20 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73 ter passed in as
2bc30 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 the.** fourth a
2bc40 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 rgument to [sqli
2bc50 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e te3_trace_v2()].
2bc60 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 .** The P and X
2bc70 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f arguments are po
2bc80 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 inters whose mea
2bc90 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 nings depend on
2bca0 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a T..**.** <dl>.**
2bcb0 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f [[SQLITE_TRACE_
2bcc0 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 STMT]] <dt>SQLIT
2bcd0 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 E_TRACE_STMT</dt
2bce0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c >.** <dd>^An SQL
2bcf0 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 ITE_TRACE_STMT c
2bd00 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b allback is invok
2bd10 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72 ed when a prepar
2bd20 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 ed statement.**
2bd30 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e first begins run
2bd40 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c ning and possibl
2bd50 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73 y at other times
2bd60 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 during the.** e
2bd70 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 xecution of the
2bd80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2bd90 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74 nt, such as at t
2bda0 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68 he start of each
2bdb0 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70 .** trigger subp
2bdc0 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 rogram. ^The P a
2bdd0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
2bde0 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b nter to the.** [
2bdf0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
2be00 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75 nt]. ^The X argu
2be10 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
2be20 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 r to a string wh
2be30 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e ich.** is the un
2be40 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78 expanded SQL tex
2be50 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 t of the prepare
2be60 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 d statement or a
2be70 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a n SQL comment .*
2be80 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 * that indicates
2be90 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 the invocation
2bea0 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e of a trigger. ^
2beb0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e The callback can
2bec0 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 compute.** the
2bed0 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77 same text that w
2bee0 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72 ould have been r
2bef0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c eturned by the l
2bf00 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 egacy [sqlite3_t
2bf10 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 race()].** inter
2bf20 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68 face by using th
2bf30 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65 e X argument whe
2bf40 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20 n X begins with
2bf50 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e "--" and invokin
2bf60 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 g.** [sqlite3_ex
2bf70 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f panded_sql(P)] o
2bf80 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 therwise..**.**
2bf90 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 [[SQLITE_TRACE_P
2bfa0 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c ROFILE]] <dt>SQL
2bfb0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c ITE_TRACE_PROFIL
2bfc0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 E</dt>.** <dd>^A
2bfd0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 n SQLITE_TRACE_P
2bfe0 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 ROFILE callback
2bff0 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69 provides approxi
2c000 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a mately the same.
2c010 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 ** information a
2c020 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 s is provided by
2c030 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 the [sqlite3_pr
2c040 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 ofile()] callbac
2c050 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 k..** ^The P arg
2c060 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 ument is a point
2c070 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 er to the [prepa
2c080 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 red statement] a
2c090 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 nd the.** X argu
2c0a0 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 ment points to a
2c0b0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 64-bit integer
2c0c0 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74 which is the est
2c0d0 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 imated of.** the
2c0e0 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 number of nanos
2c0f0 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70 econd that the p
2c100 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2c110 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a t took to run..*
2c120 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52 * ^The SQLITE_TR
2c130 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c ACE_PROFILE call
2c140 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
2c150 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 when the stateme
2c160 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a nt finishes..**.
2c170 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 ** [[SQLITE_TRAC
2c180 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 E_ROW]] <dt>SQLI
2c190 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 TE_TRACE_ROW</dt
2c1a0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c >.** <dd>^An SQL
2c1b0 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 ITE_TRACE_ROW ca
2c1c0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
2c1d0 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65 d whenever a pre
2c1e0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 pared.** stateme
2c1f0 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73 nt generates a s
2c200 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 ingle row of res
2c210 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 ult. .** ^The P
2c220 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 argument is a p
2c230 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 ointer to the [p
2c240 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
2c250 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 t] and the.** X
2c260 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 argument is unus
2c270 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 ed..**.** [[SQLI
2c280 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d TE_TRACE_CLOSE]]
2c290 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 <dt>SQLITE_TRAC
2c2a0 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 E_CLOSE</dt>.**
2c2b0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 <dd>^An SQLITE_T
2c2c0 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 RACE_CLOSE callb
2c2d0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
2c2e0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a hen a database.*
2c2f0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f * connection clo
2c300 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 ses..** ^The P a
2c310 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 rgument is a poi
2c320 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 nter to the [dat
2c330 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2c340 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 ] object.** and
2c350 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69 the X argument i
2c360 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 s unused..** </d
2c370 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
2c380 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 LITE_TRACE_STMT
2c390 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69 0x01.#defi
2c3a0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f ne SQLITE_TRACE_
2c3b0 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a PROFILE 0x02.
2c3c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 #define SQLITE_T
2c3d0 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20 RACE_ROW
2c3e0 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 0x04.#define SQL
2c3f0 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 ITE_TRACE_CLOSE
2c400 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 0x08../*.**
2c410 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 CAPI3REF: SQL T
2c420 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 race Hook.** MET
2c430 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
2c440 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f ** ^The sqlite3_
2c450 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 trace_v2(D,M,X,P
2c460 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 ) interface regi
2c470 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61 sters a trace ca
2c480 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 llback.** functi
2c490 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61 on X against [da
2c4a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
2c4b0 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 n] D, using prop
2c4c0 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 erty mask M.** a
2c4d0 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 nd context point
2c4e0 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58 er P. ^If the X
2c4f0 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 callback is.**
2c500 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d NULL or if the M
2c510 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 mask is zero, t
2c520 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64 hen tracing is d
2c530 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a isabled. The.**
2c540 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 M argument shou
2c550 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73 ld be the bitwis
2c560 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 e OR-ed combinat
2c570 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f ion of.** zero o
2c580 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 r more [SQLITE_T
2c590 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e RACE] constants.
2c5a0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c .**.** ^Each cal
2c5b0 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69 l to either sqli
2c5c0 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 te3_trace() or s
2c5d0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 qlite3_trace_v2(
2c5e0 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 ) overrides .**
2c5f0 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 (cancels) any pr
2c600 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c ior calls to sql
2c610 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 ite3_trace() or
2c620 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 sqlite3_trace_v2
2c630 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 ()..**.** ^The X
2c640 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 callback is inv
2c650 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e oked whenever an
2c660 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20 y of the events
2c670 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a identified by .*
2c680 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 * mask M occur.
2c690 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65 ^The integer re
2c6a0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 turn value from
2c6b0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 the callback is
2c6c0 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e currently.** ign
2c6d0 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69 ored, though thi
2c6e0 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20 s may change in
2c6f0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e future releases.
2c700 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d Callback.** im
2c710 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 plementations sh
2c720 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f ould return zero
2c730 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72 to ensure futur
2c740 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e e compatibility.
2c750 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 .**.** ^A trace
2c760 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f callback is invo
2c770 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72 ked with four ar
2c780 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 guments: callbac
2c790 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e k(T,C,P,X)..** ^
2c7a0 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 The T argument i
2c7b0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 s one of the [SQ
2c7c0 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 LITE_TRACE].** c
2c7d0 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 onstants to indi
2c7e0 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c cate why the cal
2c7f0 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 lback was invoke
2c800 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 d..** ^The C arg
2c810 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 ument is a copy
2c820 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 of the context p
2c830 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 ointer..** The P
2c840 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 and X arguments
2c850 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 are pointers wh
2c860 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 ose meanings dep
2c870 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 end on T..**.**
2c880 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 The sqlite3_trac
2c890 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 e_v2() interface
2c8a0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 is intended to
2c8b0 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61 replace the lega
2c8c0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 cy.** interfaces
2c8d0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 [sqlite3_trace(
2c8e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
2c8f0 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 profile()], both
2c900 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 of which.** are
2c910 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a deprecated..*/.
2c920 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
2c930 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 qlite3_trace_v2(
2c940 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 . sqlite3*,. u
2c950 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 nsigned uMask,.
2c960 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 int(*xCallback)
2c970 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c (unsigned,void*,
2c980 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 void*,void*),.
2c990 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f void *pCtx.);../
2c9a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 *.** CAPI3REF: Q
2c9b0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 uery Progress Ca
2c9c0 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f llbacks.** METHO
2c9d0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
2c9e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 ^The sqlite3_pr
2c9f0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 ogress_handler(D
2ca00 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 ,N,X,P) interfac
2ca10 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c e causes the cal
2ca20 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f lback.** functio
2ca30 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 n X to be invoke
2ca40 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 d periodically d
2ca50 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 uring long runni
2ca60 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b ng calls to.** [
2ca70 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c sqlite3_exec()],
2ca80 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
2ca90 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 ] and [sqlite3_g
2caa0 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a et_table()] for.
2cab0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ** database conn
2cac0 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 ection D. An ex
2cad0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 ample use for th
2cae0 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 is.** interface
2caf0 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 is to keep a GUI
2cb00 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 updated during
2cb10 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a a large query..*
2cb20 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 *.** ^The parame
2cb30 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 ter P is passed
2cb40 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f through as the o
2cb50 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f nly parameter to
2cb60 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 the .** callbac
2cb70 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e k function X. ^
2cb80 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 The parameter N
2cb90 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 is the approxima
2cba0 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a te number of .**
2cbb0 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e [virtual machin
2cbc0 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 e instructions]
2cbd0 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 that are evaluat
2cbe0 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 ed between succe
2cbf0 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 ssive.** invocat
2cc00 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c ions of the call
2cc10 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 back X. ^If N i
2cc20 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 s less than one
2cc30 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 then the progres
2cc40 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 s.** handler is
2cc50 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 disabled..**.**
2cc60 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 ^Only a single p
2cc70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 rogress handler
2cc80 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 may be defined a
2cc90 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a t one time per.*
2cca0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e * [database conn
2ccb0 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 ection]; setting
2ccc0 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 a new progress
2ccd0 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 handler cancels
2cce0 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 the.** old one.
2ccf0 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 ^Setting parame
2cd00 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 ter X to NULL di
2cd10 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 sables the progr
2cd20 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 ess handler..**
2cd30 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 ^The progress ha
2cd40 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 ndler is also di
2cd50 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e sabled by settin
2cd60 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c g N to a value l
2cd70 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a ess.** than 1..*
2cd80 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f *.** ^If the pro
2cd90 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 gress callback r
2cda0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c eturns non-zero,
2cdb0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 the operation i
2cdc0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 s.** interrupted
2cdd0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 . This feature
2cde0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 can be used to i
2cdf0 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 mplement a.** "C
2ce00 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e ancel" button on
2ce10 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 a GUI progress
2ce20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a dialog box..**.*
2ce30 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 * The progress h
2ce40 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 andler callback
2ce50 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 must not do anyt
2ce60 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d hing that will m
2ce70 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 odify.** the dat
2ce80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
2ce90 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 that invoked th
2cea0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
2ceb0 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 er..** Note that
2cec0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
2ced0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c e_v2()] and [sql
2cee0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 ite3_step()] bot
2cef0 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a h modify their.*
2cf00 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 * database conne
2cf10 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d ctions for the m
2cf20 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 eaning of "modif
2cf30 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 y" in this parag
2cf40 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 raph..**.*/.SQLI
2cf50 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 TE_API void sqli
2cf60 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e te3_progress_han
2cf70 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 dler(sqlite3*, i
2cf80 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a nt, int(*)(void*
2cf90 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a ), void*);../*.*
2cfa0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e * CAPI3REF: Open
2cfb0 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 ing A New Databa
2cfc0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se Connection.**
2cfd0 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 CONSTRUCTOR: sq
2cfe0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 lite3.**.** ^The
2cff0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e se routines open
2d000 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 an SQLite datab
2d010 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 ase file as spec
2d020 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a ified by the .**
2d030 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
2d040 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d nt. ^The filenam
2d050 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e e argument is in
2d060 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 terpreted as UTF
2d070 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 -8 for.** sqlite
2d080 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 3_open() and sql
2d090 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 ite3_open_v2() a
2d0a0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 nd as UTF-16 in
2d0b0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a the native byte.
2d0c0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c ** order for sql
2d0d0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e ite3_open16(). ^
2d0e0 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e (A [database con
2d0f0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
2d100 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 is usually.** re
2d110 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c turned in *ppDb,
2d120 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f even if an erro
2d130 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f r occurs. The o
2d140 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 nly exception is
2d150 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 that.** if SQLi
2d160 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 te is unable to
2d170 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 allocate memory
2d180 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c to hold the [sql
2d190 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a ite3] object,.**
2d1a0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 a NULL will be
2d1b0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 written into *pp
2d1c0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 Db instead of a
2d1d0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b pointer to the [
2d1e0 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 sqlite3].** obje
2d1f0 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 ct.)^ ^(If the d
2d200 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
2d210 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 d (and/or create
2d220 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c d) successfully,
2d230 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 then.** [SQLITE
2d240 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 _OK] is returned
2d250 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 . Otherwise an
2d260 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
2d270 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 returned.)^ ^The
2d280 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 .** [sqlite3_err
2d290 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 msg()] or [sqlit
2d2a0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 e3_errmsg16()] r
2d2b0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 outines can be u
2d2c0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a sed to obtain.**
2d2d0 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 an English lang
2d2e0 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e uage description
2d2f0 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f of the error fo
2d300 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 llowing a failur
2d310 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 e of any.** of t
2d320 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 he sqlite3_open(
2d330 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a ) routines..**.*
2d340 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 * ^The default e
2d350 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 ncoding will be
2d360 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 UTF-8 for databa
2d370 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e ses created usin
2d380 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 g.** sqlite3_ope
2d390 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f n() or sqlite3_o
2d3a0 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 pen_v2(). ^The
2d3b0 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 default encoding
2d3c0 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a for databases.*
2d3d0 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 * created using
2d3e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 sqlite3_open16()
2d3f0 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 will be UTF-16
2d400 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 in the native by
2d410 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 te order..**.**
2d420 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 Whether or not a
2d430 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 n error occurs w
2d440 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 hen it is opened
2d450 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 , resources.** a
2d460 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
2d470 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e he [database con
2d480 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 nection] handle
2d490 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 should be releas
2d4a0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 ed by.** passing
2d4b0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f it to [sqlite3_
2d4c0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 close()] when it
2d4d0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 is no longer re
2d4e0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 quired..**.** Th
2d4f0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 e sqlite3_open_v
2d500 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 2() interface wo
2d510 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 rks like sqlite3
2d520 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 _open().** excep
2d530 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 t that it accept
2d540 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c s two additional
2d550 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 parameters for
2d560 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 additional contr
2d570 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e ol.** over the n
2d580 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e ew database conn
2d590 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 ection. ^(The f
2d5a0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 lags parameter t
2d5b0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 o.** sqlite3_ope
2d5c0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 n_v2() can take
2d5d0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f one of.** the fo
2d5e0 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 llowing three va
2d5f0 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 lues, optionally
2d600 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 combined with t
2d610 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f he .** [SQLITE_O
2d620 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 PEN_NOMUTEX], [S
2d630 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d QLITE_OPEN_FULLM
2d640 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f UTEX], [SQLITE_O
2d650 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d PEN_SHAREDCACHE]
2d660 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 ,.** [SQLITE_OPE
2d670 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c N_PRIVATECACHE],
2d680 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f and/or [SQLITE_
2d690 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a OPEN_URI] flags:
2d6a0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a )^.**.** <dl>.**
2d6b0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f ^(<dt>[SQLITE_O
2d6c0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 PEN_READONLY]</d
2d6d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
2d6e0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
2d6f0 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f in read-only mo
2d700 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 de. If the data
2d710 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a base does not.**
2d720 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 already exist,
2d730 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 an error is retu
2d740 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a rned.</dd>)^.**.
2d750 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 ** ^(<dt>[SQLITE
2d760 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d _OPEN_READWRITE]
2d770 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
2d780 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 database is ope
2d790 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 ned for reading
2d7a0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 and writing if p
2d7b0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 ossible, or read
2d7c0 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 ing.** only if t
2d7d0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 he file is write
2d7e0 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 protected by th
2d7f0 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 e operating syst
2d800 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a em. In either.*
2d810 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 * case the datab
2d820 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 ase must already
2d830 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 exist, otherwis
2d840 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 e an error is re
2d850 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a turned.</dd>)^.*
2d860 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 *.** ^(<dt>[SQLI
2d870 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 TE_OPEN_READWRIT
2d880 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 E] | [SQLITE_OPE
2d890 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a N_CREATE]</dt>.*
2d8a0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 * <dd>The databa
2d8b0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
2d8c0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 reading and wri
2d8d0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 ting, and is cre
2d8e0 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f ated if.** it do
2d8f0 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 es not already e
2d900 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 xist. This is th
2d910 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 e behavior that
2d920 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 is always used f
2d930 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 or.** sqlite3_op
2d940 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
2d950 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 _open16().</dd>)
2d960 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a ^.** </dl>.**.**
2d970 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 If the 3rd para
2d980 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
2d990 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f _open_v2() is no
2d9a0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 t one of the.**
2d9b0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f combinations sho
2d9c0 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 wn above optiona
2d9d0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 lly combined wit
2d9e0 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 h other.** [SQLI
2d9f0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 TE_OPEN_READONLY
2da00 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a | SQLITE_OPEN_*
2da10 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 bits].** then t
2da20 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 he behavior is u
2da30 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
2da40 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f ^If the [SQLITE_
2da50 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c OPEN_NOMUTEX] fl
2da60 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 ag is set, then
2da70 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2da80 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 nection.** opens
2da90 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 in the multi-th
2daa0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 read [threading
2dab0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 mode] as long as
2dac0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 the single-thre
2dad0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e ad.** mode has n
2dae0 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 ot been set at c
2daf0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 ompile-time or s
2db00 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 tart-time. ^If
2db10 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f the.** [SQLITE_O
2db20 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 PEN_FULLMUTEX] f
2db30 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 lag is set then
2db40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
2db50 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a nection opens.**
2db60 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a in the serializ
2db70 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f ed [threading mo
2db80 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c de] unless singl
2db90 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 e-thread was.**
2dba0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 previously selec
2dbb0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 ted at compile-t
2dbc0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d ime or start-tim
2dbd0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 e..** ^The [SQLI
2dbe0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
2dbf0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 CHE] flag causes
2dc00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f the database co
2dc10 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a nnection to be.*
2dc20 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 * eligible to us
2dc30 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 e [shared cache
2dc40 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 mode], regardles
2dc50 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
2dc60 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 not shared.** ca
2dc70 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 che is enabled u
2dc80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e sing [sqlite3_en
2dc90 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 able_shared_cach
2dca0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b e()]. ^The.** [
2dcb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
2dcc0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 ATECACHE] flag c
2dcd0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 auses the databa
2dce0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f se connection to
2dcf0 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 not.** particip
2dd00 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 ate in [shared c
2dd10 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 ache mode] even
2dd20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 if it is enabled
2dd30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 ..**.** ^The fou
2dd40 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
2dd50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 sqlite3_open_v2
2dd60 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f () is the name o
2dd70 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 f the.** [sqlite
2dd80 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 3_vfs] object th
2dd90 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f at defines the o
2dda0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 perating system
2ddb0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a interface that.*
2ddc0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 * the new databa
2ddd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 se connection sh
2dde0 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 ould use. ^If t
2ddf0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
2de00 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c ter is.** a NULL
2de10 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 pointer then th
2de20 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 e default [sqlit
2de30 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 e3_vfs] object i
2de40 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 s used..**.** ^I
2de50 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 f the filename i
2de60 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 s ":memory:", th
2de70 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 en a private, te
2de80 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 mporary in-memor
2de90 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 y database.** is
2dea0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 created for the
2deb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 connection. ^T
2dec0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 his in-memory da
2ded0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 tabase will vani
2dee0 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 sh when.** the d
2def0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2df00 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 on is closed. F
2df10 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f uture versions o
2df20 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a f SQLite might.*
2df30 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 * make use of ad
2df40 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c ditional special
2df50 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 filenames that
2df60 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 begin with the "
2df70 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a :" character..**
2df80 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 It is recommend
2df90 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 ed that when a d
2dfa0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 atabase filename
2dfb0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 actually does b
2dfc0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 egin with.** a "
2dfd0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 :" character you
2dfe0 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 should prefix t
2dff0 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 he filename with
2e000 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 a pathname such
2e010 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 as.** "./" to a
2e020 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a void ambiguity..
2e030 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 **.** ^If the fi
2e040 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 lename is an emp
2e050 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 ty string, then
2e060 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f a private, tempo
2e070 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 rary.** on-disk
2e080 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 database will be
2e090 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 created. ^This
2e0a0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 private databas
2e0b0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 e will be.** aut
2e0c0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 omatically delet
2e0d0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 ed as soon as th
2e0e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2e0f0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e ction is closed.
2e100 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c .**.** [[URI fil
2e110 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 enames in sqlite
2e120 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 3_open()]] <h3>U
2e130 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 RI Filenames</h3
2e140 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 >.**.** ^If [URI
2e150 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 filename] inter
2e160 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 pretation is ena
2e170 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 bled, and the fi
2e180 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a lename argument.
2e190 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 ** begins with "
2e1a0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 file:", then the
2e1b0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 filename is int
2e1c0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 erpreted as a UR
2e1d0 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e I. ^URI.** filen
2e1e0 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 ame interpretati
2e1f0 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 on is enabled if
2e200 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
2e210 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a N_URI] flag is.*
2e220 2a 20 73 65 74 20 69 6e 20 74 68 65 20 74 68 69 * set in the thi
2e230 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
2e240 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
2e250 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a , or if it has.*
2e260 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 * been enabled g
2e270 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 lobally using th
2e280 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 e [SQLITE_CONFIG
2e290 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 _URI] option wit
2e2a0 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 h the.** [sqlite
2e2b0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 3_config()] meth
2e2c0 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 od or by the [SQ
2e2d0 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f LITE_USE_URI] co
2e2e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
2e2f0 6e 2e 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 n..** URI filena
2e300 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f me interpretatio
2e310 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a n is turned off.
2e320 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 ** by default, b
2e330 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 ut future releas
2e340 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 es of SQLite mig
2e350 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 ht enable URI fi
2e360 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 lename.** interp
2e370 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 retation by defa
2e380 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 ult. See "[URI
2e390 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 filenames]" for
2e3a0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e additional.** in
2e3b0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a formation..**.**
2e3c0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 URI filenames a
2e3d0 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 re parsed accord
2e3e0 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e ing to RFC 3986.
2e3f0 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e ^If the URI con
2e400 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 tains an.** auth
2e410 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d ority, then it m
2e420 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e ust be either an
2e430 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 empty string or
2e440 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 the string .**
2e450 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 "localhost". ^If
2e460 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 the authority i
2e470 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 s not an empty s
2e480 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 tring or "localh
2e490 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 ost", an .** err
2e4a0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 or is returned t
2e4b0 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 o the caller. ^T
2e4c0 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 he fragment comp
2e4d0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 onent of a URI,
2e4e0 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 if .** present,
2e4f0 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a is ignored..**.*
2e500 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 * ^SQLite uses t
2e510 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e he path componen
2e520 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 t of the URI as
2e530 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
2e540 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 disk file.** whi
2e550 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 ch contains the
2e560 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 database. ^If th
2e570 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 e path begins wi
2e580 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 th a '/' charact
2e590 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 er, .** then it
2e5a0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 is interpreted a
2e5b0 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 s an absolute pa
2e5c0 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 th. ^If the path
2e5d0 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 does not begin
2e5e0 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 .** with a '/' (
2e5f0 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 meaning that the
2e600 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 authority secti
2e610 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 on is omitted fr
2e620 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 om the URI).** t
2e630 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 hen the path is
2e640 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
2e650 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 relative path.
2e660 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 .** ^(On windows
2e670 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 , the first comp
2e680 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f onent of an abso
2e690 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 lute path .** is
2e6a0 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 a drive specifi
2e6b0 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a cation (e.g. "C:
2e6c0 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f ").)^.**.** [[co
2e6d0 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 re URI query par
2e6e0 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 ameters]].** The
2e6f0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
2e700 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f of a URI may co
2e710 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 ntain parameters
2e720 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 that are interp
2e730 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 reted.** either
2e740 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 by SQLite itself
2e750 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c , or by a [VFS |
2e760 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c custom VFS impl
2e770 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 ementation]..**
2e780 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 SQLite and its b
2e790 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 uilt-in [VFSes]
2e7a0 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a interpret the.**
2e7b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 following query
2e7c0 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a parameters:.**.
2e7d0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 ** <ul>.** <li
2e7e0 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 > <b>vfs</b>: ^T
2e7f0 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 he "vfs" paramet
2e800 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 er may be used t
2e810 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 o specify the na
2e820 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 me of.** a V
2e830 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 FS object that p
2e840 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 rovides the oper
2e850 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 ating system int
2e860 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 erface that shou
2e870 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 ld.** be use
2e880 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 d to access the
2e890 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e database file on
2e8a0 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 disk. ^If this
2e8b0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f option is set to
2e8c0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 .** an empty
2e8d0 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 string the defa
2e8e0 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 ult VFS object i
2e8f0 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 s used. ^Specify
2e900 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a ing an unknown.*
2e910 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 * VFS is an
2e920 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 error. ^If sqlit
2e930 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 e3_open_v2() is
2e940 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 used and the vfs
2e950 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 option is.**
2e960 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 present, then
2e970 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 the VFS specifie
2e980 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 d by the option
2e990 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 takes precedence
2e9a0 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 over.** the
2e9b0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 value passed as
2e9c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 the fourth para
2e9d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
2e9e0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
2e9f0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 * <li> <b>mode
2ea00 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 </b>: ^(The mode
2ea10 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 parameter may b
2ea20 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 e set to either
2ea30 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 "ro", "rw",.**
2ea40 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 "rwc", or "me
2ea50 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e mory". Attemptin
2ea60 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 g to set it to a
2ea70 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 ny other value i
2ea80 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f s.** an erro
2ea90 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 r)^. .** ^If
2eaa0 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 "ro" is specifi
2eab0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 ed, then the dat
2eac0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
2ead0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a for read-only .*
2eae0 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 * access, ju
2eaf0 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 st as if the [SQ
2eb00 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
2eb10 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 LY] flag had bee
2eb20 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a n set in the .**
2eb30 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d third argum
2eb40 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ent to sqlite3_o
2eb50 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 pen_v2(). ^If th
2eb60 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 e mode option is
2eb70 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 set to .**
2eb80 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 "rw", then the d
2eb90 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 atabase is opene
2eba0 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 d for read-write
2ebb0 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 (but not create
2ebc0 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 ) .** access
2ebd0 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f , as if SQLITE_O
2ebe0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 PEN_READWRITE (b
2ebf0 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 ut not SQLITE_OP
2ec00 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a EN_CREATE) had .
2ec10 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e ** been set.
2ec20 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 ^Value "rwc" is
2ec30 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 equivalent to s
2ec40 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 etting both .**
2ec50 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f SQLITE_OPEN_
2ec60 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 READWRITE and SQ
2ec70 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 LITE_OPEN_CREATE
2ec80 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 . ^If the mode
2ec90 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 option is.**
2eca0 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 set to "memory"
2ecb0 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e then a pure [in
2ecc0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 -memory database
2ecd0 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 ] that never rea
2ece0 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 ds.** or wri
2ecf0 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 tes from disk is
2ed00 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e used. ^It is an
2ed10 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 error to specif
2ed20 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a y a value for.**
2ed30 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 the mode pa
2ed40 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 rameter that is
2ed50 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 less restrictive
2ed60 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 than that speci
2ed70 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 fied by.** t
2ed80 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 he flags passed
2ed90 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 in the third par
2eda0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ameter to sqlite
2edb0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 3_open_v2()..**.
2edc0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 ** <li> <b>cac
2edd0 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 he</b>: ^The cac
2ede0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 he parameter may
2edf0 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 be set to eithe
2ee00 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a r "shared" or.**
2ee10 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 "private".
2ee20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 ^Setting it to "
2ee30 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 shared" is equiv
2ee40 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 alent to setting
2ee50 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 the.** SQLI
2ee60 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
2ee70 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 CHE bit in the f
2ee80 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 lags argument pa
2ee90 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 ssed to.** s
2eea0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
2eeb0 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 . ^Setting the c
2eec0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 ache parameter t
2eed0 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a o "private" is .
2eee0 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e ** equivalen
2eef0 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 t to setting the
2ef00 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 SQLITE_OPEN_PRI
2ef10 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a VATECACHE bit..*
2ef20 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 * ^If sqlite
2ef30 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 3_open_v2() is u
2ef40 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 sed and the "cac
2ef50 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 he" parameter is
2ef60 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 present in.**
2ef70 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d a URI filenam
2ef80 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 e, its value ove
2ef90 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 rrides any behav
2efa0 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 ior requested by
2efb0 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 setting.**
2efc0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 SQLITE_OPEN_PRIV
2efd0 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 ATECACHE or SQLI
2efe0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 TE_OPEN_SHAREDCA
2eff0 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 CHE flag..**.**
2f000 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 <li> <b>psow</b
2f010 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 >: ^The psow par
2f020 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 ameter indicates
2f030 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
2f040 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 the.** [powe
2f050 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d rsafe overwrite]
2f060 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f property does o
2f070 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 r does not apply
2f080 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 to the.** s
2f090 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 torage media on
2f0a0 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 which the databa
2f0b0 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e se file resides.
2f0c0 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e .**.** <li> <b>
2f0d0 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 nolock</b>: ^The
2f0e0 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 nolock paramete
2f0f0 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 r is a boolean q
2f100 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a uery parameter.*
2f110 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 * which if s
2f120 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 et disables file
2f130 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c locking in roll
2f140 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 back journal mod
2f150 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 es. This.**
2f160 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 is useful for a
2f170 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 ccessing a datab
2f180 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 ase on a filesys
2f190 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f tem that does no
2f1a0 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 t.** support
2f1b0 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 locking. Cauti
2f1c0 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f on: Database co
2f1d0 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 rruption might r
2f1e0 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 esult if two.**
2f1f0 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 or more proc
2f200 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 esses write to t
2f210 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 he same database
2f220 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 and any one of
2f230 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f those.** pro
2f240 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f cesses uses nolo
2f250 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 ck=1..**.** <li
2f260 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f > <b>immutable</
2f270 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 b>: ^The immutab
2f280 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 le parameter is
2f290 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a a boolean query.
2f2a0 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 ** parameter
2f2b0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 that indicates
2f2c0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 that the databas
2f2d0 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 e file is stored
2f2e0 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d on.** read-
2f2f0 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 only media. ^Wh
2f300 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 en immutable is
2f310 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 set, SQLite assu
2f320 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 mes that the.**
2f330 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c database fil
2f340 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e e cannot be chan
2f350 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 ged, even by a p
2f360 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 rocess with high
2f370 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c er.** privil
2f380 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 ege, and so the
2f390 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e database is open
2f3a0 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 ed read-only and
2f3b0 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 all locking.**
2f3c0 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 and change d
2f3d0 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 etection is disa
2f3e0 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 bled. Caution:
2f3f0 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 Setting the immu
2f400 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f table.** pro
2f410 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 perty on a datab
2f420 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f ase file that do
2f430 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 es in fact chang
2f440 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 e can result.**
2f450 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 in incorrect
2f460 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 query results a
2f470 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f nd/or [SQLITE_CO
2f480 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a RRUPT] errors..*
2f490 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 * See also:
2f4a0 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d [SQLITE_IOCAP_IM
2f4b0 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 MUTABLE]..**
2f4c0 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a .** </ul>.**.
2f4d0 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 ** ^Specifying a
2f4e0 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 n unknown parame
2f4f0 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 ter in the query
2f500 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 component of a
2f510 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a URI is not an.**
2f520 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 error. Future
2f530 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 versions of SQLi
2f540 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 te might underst
2f550 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 and additional q
2f560 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 uery.** paramete
2f570 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 rs. See "[query
2f580 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 parameters with
2f590 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 special meaning
2f5a0 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 to SQLite]" for
2f5b0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 .** additional i
2f5c0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a nformation..**.*
2f5d0 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 * [[URI filename
2f5e0 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e examples]] <h3>
2f5f0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 URI filename exa
2f600 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a mples</h3>.**.**
2f610 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 <table border="
2f620 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 1" align=center
2f630 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a cellpadding=5>.*
2f640 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 * <tr><th> URI f
2f650 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 ilenames <th> Re
2f660 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 sults.** <tr><td
2f670 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c > file:data.db <
2f680 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
2f690 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 Open the file "
2f6a0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 data.db" in the
2f6b0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 current director
2f6c0 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 y..** <tr><td> f
2f6d0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 ile:/home/fred/d
2f6e0 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 ata.db<br>.**
2f6f0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 file:///h
2f700 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 ome/fred/data.db
2f710 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 <br> .**
2f720 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 file://localh
2f730 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 ost/home/fred/da
2f740 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 ta.db <br> <td>
2f750 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 .** Ope
2f760 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 n the database f
2f770 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f ile "/home/fred/
2f780 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 data.db"..** <tr
2f790 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 ><td> file://dar
2f7a0 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f kstar/home/fred/
2f7b0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a data.db <td> .**
2f7c0 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 An err
2f7d0 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 or. "darkstar" i
2f7e0 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a s not a recogniz
2f7f0 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a ed authority..**
2f800 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 <tr><td style="
2f810 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 white-space:nowr
2f820 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 ap"> .**
2f830 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 file:///C:/Doc
2f840 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 uments%20and%20S
2f850 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 ettings/fred/Des
2f860 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 ktop/data.db.**
2f870 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 <td> Windows
2f880 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 only: Open the
2f890 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f file "data.db" o
2f8a0 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 n fred's desktop
2f8b0 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 on drive.**
2f8c0 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 C:. Note t
2f8d0 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 hat the %20 esca
2f8e0 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 ping in this exa
2f8f0 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 mple is not stri
2f900 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 ctly .**
2f910 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 necessary - sp
2f920 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 ace characters c
2f930 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 an be used liter
2f940 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 ally.**
2f950 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 in URI filename
2f960 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 s..** <tr><td> f
2f970 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 ile:data.db?mode
2f980 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 =ro&cache=privat
2f990 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 e <td> .**
2f9a0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 Open file "d
2f9b0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 ata.db" in the c
2f9c0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 urrent directory
2f9d0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 for read-only a
2f9e0 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 ccess..**
2f9f0 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 Regardless of
2fa00 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
2fa10 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 shared-cache mod
2fa20 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a e is enabled by.
2fa30 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 ** defa
2fa40 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 ult, use a priva
2fa50 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 te cache..** <tr
2fa60 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 ><td> file:/home
2fa70 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 /fred/data.db?vf
2fa80 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c s=unix-dotfile <
2fa90 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 td>.**
2faa0 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 Open file "/home
2fab0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 /fred/data.db".
2fac0 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 Use the special
2fad0 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c VFS "unix-dotfil
2fae0 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 e".** t
2faf0 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c hat uses dot-fil
2fb00 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 es in place of p
2fb10 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f osix advisory lo
2fb20 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 cking..** <tr><t
2fb30 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f d> file:data.db?
2fb40 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 mode=readonly <t
2fb50 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 d> .**
2fb60 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f An error. "reado
2fb70 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 nly" is not a va
2fb80 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 lid option for t
2fb90 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 he "mode" parame
2fba0 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e ter..** </table>
2fbb0 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 .**.** ^URI hexa
2fbc0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 decimal escape s
2fbd0 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 equences (%HH) a
2fbe0 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 re supported wit
2fbf0 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 hin the path and
2fc00 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e .** query compon
2fc10 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 ents of a URI. A
2fc20 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 hexadecimal esc
2fc30 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e ape sequence con
2fc40 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 sists of a.** pe
2fc50 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 rcent sign - "%"
2fc60 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 - followed by e
2fc70 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 xactly two hexad
2fc80 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a ecimal digits .*
2fc90 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 * specifying an
2fca0 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 octet value. ^Be
2fcb0 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 fore the path or
2fcc0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
2fcd0 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 s of a.** URI fi
2fce0 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 lename are inter
2fcf0 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 preted, they are
2fd00 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 encoded using U
2fd10 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a TF-8 and all .**
2fd20 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 hexadecimal esc
2fd30 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 ape sequences re
2fd40 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 placed by a sing
2fd50 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 le byte containi
2fd60 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 ng the.** corres
2fd70 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 ponding octet. I
2fd80 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 f this process g
2fd90 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 enerates an inva
2fda0 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 lid UTF-8 encodi
2fdb0 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c ng,.** the resul
2fdc0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 ts are undefined
2fdd0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 ..**.** <b>Note
2fde0 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 to Windows users
2fdf0 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 :</b> The encod
2fe00 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 ing used for the
2fe10 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 filename argume
2fe20 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 nt.** of sqlite3
2fe30 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 _open() and sqli
2fe40 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 te3_open_v2() mu
2fe50 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 st be UTF-8, not
2fe60 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 whatever.** cod
2fe70 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 epage is current
2fe80 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c ly defined. Fil
2fe90 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e enames containin
2fea0 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a g international.
2feb0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 ** characters mu
2fec0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 st be converted
2fed0 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 to UTF-8 prior t
2fee0 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 o passing them i
2fef0 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f nto.** sqlite3_o
2ff00 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 pen() or sqlite3
2ff10 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a _open_v2()..**.*
2ff20 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e * <b>Note to Win
2ff30 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 dows Runtime use
2ff40 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d rs:</b> The tem
2ff50 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 porary directory
2ff60 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 must be set.**
2ff70 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 prior to calling
2ff80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 sqlite3_open()
2ff90 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f or sqlite3_open_
2ffa0 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 v2(). Otherwise
2ffb0 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 , various.** fea
2ffc0 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 tures that requi
2ffd0 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 re the use of te
2ffe0 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 mporary files ma
2fff0 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 y fail..**.** Se
30000 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
30010 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d _temp_directory]
30020 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
30030 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 nt sqlite3_open(
30040 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 . const char *f
30050 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 ilename, /* Da
30060 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 tabase filename
30070 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c (UTF-8) */. sql
30080 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 ite3 **ppDb
30090 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c /* OUT: SQL
300a0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f ite db handle */
300b0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
300c0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 nt sqlite3_open1
300d0 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 6(. const void
300e0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 *filename, /*
300f0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d Database filenam
30100 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 e (UTF-16) */.
30110 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 sqlite3 **ppDb
30120 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
30130 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
30140 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
30150 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 I int sqlite3_op
30160 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 en_v2(. const c
30170 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 har *filename,
30180 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c /* Database fil
30190 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f ename (UTF-8) */
301a0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 . sqlite3 **ppD
301b0 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 b, /* OU
301c0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e T: SQLite db han
301d0 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 dle */. int fla
301e0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 gs,
301f0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 /* Flags */. c
30200 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 onst char *zVfs
30210 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f /* Name o
30220 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 f VFS module to
30230 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a use */.);../*.**
30240 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 CAPI3REF: Obtai
30250 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 n Values For URI
30260 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a Parameters.**.*
30270 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c * These are util
30280 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 ity routines, us
30290 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c eful to VFS impl
302a0 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 ementations, tha
302b0 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 t check.** to se
302c0 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 e if a database
302d0 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 file was a URI t
302e0 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 hat contained a
302f0 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a specific query .
30300 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e ** parameter, an
30310 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 d if so obtains
30320 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 the value of tha
30330 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 t query paramete
30340 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 r..**.** If F is
30350 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 the database fi
30360 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 lename pointer p
30370 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 assed into the x
30380 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 Open() method of
30390 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 .** a VFS imple
303a0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 mentation when t
303b0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 he flags paramet
303c0 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 er to xOpen() ha
303d0 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 s one or .** mor
303e0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 e of the [SQLITE
303f0 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 _OPEN_URI] or [S
30400 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f QLITE_OPEN_MAIN_
30410 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 DB] bits set and
30420 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d .** P is the nam
30430 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 e of the query p
30440 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a arameter, then.*
30450 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 * sqlite3_uri_pa
30460 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 rameter(F,P) ret
30470 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f urns the value o
30480 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d f the P.** param
30490 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 eter if it exist
304a0 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e s or a NULL poin
304b0 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f ter if P does no
304c0 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a t appear as a .*
304d0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 * query paramete
304e0 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 r on F. If P is
304f0 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 a query paramet
30500 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e er of F.** has n
30510 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 o explicit value
30520 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 , then sqlite3_u
30530 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 ri_parameter(F,P
30540 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 ) returns.** a p
30550 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 ointer to an emp
30560 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a ty string..**.**
30570 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 The sqlite3_uri
30580 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
30590 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 routine assumes
305a0 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c that P is a bool
305b0 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ean.** parameter
305c0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 and returns tru
305d0 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 e (1) or false (
305e0 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 0) according to
305f0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 the value.** of
30600 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f P. The sqlite3_
30610 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c uri_boolean(F,P,
30620 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 B) routine retur
30630 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 ns true (1) if t
30640 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 he.** value of q
30650 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 uery parameter P
30660 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 is one of "yes"
30670 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e , "true", or "on
30680 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 " in any.** case
30690 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 or if the value
306a0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e begins with a n
306b0 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 on-zero number.
306c0 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 The .** sqlite3
306d0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 _uri_boolean(F,P
306e0 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 ,B) routines ret
306f0 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 urns false (0) i
30700 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a f the value of.*
30710 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 * query paramete
30720 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e r P is one of "n
30730 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 o", "false", or
30740 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 "off" in any cas
30750 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 e or.** if the v
30760 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 alue begins with
30770 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e a numeric zero.
30780 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 If P is not a
30790 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 query.** paramet
307a0 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 er on F or if th
307b0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 e value of P is
307c0 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 does not match a
307d0 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f ny of the.** abo
307e0 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 ve, then sqlite3
307f0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 _uri_boolean(F,P
30800 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d ,B) returns (B!=
30810 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 0)..**.** The sq
30820 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 lite3_uri_int64(
30830 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 F,P,D) routine c
30840 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 onverts the valu
30850 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a e of P into a.**
30860 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 64-bit signed i
30870 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 nteger and retur
30880 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c ns that integer,
30890 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 or D if P does
308a0 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 not.** exist. I
308b0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 f the value of P
308c0 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 is something ot
308d0 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 her than an inte
308e0 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 ger, then.** zer
308f0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a o is returned..*
30900 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 * .** If F is a
30910 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 NULL pointer, th
30920 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 en sqlite3_uri_p
30930 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 arameter(F,P) re
30940 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a turns NULL and.*
30950 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f * sqlite3_uri_bo
30960 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 olean(F,P,B) ret
30970 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 urns B. If F is
30980 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e not a NULL poin
30990 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f ter and.** is no
309a0 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c t a database fil
309b0 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 e pathname point
309c0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 er that SQLite p
309d0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 assed into the x
309e0 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 Open.** VFS meth
309f0 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 od, then the beh
30a00 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f avior of this ro
30a10 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e utine is undefin
30a20 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a ed and probably.
30a30 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a ** undesirable..
30a40 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
30a50 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
30a60 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 3_uri_parameter(
30a70 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c const char *zFil
30a80 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 ename, const cha
30a90 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 r *zParam);.SQLI
30aa0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
30ab0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 e3_uri_boolean(c
30ac0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 onst char *zFile
30ad0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 , const char *zP
30ae0 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 aram, int bDefau
30af0 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 lt);.SQLITE_API
30b00 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
30b10 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 lite3_uri_int64(
30b20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e const char*, con
30b30 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 st char*, sqlite
30b40 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 3_int64);.../*.*
30b50 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f * CAPI3REF: Erro
30b60 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 r Codes And Mess
30b70 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ages.** METHOD:
30b80 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 sqlite3.**.** ^I
30b90 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e f the most recen
30ba0 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 t sqlite3_* API
30bb0 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 call associated
30bc0 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 with .** [databa
30bd0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 se connection] D
30be0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 failed, then th
30bf0 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 e sqlite3_errcod
30c00 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a e(D) interface.*
30c10 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 * returns the nu
30c20 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f meric [result co
30c30 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 de] or [extended
30c40 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f result code] fo
30c50 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 r that.** API ca
30c60 6c 6c 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 ll..** ^The sqli
30c70 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 te3_extended_err
30c80 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 code().** interf
30c90 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 ace is the same
30ca0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 except that it a
30cb0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 lways returns th
30cc0 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 e .** [extended
30cd0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 result code] eve
30ce0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 n when extended
30cf0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 result codes are
30d00 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a .** disabled..**
30d10 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 73 20 72 .** The values r
30d20 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 eturned by sqlit
30d30 65 33 5f 65 72 72 63 6f 64 65 28 29 20 61 6e 64 e3_errcode() and
30d40 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 /or.** sqlite3_e
30d50 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
30d60 29 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 77 ) might change w
30d70 69 74 68 20 65 61 63 68 20 41 50 49 20 63 61 6c ith each API cal
30d80 6c 2e 0a 2a 2a 20 45 78 63 65 70 74 2c 20 74 68 l..** Except, th
30d90 65 72 65 20 61 72 65 20 73 6f 6d 65 20 69 6e 74 ere are some int
30da0 65 72 66 61 63 65 73 20 74 68 61 74 20 61 72 65 erfaces that are
30db0 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 6e guaranteed to n
30dc0 65 76 65 72 0a 2a 2a 20 63 68 61 6e 67 65 20 74 ever.** change t
30dd0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 he value of the
30de0 65 72 72 6f 72 20 63 6f 64 65 2e 20 20 54 68 65 error code. The
30df0 20 65 72 72 6f 72 2d 63 6f 64 65 20 70 72 65 73 error-code pres
30e00 65 72 76 69 6e 67 0a 2a 2a 20 69 6e 74 65 72 66 erving.** interf
30e10 61 63 65 73 20 61 72 65 3a 0a 2a 2a 0a 2a 2a 20 aces are:.**.**
30e20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c <ul>.** <li> sql
30e30 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 0a 2a ite3_errcode().*
30e40 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 33 5f 65 * <li> sqlite3_e
30e50 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 xtended_errcode(
30e60 29 0a 2a 2a 20 3c 6c 69 3e 20 73 71 6c 69 74 65 ).** <li> sqlite
30e70 33 5f 65 72 72 6d 73 67 28 29 0a 2a 2a 20 3c 6c 3_errmsg().** <l
30e80 69 3e 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 i> sqlite3_errms
30e90 67 31 36 28 29 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a g16().** </ul>.*
30ea0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
30eb0 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 3_errmsg() and s
30ec0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 qlite3_errmsg16(
30ed0 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 ) return English
30ee0 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 -language.** tex
30ef0 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 t that describes
30f00 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 the error, as e
30f10 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 ither UTF-8 or U
30f20 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 TF-16 respective
30f30 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 ly..** ^(Memory
30f40 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f to hold the erro
30f50 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 r message string
30f60 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 is managed inte
30f70 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 rnally..** The a
30f80 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 pplication does
30f90 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 not need to worr
30fa0 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 y about freeing
30fb0 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 the result..** H
30fc0 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f owever, the erro
30fd0 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 r string might b
30fe0 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 e overwritten or
30ff0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a deallocated by.
31000 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 ** subsequent ca
31010 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c lls to other SQL
31020 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 ite interface fu
31030 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a nctions.)^.**.**
31040 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 ^The sqlite3_er
31050 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 rstr() interface
31060 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 returns the Eng
31070 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 lish-language te
31080 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 xt.** that descr
31090 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 ibes the [result
310a0 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 code], as UTF-8
310b0 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f ..** ^(Memory to
310c0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 hold the error
310d0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 message string i
310e0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e s managed intern
310f0 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 ally.** and must
31100 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 not be freed by
31110 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
31120 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 )^..**.** When t
31130 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 he serialized [t
31140 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 hreading mode] i
31150 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 s in use, it mig
31160 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 ht be the.** cas
31170 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 e that a second
31180 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 error occurs on
31190 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 a separate threa
311a0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 d in between.**
311b0 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 the time of the
311c0 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 first error and
311d0 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 the call to thes
311e0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a e interfaces..**
311f0 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 When that happe
31200 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 ns, the second e
31210 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 rror will be rep
31220 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 orted since thes
31230 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 e.** interfaces
31240 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 always report th
31250 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 e most recent re
31260 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a sult. To avoid.
31270 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 ** this, each th
31280 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 read can obtain
31290 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 exclusive use of
312a0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
312b0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 onnection] D.**
312c0 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c by invoking [sql
312d0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 ite3_mutex_enter
312e0 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 ]([sqlite3_db_mu
312f0 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 tex](D)) before
31300 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 beginning.** to
31310 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 use D and invoki
31320 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 ng [sqlite3_mute
31330 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 x_leave]([sqlite
31340 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 3_db_mutex](D))
31350 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c after.** all cal
31360 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 ls to the interf
31370 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 aces listed here
31380 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a are completed..
31390 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 **.** If an inte
313a0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 rface fails with
313b0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 SQLITE_MISUSE,
313c0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 that means the i
313d0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 nterface.** was
313e0 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 invoked incorrec
313f0 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 tly by the appli
31400 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 cation. In that
31410 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 case, the.** er
31420 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 ror code and mes
31430 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 sage may or may
31440 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 not be set..*/.S
31450 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
31460 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 lite3_errcode(sq
31470 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 lite3 *db);.SQLI
31480 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
31490 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 e3_extended_errc
314a0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 ode(sqlite3 *db)
314b0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
314c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
314d0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a _errmsg(sqlite3*
314e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
314f0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 nst void *sqlite
31500 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 3_errmsg16(sqlit
31510 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 e3*);.SQLITE_API
31520 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
31530 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 ite3_errstr(int)
31540 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
31550 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 F: Prepared Stat
31560 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 ement Object.**
31570 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 KEYWORDS: {prepa
31580 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b red statement} {
31590 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
315a0 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e nts}.**.** An in
315b0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f stance of this o
315c0 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 bject represents
315d0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 a single SQL st
315e0 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 atement that.**
315f0 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 has been compile
31600 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f d into binary fo
31610 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 rm and is ready
31620 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e to be evaluated.
31630 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 .**.** Think of
31640 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 each SQL stateme
31650 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 nt as a separate
31660 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 computer progra
31670 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 m. The.** origi
31680 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 nal SQL text is
31690 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 source code. A
316a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
316b0 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 nt object .** is
316c0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 the compiled ob
316d0 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 ject code. All
316e0 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 SQL must be conv
316f0 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 erted into a.**
31700 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
31710 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e nt before it can
31720 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 be run..**.** T
31730 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 he life-cycle of
31740 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 a prepared stat
31750 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 ement object usu
31760 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 ally goes like t
31770 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a his:.**.** <ol>.
31780 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 ** <li> Create t
31790 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
317a0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 ement object usi
317b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ng [sqlite3_prep
317c0 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c are_v2()]..** <l
317d0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 i> Bind values t
317e0 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 o [parameters] u
317f0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 sing the sqlite3
31800 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 _bind_*().**
31810 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a interfaces..**
31820 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 <li> Run the SQ
31830 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 L by calling [sq
31840 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e lite3_step()] on
31850 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e e or more times.
31860 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 .** <li> Reset t
31870 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 he prepared stat
31880 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c ement using [sql
31890 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 ite3_reset()] th
318a0 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 en go back.**
318b0 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 to step 2. D
318c0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d o this zero or m
318d0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c ore times..** <l
318e0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f i> Destroy the o
318f0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c bject using [sql
31900 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
31910 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 ..** </ol>.*/.ty
31920 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
31930 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 ite3_stmt sqlite
31940 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 3_stmt;../*.** C
31950 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d API3REF: Run-tim
31960 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 e Limits.** METH
31970 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a OD: sqlite3.**.*
31980 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 * ^(This interfa
31990 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 ce allows the si
319a0 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f ze of various co
319b0 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c nstructs to be l
319c0 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 imited.** on a c
319d0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e onnection by con
319e0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 nection basis.
319f0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 The first parame
31a00 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 ter is the.** [d
31a10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
31a20 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 on] whose limit
31a30 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 is to be set or
31a40 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a queried. The.**
31a50 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 second paramete
31a60 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 r is one of the
31a70 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 [limit categorie
31a80 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 s] that define a
31a90 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e .** class of con
31aa0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 structs to be si
31ab0 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 ze limited. The
31ac0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 third parameter
31ad0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c is the.** new l
31ae0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f imit for that co
31af0 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a nstruct.)^.**.**
31b00 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d ^If the new lim
31b10 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 it is a negative
31b20 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d number, the lim
31b30 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e it is unchanged.
31b40 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c .** ^(For each l
31b50 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 imit category SQ
31b60 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 LITE_LIMIT_<i>NA
31b70 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 ME</i> there is
31b80 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 a .** [limits |
31b90 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 hard upper bound
31ba0 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 ].** set at comp
31bb0 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 ile-time by a C
31bc0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 preprocessor mac
31bd0 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 ro called.** [li
31be0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 mits | SQLITE_MA
31bf0 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a X_<i>NAME</i>]..
31c00 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f ** (The "_LIMIT_
31c10 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 " in the name is
31c20 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 changed to "_MA
31c30 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 X_".))^.** ^Atte
31c40 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 mpts to increase
31c50 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 a limit above i
31c60 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f ts hard upper bo
31c70 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e und are.** silen
31c80 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f tly truncated to
31c90 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 the hard upper
31ca0 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 bound..**.** ^Re
31cb0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 gardless of whet
31cc0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c her or not the l
31cd0 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 imit was changed
31ce0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 , the .** [sqlit
31cf0 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 e3_limit()] inte
31d00 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 rface returns th
31d10 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 e prior value of
31d20 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e the limit..** ^
31d30 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 Hence, to find t
31d40 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 he current value
31d50 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 of a limit with
31d60 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c out changing it,
31d70 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b .** simply invok
31d80 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 e this interface
31d90 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 with the third
31da0 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f parameter set to
31db0 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 -1..**.** Run-t
31dc0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 ime limits are i
31dd0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 ntended for use
31de0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 in applications
31df0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 that manage.** b
31e00 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e oth their own in
31e10 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 ternal database
31e20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 and also databas
31e30 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 es that are cont
31e40 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 rolled.** by unt
31e50 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 rusted external
31e60 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 sources. An exa
31e70 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e mple application
31e80 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 might be a.** w
31e90 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 eb browser that
31ea0 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 has its own data
31eb0 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e bases for storin
31ec0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a g history and.**
31ed0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 separate databa
31ee0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 ses controlled b
31ef0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 y JavaScript app
31f00 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f lications downlo
31f10 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 aded.** off the
31f20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 Internet. The i
31f30 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 nternal database
31f40 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 s can be given t
31f50 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 he.** large, def
31f60 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 ault limits. Da
31f70 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 tabases managed
31f80 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 by external sour
31f90 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 ces can.** be gi
31fa0 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 ven much smaller
31fb0 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 limits designed
31fc0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 to prevent a de
31fd0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a nial of service.
31fe0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 ** attack. Deve
31ff0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 lopers might als
32000 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 o want to use th
32010 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 e [sqlite3_set_a
32020 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 uthorizer()].**
32030 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 interface to fur
32040 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 ther control unt
32050 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 rusted SQL. The
32060 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 size of the dat
32070 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 abase.** created
32080 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 by an untrusted
32090 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 script can be c
320a0 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 ontained using t
320b0 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f he.** [max_page_
320c0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e count] [PRAGMA].
320d0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 .**.** New run-t
320e0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f ime limit catego
320f0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 ries may be adde
32100 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 d in future rele
32110 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f ases..*/.SQLITE_
32120 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
32130 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 limit(sqlite3*,
32140 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 int id, int newV
32150 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 al);../*.** CAPI
32160 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 3REF: Run-Time L
32170 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a imit Categories.
32180 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 ** KEYWORDS: {li
32190 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a mit category} {*
321a0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 limit categories
321b0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f }.**.** These co
321c0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 nstants define v
321d0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e arious performan
321e0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 ce limits.** tha
321f0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 t can be lowered
32200 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 at run-time usi
32210 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 ng [sqlite3_limi
32220 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e t()]..** The syn
32230 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 opsis of the mea
32240 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 nings of the var
32250 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 ious limits is s
32260 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 hown below..** A
32270 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d dditional inform
32280 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 ation is availab
32290 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 le at [limits |
322a0 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 Limits in SQLite
322b0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a ]..**.** <dl>.**
322c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f [[SQLITE_LIMIT_
322d0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 LENGTH]] ^(<dt>S
322e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 QLITE_LIMIT_LENG
322f0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 TH</dt>.** <dd>T
32300 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 he maximum size
32310 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 of any string or
32320 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 BLOB or table r
32330 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 ow, in bytes.<dd
32340 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
32350 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
32360 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 GTH]] ^(<dt>SQLI
32370 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e TE_LIMIT_SQL_LEN
32380 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e GTH</dt>.** <dd>
32390 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 The maximum leng
323a0 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 th of an SQL sta
323b0 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 tement, in bytes
323c0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
323d0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f [SQLITE_LIMIT_CO
323e0 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c LUMN]] ^(<dt>SQL
323f0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e ITE_LIMIT_COLUMN
32400 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
32410 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
32420 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 of columns in a
32430 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e table definition
32440 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 or in the.** re
32450 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 sult set of a [S
32460 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 ELECT] or the ma
32470 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
32480 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e columns in an in
32490 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 dex.** or in an
324a0 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 ORDER BY or GROU
324b0 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 P BY clause.</dd
324c0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 >)^.**.** [[SQLI
324d0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 TE_LIMIT_EXPR_DE
324e0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 PTH]] ^(<dt>SQLI
324f0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 TE_LIMIT_EXPR_DE
32500 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e PTH</dt>.** <dd>
32510 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 The maximum dept
32520 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 h of the parse t
32530 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 ree on any expre
32540 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ssion.</dd>)^.**
32550 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
32560 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 IT_COMPOUND_SELE
32570 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 CT]] ^(<dt>SQLIT
32580 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 E_LIMIT_COMPOUND
32590 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 _SELECT</dt>.**
325a0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
325b0 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 number of terms
325c0 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 in a compound SE
325d0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c LECT statement.<
325e0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
325f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 QLITE_LIMIT_VDBE
32600 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 _OP]] ^(<dt>SQLI
32610 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 TE_LIMIT_VDBE_OP
32620 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
32630 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
32640 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 of instructions
32650 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 in a virtual mac
32660 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 hine program.**
32670 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e used to implemen
32680 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 t an SQL stateme
32690 6e 74 2e 20 20 49 66 20 5b 73 71 6c 69 74 65 33 nt. If [sqlite3
326a0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f _prepare_v2()] o
326b0 72 0a 2a 2a 20 74 68 65 20 65 71 75 69 76 61 6c r.** the equival
326c0 65 6e 74 20 74 72 69 65 73 20 74 6f 20 61 6c 6c ent tries to all
326d0 6f 63 61 74 65 20 73 70 61 63 65 20 66 6f 72 20 ocate space for
326e0 6d 6f 72 65 20 74 68 61 6e 20 74 68 69 73 20 6d more than this m
326f0 61 6e 79 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 69 any opcodes.** i
32700 6e 20 61 20 73 69 6e 67 6c 65 20 70 72 65 70 61 n a single prepa
32710 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 61 red statement, a
32720 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 65 n SQLITE_NOMEM e
32730 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 rror is returned
32740 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b .</dd>)^.**.** [
32750 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 [SQLITE_LIMIT_FU
32760 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c NCTION_ARG]] ^(<
32770 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
32780 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 FUNCTION_ARG</dt
32790 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
327a0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 imum number of a
327b0 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 rguments on a fu
327c0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a nction.</dd>)^.*
327d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 *.** [[SQLITE_LI
327e0 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e MIT_ATTACHED]] ^
327f0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
32800 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a T_ATTACHED</dt>.
32810 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d ** <dd>The maxim
32820 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 um number of [AT
32830 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 TACH | attached
32840 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 databases].)^</d
32850 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 d>.**.** [[SQLIT
32860 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 E_LIMIT_LIKE_PAT
32870 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a TERN_LENGTH]].**
32880 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 ^(<dt>SQLITE_LI
32890 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e MIT_LIKE_PATTERN
328a0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 _LENGTH</dt>.**
328b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 <dd>The maximum
328c0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 length of the pa
328d0 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 ttern argument t
328e0 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a o the [LIKE] or.
328f0 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 ** [GLOB] operat
32900 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ors.</dd>)^.**.*
32910 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
32920 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 _VARIABLE_NUMBER
32930 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 ]].** ^(<dt>SQLI
32940 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c TE_LIMIT_VARIABL
32950 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a E_NUMBER</dt>.**
32960 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d <dd>The maximum
32970 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 index number of
32980 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d any [parameter]
32990 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 in an SQL state
329a0 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b ment.)^.**.** [[
329b0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 SQLITE_LIMIT_TRI
329c0 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c GGER_DEPTH]] ^(<
329d0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
329e0 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 TRIGGER_DEPTH</d
329f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 t>.** <dd>The ma
32a00 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 ximum depth of r
32a10 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 ecursion for tri
32a20 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a ggers.</dd>)^.**
32a30 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d .** [[SQLITE_LIM
32a40 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 IT_WORKER_THREAD
32a50 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 S]] ^(<dt>SQLITE
32a60 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 _LIMIT_WORKER_TH
32a70 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 READS</dt>.** <d
32a80 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
32a90 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 mber of auxiliar
32aa0 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 y worker threads
32ab0 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a that a single.*
32ac0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
32ad0 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 ement] may start
32ae0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c .</dd>)^.** </dl
32af0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c >.*/.#define SQL
32b00 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
32b10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
32b20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 0.#define SQ
32b30 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c LITE_LIMIT_SQL_L
32b40 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 ENGTH
32b50 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 1.#define S
32b60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 QLITE_LIMIT_COLU
32b70 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 MN
32b80 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
32b90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 SQLITE_LIMIT_EXP
32ba0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 R_DEPTH
32bb0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 3.#define
32bc0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f SQLITE_LIMIT_CO
32bd0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 MPOUND_SELECT
32be0 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 4.#defin
32bf0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 e SQLITE_LIMIT_V
32c00 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 DBE_OP
32c10 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 5.#defi
32c20 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f ne SQLITE_LIMIT_
32c30 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 FUNCTION_ARG
32c40 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 6.#def
32c50 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 ine SQLITE_LIMIT
32c60 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 _ATTACHED
32c70 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 7.#de
32c80 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 fine SQLITE_LIMI
32c90 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c T_LIKE_PATTERN_L
32ca0 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 ENGTH 8.#d
32cb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
32cc0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
32cd0 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 ER 9.#
32ce0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
32cf0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 MIT_TRIGGER_DEPT
32d00 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a H 10.
32d10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
32d20 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 IMIT_WORKER_THRE
32d30 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 ADS 11
32d40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
32d50 3a 20 50 72 65 70 61 72 65 20 46 6c 61 67 73 0a : Prepare Flags.
32d60 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 **.** These cons
32d70 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 tants define var
32d80 69 6f 75 73 20 66 6c 61 67 73 20 74 68 61 74 20 ious flags that
32d90 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 69 6e can be passed in
32da0 74 6f 0a 2a 2a 20 22 70 72 65 70 46 6c 61 67 73 to.** "prepFlags
32db0 22 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 " parameter of t
32dc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 he [sqlite3_prep
32dd0 61 72 65 5f 76 33 28 29 5d 20 61 6e 64 0a 2a 2a are_v3()] and.**
32de0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
32df0 65 31 36 5f 76 33 28 29 5d 20 69 6e 74 65 72 66 e16_v3()] interf
32e00 61 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 aces..**.** New
32e10 66 6c 61 67 73 20 6d 61 79 20 62 65 20 61 64 64 flags may be add
32e20 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c ed in future rel
32e30 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e eases of SQLite.
32e40 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b .**.** <dl>.** [
32e50 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f [SQLITE_PREPARE_
32e60 50 45 52 53 49 53 54 45 4e 54 5d 5d 20 5e 28 3c PERSISTENT]] ^(<
32e70 64 74 3e 53 51 4c 49 54 45 5f 50 52 45 50 41 52 dt>SQLITE_PREPAR
32e80 45 5f 50 45 52 53 49 53 54 45 4e 54 3c 2f 64 74 E_PERSISTENT</dt
32e90 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 53 51 4c >.** <dd>The SQL
32ea0 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 ITE_PREPARE_PERS
32eb0 49 53 54 45 4e 54 20 66 6c 61 67 20 69 73 20 61 ISTENT flag is a
32ec0 20 68 69 6e 74 20 74 6f 20 74 68 65 20 71 75 65 hint to the que
32ed0 72 79 20 70 6c 61 6e 6e 65 72 0a 2a 2a 20 74 68 ry planner.** th
32ee0 61 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 at the prepared
32ef0 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 statement will b
32f00 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 61 e retained for a
32f10 20 6c 6f 6e 67 20 74 69 6d 65 20 61 6e 64 0a 2a long time and.*
32f20 2a 20 70 72 6f 62 61 62 6c 79 20 72 65 75 73 65 * probably reuse
32f30 64 20 6d 61 6e 79 20 74 69 6d 65 73 2e 29 5e 20 d many times.)^
32f40 5e 57 69 74 68 6f 75 74 20 74 68 69 73 20 66 6c ^Without this fl
32f50 61 67 2c 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 ag, [sqlite3_pre
32f60 70 61 72 65 5f 76 33 28 29 5d 0a 2a 2a 20 61 6e pare_v3()].** an
32f70 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 d [sqlite3_prepa
32f80 72 65 31 36 5f 76 33 28 29 5d 20 61 73 73 75 6d re16_v3()] assum
32f90 65 20 74 68 61 74 20 74 68 65 20 70 72 65 70 61 e that the prepa
32fa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 77 69 red statement wi
32fb0 6c 6c 20 0a 2a 2a 20 62 65 20 75 73 65 64 20 6a ll .** be used j
32fc0 75 73 74 20 6f 6e 63 65 20 6f 72 20 61 74 20 6d ust once or at m
32fd0 6f 73 74 20 61 20 66 65 77 20 74 69 6d 65 73 20 ost a few times
32fe0 61 6e 64 20 74 68 65 6e 20 64 65 73 74 72 6f 79 and then destroy
32ff0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c ed using.** [sql
33000 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d ite3_finalize()]
33010 20 72 65 6c 61 74 69 76 65 6c 79 20 73 6f 6f 6e relatively soon
33020 2e 20 54 68 65 20 63 75 72 72 65 6e 74 20 69 6d . The current im
33030 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 63 74 plementation act
33040 73 0a 2a 2a 20 6f 6e 20 74 68 69 73 20 68 69 6e s.** on this hin
33050 74 20 62 79 20 61 76 6f 69 64 69 6e 67 20 74 68 t by avoiding th
33060 65 20 75 73 65 20 6f 66 20 5b 6c 6f 6f 6b 61 73 e use of [lookas
33070 69 64 65 20 6d 65 6d 6f 72 79 5d 20 73 6f 20 61 ide memory] so a
33080 73 20 6e 6f 74 20 74 6f 0a 2a 2a 20 64 65 70 6c s not to.** depl
33090 65 74 65 20 74 68 65 20 6c 69 6d 69 74 65 64 20 ete the limited
330a0 73 74 6f 72 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 store of lookasi
330b0 64 65 20 6d 65 6d 6f 72 79 2e 20 46 75 74 75 72 de memory. Futur
330c0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 0a 2a 2a e versions of.**
330d0 20 53 51 4c 69 74 65 20 6d 61 79 20 61 63 74 20 SQLite may act
330e0 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 64 69 66 on this hint dif
330f0 66 65 72 65 6e 74 6c 79 2e 0a 2a 2a 20 3c 2f 64 ferently..** </d
33100 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 l>.*/.#define SQ
33110 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 LITE_PREPARE_PER
33120 53 49 53 54 45 4e 54 20 20 20 20 20 20 20 20 20 SISTENT
33130 20 20 20 20 20 30 78 30 31 0a 0a 2f 2a 0a 2a 2a 0x01../*.**
33140 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 CAPI3REF: Compi
33150 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 ling An SQL Stat
33160 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 ement.** KEYWORD
33170 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e S: {SQL statemen
33180 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d t compiler}.** M
33190 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
331a0 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 * CONSTRUCTOR: s
331b0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
331c0 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 * To execute an
331d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 SQL statement, i
331e0 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 t must first be
331f0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 compiled into a
33200 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f byte-code.** pro
33210 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f gram using one o
33220 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 f these routines
33230 2e 20 20 4f 72 2c 20 69 6e 20 6f 74 68 65 72 20 . Or, in other
33240 77 6f 72 64 73 2c 20 74 68 65 73 65 20 72 6f 75 words, these rou
33250 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 63 6f 6e tines.** are con
33260 73 74 72 75 63 74 6f 72 73 20 66 6f 72 20 74 68 structors for th
33270 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
33280 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 2e 0a 2a ement] object..*
33290 2a 0a 2a 2a 20 54 68 65 20 70 72 65 66 65 72 72 *.** The preferr
332a0 65 64 20 72 6f 75 74 69 6e 65 20 74 6f 20 75 73 ed routine to us
332b0 65 20 69 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 e is [sqlite3_pr
332c0 65 70 61 72 65 5f 76 32 28 29 5d 2e 20 20 54 68 epare_v2()]. Th
332d0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 e.** [sqlite3_pr
332e0 65 70 61 72 65 28 29 5d 20 69 6e 74 65 72 66 61 epare()] interfa
332f0 63 65 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64 ce is legacy and
33300 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 should be avoid
33310 65 64 2e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ed..** [sqlite3_
33320 70 72 65 70 61 72 65 5f 76 33 28 29 5d 20 68 61 prepare_v3()] ha
33330 73 20 61 6e 20 65 78 74 72 61 20 22 70 72 65 70 s an extra "prep
33340 46 6c 61 67 73 22 20 6f 70 74 69 6f 6e 20 74 68 Flags" option th
33350 61 74 20 69 73 20 75 73 65 64 0a 2a 2a 20 66 6f at is used.** fo
33360 72 20 73 70 65 63 69 61 6c 20 70 75 72 70 6f 73 r special purpos
33370 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 73 es..**.** The us
33380 65 20 6f 66 20 74 68 65 20 55 54 46 2d 38 20 69 e of the UTF-8 i
33390 6e 74 65 72 66 61 63 65 73 20 69 73 20 70 72 65 nterfaces is pre
333a0 66 65 72 72 65 64 2c 20 61 73 20 53 51 4c 69 74 ferred, as SQLit
333b0 65 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 64 e currently.** d
333c0 6f 65 73 20 61 6c 6c 20 70 61 72 73 69 6e 67 20 oes all parsing
333d0 75 73 69 6e 67 20 55 54 46 2d 38 2e 20 20 54 68 using UTF-8. Th
333e0 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 66 61 e UTF-16 interfa
333f0 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 ces are provided
33400 0a 2a 2a 20 61 73 20 61 20 63 6f 6e 76 65 6e 69 .** as a conveni
33410 65 6e 63 65 2e 20 20 54 68 65 20 55 54 46 2d 31 ence. The UTF-1
33420 36 20 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6 interfaces wor
33430 6b 20 62 79 20 63 6f 6e 76 65 72 74 69 6e 67 20 k by converting
33440 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 74 65 78 the.** input tex
33450 74 20 69 6e 74 6f 20 55 54 46 2d 38 2c 20 74 68 t into UTF-8, th
33460 65 6e 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 en invoking the
33470 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 55 54 corresponding UT
33480 46 2d 38 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a F-8 interface..*
33490 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 *.** The first a
334a0 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 rgument, "db", i
334b0 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f s a [database co
334c0 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e nnection] obtain
334d0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 ed from a.** pri
334e0 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 or successful ca
334f0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f ll to [sqlite3_o
33500 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 pen()], [sqlite3
33510 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a _open_v2()] or.*
33520 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 * [sqlite3_open1
33530 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 6()]. The datab
33540 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d ase connection m
33550 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 ust not have bee
33560 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 n closed..**.**
33570 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d The second argum
33580 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 ent, "zSql", is
33590 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f the statement to
335a0 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e be compiled, en
335b0 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 coded.** as eith
335c0 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d er UTF-8 or UTF-
335d0 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 16. The sqlite3
335e0 5f 70 72 65 70 61 72 65 28 29 2c 20 73 71 6c 69 _prepare(), sqli
335f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
33600 2c 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 ,.** and sqlite3
33610 5f 70 72 65 70 61 72 65 5f 76 33 28 29 0a 2a 2a _prepare_v3().**
33620 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 interfaces use
33630 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 UTF-8, and sqlit
33640 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 2c 20 e3_prepare16(),
33650 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
33660 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 6_v2(),.** and s
33670 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
33680 5f 76 33 28 29 20 75 73 65 20 55 54 46 2d 31 36 _v3() use UTF-16
33690 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 ..**.** ^If the
336a0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 nByte argument i
336b0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
336c0 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 zSql is read up
336d0 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 to the.** first
336e0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 zero terminator
336f0 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 . ^If nByte is p
33700 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 ositive, then it
33710 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 is the.** numbe
33720 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 r of bytes read
33730 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 from zSql. ^If
33740 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 nByte is zero, t
33750 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a hen no prepared.
33760 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ** statement is
33770 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 generated..** If
33780 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 the caller know
33790 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c s that the suppl
337a0 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 ied string is nu
337b0 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 l-terminated, th
337c0 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 en.** there is a
337d0 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e small performan
337e0 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 ce advantage to
337f0 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 passing an nByte
33800 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a parameter that.
33810 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 ** is the number
33820 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
33830 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 input string <i
33840 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a >including</i>.*
33850 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e * the nul-termin
33860 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 ator..**.** ^If
33870 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 pzTail is not NU
33880 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 LL then *pzTail
33890 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 is made to point
338a0 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 to the first by
338b0 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 te.** past the e
338c0 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 nd of the first
338d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e SQL statement in
338e0 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f zSql. These ro
338f0 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 utines only.** c
33900 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 ompile the first
33910 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 statement in zS
33920 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 ql, so *pzTail i
33930 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 s left pointing
33940 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 to.** what remai
33950 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a ns uncompiled..*
33960 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 *.** ^*ppStmt is
33970 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 left pointing t
33980 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 o a compiled [pr
33990 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
339a0 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a ] that can be.**
339b0 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 executed using
339c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
339d0 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 . ^If there is
339e0 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d an error, *ppStm
339f0 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e t is set.** to N
33a00 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e ULL. ^If the in
33a10 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e put text contain
33a20 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 s no SQL (if the
33a30 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 input is an emp
33a40 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 ty.** string or
33a50 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 a comment) then
33a60 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 *ppStmt is set t
33a70 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 o NULL..** The c
33a80 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 alling procedure
33a90 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 is responsible
33aa0 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 for deleting the
33ab0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c compiled.** SQL
33ac0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 statement using
33ad0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 [sqlite3_finali
33ae0 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 ze()] after it h
33af0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 as finished with
33b00 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d it..** ppStmt m
33b10 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a ay not be NULL..
33b20 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 **.** ^On succes
33b30 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 s, the sqlite3_p
33b40 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 repare() family
33b50 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 of routines retu
33b60 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a rn [SQLITE_OK];.
33b70 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 ** otherwise an
33b80 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 [error code] is
33b90 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 returned..**.**
33ba0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 The sqlite3_prep
33bb0 61 72 65 5f 76 32 28 29 2c 20 73 71 6c 69 74 65 are_v2(), sqlite
33bc0 33 5f 70 72 65 70 61 72 65 5f 76 33 28 29 2c 20 3_prepare_v3(),
33bd0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
33be0 36 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e 64 20 73 6_v2(),.** and s
33bf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
33c00 5f 76 33 28 29 20 69 6e 74 65 72 66 61 63 65 73 _v3() interfaces
33c10 20 61 72 65 20 72 65 63 6f 6d 6d 65 6e 64 65 64 are recommended
33c20 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f for all new pro
33c30 67 72 61 6d 73 2e 0a 2a 2a 20 54 68 65 20 6f 6c grams..** The ol
33c40 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 der interfaces (
33c50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
33c60 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 ) and sqlite3_pr
33c70 65 70 61 72 65 31 36 28 29 29 0a 2a 2a 20 61 72 epare16()).** ar
33c80 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 e retained for b
33c90 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
33ca0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 bility, but thei
33cb0 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 r use is discour
33cc0 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 aged..** ^In the
33cd0 20 22 76 58 22 20 69 6e 74 65 72 66 61 63 65 73 "vX" interfaces
33ce0 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 , the prepared s
33cf0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 tatement.** that
33d00 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 is returned (th
33d10 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d e [sqlite3_stmt]
33d20 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e object) contain
33d30 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a s a copy of the.
33d40 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 ** original SQL
33d50 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 text. This cause
33d60 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 s the [sqlite3_s
33d70 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 tep()] interface
33d80 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 to.** behave di
33d90 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 fferently in thr
33da0 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c ee ways:.**.** <
33db0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e ol>.** <li>.** ^
33dc0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 If the database
33dd0 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 schema changes,
33de0 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 instead of retur
33df0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 ning [SQLITE_SCH
33e00 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c EMA] as it.** al
33e10 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c ways used to do,
33e20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
33e30 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 ] will automatic
33e40 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 ally recompile t
33e50 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d he SQL.** statem
33e60 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 ent and try to r
33e70 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 un it again. As
33e80 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f many as [SQLITE_
33e90 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 MAX_SCHEMA_RETRY
33ea0 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c ].** retries wil
33eb0 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 l occur before s
33ec0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 qlite3_step() gi
33ed0 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 ves up and retur
33ee0 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 ns an error..**
33ef0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e </li>.**.** <li>
33f00 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 .** ^When an err
33f10 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 or occurs, [sqli
33f20 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c te3_step()] will
33f30 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 return one of t
33f40 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b he detailed.** [
33f50 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 error codes] or
33f60 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 [extended error
33f70 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 codes]. ^The le
33f80 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 gacy behavior wa
33f90 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 s that.** [sqlit
33fa0 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 e3_step()] would
33fb0 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 only return a g
33fc0 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 eneric [SQLITE_E
33fd0 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 RROR] result cod
33fe0 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 e.** and the app
33ff0 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 lication would h
34000 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 ave to make a se
34010 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 cond call to [sq
34020 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a lite3_reset()].*
34030 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 * in order to fi
34040 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e nd the underlyin
34050 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 g cause of the p
34060 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 roblem. With the
34070 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a "v2" prepare.**
34080 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 interfaces, the
34090 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 underlying reas
340a0 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 on for the error
340b0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d is returned imm
340c0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c ediately..** </l
340d0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a i>.**.** <li>.**
340e0 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69 ^If the specifi
340f0 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f c value bound to
34100 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f [parameter | ho
34110 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e st parameter] in
34120 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 the .** WHERE c
34130 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c lause might infl
34140 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 uence the choice
34150 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 of query plan f
34160 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a or a statement,.
34170 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 ** then the stat
34180 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 ement will be au
34190 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f tomatically reco
341a0 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 mpiled, as if th
341b0 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a ere had been .**
341c0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 a schema change
341d0 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 , on the first
341e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d [sqlite3_step()]
341f0 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 call following
34200 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f any change.** to
34210 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 the [sqlite3_bi
34220 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e nd_text | bindin
34230 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 gs] of that [par
34240 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 ameter]. .** ^Th
34250 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 e specific value
34260 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 of WHERE-clause
34270 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 [parameter] mig
34280 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 ht influence the
34290 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 .** choice of q
342a0 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 uery plan if the
342b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 parameter is th
342c0 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 e left-hand side
342d0 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 of a [LIKE].**
342e0 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 or [GLOB] operat
342f0 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 or or if the par
34300 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 ameter is compar
34310 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 ed to an indexed
34320 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 column.** and t
34330 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c he [SQLITE_ENABL
34340 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 E_STAT3] compile
34350 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 -time option is
34360 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 enabled..** </li
34370 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a >.** </ol>.**.**
34380 20 3c 70 3e 5e 73 71 6c 69 74 65 33 5f 70 72 65 <p>^sqlite3_pre
34390 70 61 72 65 5f 76 33 28 29 20 64 69 66 66 65 72 pare_v3() differ
343a0 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 70 s from sqlite3_p
343b0 72 65 70 61 72 65 5f 76 32 28 29 20 6f 6e 6c 79 repare_v2() only
343c0 20 69 6e 20 68 61 76 69 6e 67 0a 2a 2a 20 74 68 in having.** th
343d0 65 20 65 78 74 72 61 20 70 72 65 70 46 6c 61 67 e extra prepFlag
343e0 73 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 s parameter, whi
343f0 63 68 20 69 73 20 61 20 62 69 74 20 61 72 72 61 ch is a bit arra
34400 79 20 63 6f 6e 73 69 73 74 69 6e 67 20 6f 66 20 y consisting of
34410 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 zero or.** more
34420 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 50 of the [SQLITE_P
34430 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e REPARE_PERSISTEN
34440 54 7c 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 T|SQLITE_PREPARE
34450 5f 2a 5d 20 66 6c 61 67 73 2e 20 20 5e 54 68 65 _*] flags. ^The
34460 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 .** sqlite3_prep
34470 61 72 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 are_v2() interfa
34480 63 65 20 77 6f 72 6b 73 20 65 78 61 63 74 6c 79 ce works exactly
34490 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 the same as.**
344a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
344b0 76 33 28 29 20 77 69 74 68 20 61 20 7a 65 72 6f v3() with a zero
344c0 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d prepFlags param
344d0 65 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f eter..*/.SQLITE_
344e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
344f0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 prepare(. sqlit
34500 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 e3 *db,
34510 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 /* Database h
34520 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 andle */. const
34530 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 char *zSql,
34540 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d /* SQL statem
34550 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 ent, UTF-8 encod
34560 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 ed */. int nByt
34570 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 e,
34580 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 /* Maximum lengt
34590 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 h of zSql in byt
345a0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 es. */. sqlite3
345b0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 _stmt **ppStmt,
345c0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 /* OUT: Stateme
345d0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 nt handle */. c
345e0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 onst char **pzTa
345f0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 il /* OUT: P
34600 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 ointer to unused
34610 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c portion of zSql
34620 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 */.);.SQLITE_AP
34630 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 I int sqlite3_pr
34640 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 epare_v2(. sqli
34650 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 te3 *db,
34660 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 /* Database
34670 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 handle */. cons
34680 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 t char *zSql,
34690 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 /* SQL state
346a0 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f ment, UTF-8 enco
346b0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 ded */. int nBy
346c0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 te,
346d0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 /* Maximum leng
346e0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 th of zSql in by
346f0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 tes. */. sqlite
34700 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
34710 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
34720 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
34730 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 const char **pzT
34740 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
34750 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
34760 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
34770 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 l */.);.SQLITE_A
34780 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 PI int sqlite3_p
34790 72 65 70 61 72 65 5f 76 33 28 0a 20 20 73 71 6c repare_v3(. sql
347a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
347b0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
347c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
347d0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 st char *zSql,
347e0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
347f0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 ement, UTF-8 enc
34800 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 oded */. int nB
34810 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 yte,
34820 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e /* Maximum len
34830 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 gth of zSql in b
34840 79 74 65 73 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 ytes. */. unsig
34850 6e 65 64 20 69 6e 74 20 70 72 65 70 46 6c 61 67 ned int prepFlag
34860 73 2c 20 2f 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f s, /* Zero or mo
34870 72 65 20 53 51 4c 49 54 45 5f 50 52 45 50 41 52 re SQLITE_PREPAR
34880 45 5f 20 66 6c 61 67 73 20 2a 2f 0a 20 20 73 71 E_ flags */. sq
34890 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 lite3_stmt **ppS
348a0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 tmt, /* OUT: St
348b0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a atement handle *
348c0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
348d0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f *pzTail /* O
348e0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 UT: Pointer to u
348f0 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 nused portion of
34900 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 zSql */.);.SQLI
34910 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
34920 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 e3_prepare16(.
34930 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 sqlite3 *db,
34940 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 /* Datab
34950 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ase handle */.
34960 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c const void *zSql
34970 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 , /* SQL s
34980 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 tatement, UTF-16
34990 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e encoded */. in
349a0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 t nByte,
349b0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d /* Maximum
349c0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 length of zSql
349d0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 in bytes. */. s
349e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 qlite3_stmt **pp
349f0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 Stmt, /* OUT: S
34a00 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 tatement handle
34a10 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 */. const void
34a20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 **pzTail /*
34a30 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 OUT: Pointer to
34a40 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f unused portion o
34a50 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c f zSql */.);.SQL
34a60 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
34a70 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
34a80 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
34a90 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
34aa0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
34ab0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a /. const void *
34ac0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
34ad0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
34ae0 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a F-16 encoded */.
34af0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
34b00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
34b10 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
34b20 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
34b30 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
34b40 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
34b50 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
34b60 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
34b70 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 oid **pzTail
34b80 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
34b90 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
34ba0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
34bb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
34bc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 sqlite3_prepare1
34bd0 36 5f 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 6_v3(. sqlite3
34be0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 *db,
34bf0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 /* Database hand
34c00 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f le */. const vo
34c10 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 id *zSql,
34c20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 /* SQL statement
34c30 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 , UTF-16 encoded
34c40 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c */. int nByte,
34c50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
34c60 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 Maximum length
34c70 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 of zSql in bytes
34c80 2e 20 2a 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 . */. unsigned
34c90 69 6e 74 20 70 72 65 70 46 6c 61 67 73 2c 20 2f int prepFlags, /
34ca0 2a 20 5a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 * Zero or more S
34cb0 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f 20 66 QLITE_PREPARE_ f
34cc0 6c 61 67 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 lags */. sqlite
34cd0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 3_stmt **ppStmt,
34ce0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d /* OUT: Statem
34cf0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 ent handle */.
34d00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 const void **pzT
34d10 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 ail /* OUT:
34d20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 Pointer to unuse
34d30 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 d portion of zSq
34d40 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 l */.);../*.** C
34d50 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 API3REF: Retriev
34d60 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 ing Statement SQ
34d70 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c L.** METHOD: sql
34d80 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
34d90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c ^The sqlite3_sql
34da0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 (P) interface re
34db0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
34dc0 74 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 to a copy of the
34dd0 20 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 UTF-8.** SQL te
34de0 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 xt used to creat
34df0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 e [prepared stat
34e00 65 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 ement] P if P wa
34e10 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 s.** created by
34e20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
34e30 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 _v2()], [sqlite3
34e40 5f 70 72 65 70 61 72 65 5f 76 33 28 29 5d 2c 0a _prepare_v3()],.
34e50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
34e60 61 72 65 31 36 5f 76 32 28 29 5d 2c 20 6f 72 20 are16_v2()], or
34e70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
34e80 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a 20 5e 54 68 16_v3()]..** ^Th
34e90 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 e sqlite3_expand
34ea0 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 ed_sql(P) interf
34eb0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f ace returns a po
34ec0 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 inter to a UTF-8
34ed0 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 .** string conta
34ee0 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 ining the SQL te
34ef0 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 xt of prepared s
34f00 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a tatement P with.
34f10 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 ** [bound parame
34f20 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a ters] expanded..
34f30 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d **.** ^(For exam
34f40 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 ple, if a prepar
34f50 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ed statement is
34f60 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 created using th
34f70 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 e SQL.** text "S
34f80 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 ELECT $abc,:xyz"
34f90 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 and if paramete
34fa0 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 r $abc is bound
34fb0 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a to integer 2345.
34fc0 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 ** and parameter
34fd0 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 :xyz is unbound
34fe0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 , then sqlite3_s
34ff0 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e ql() will return
35000 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c .** the original
35010 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 string, "SELECT
35020 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 $abc,:xyz" but
35030 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 sqlite3_expanded
35040 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 _sql().** will r
35050 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 eturn "SELECT 23
35060 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 45,NULL".)^.**.*
35070 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 * ^The sqlite3_e
35080 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e xpanded_sql() in
35090 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 terface returns
350a0 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 NULL if insuffic
350b0 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 ient memory.** i
350c0 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 s available to h
350d0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 old the result,
350e0 6f 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 or if the result
350f0 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 would exceed th
35100 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d e.** the maximum
35110 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 string length d
35120 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 etermined by the
35130 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c [SQLITE_LIMIT_L
35140 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 ENGTH]..**.** ^T
35150 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 he [SQLITE_TRACE
35160 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d _SIZE_LIMIT] com
35170 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
35180 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 limits the size
35190 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 of.** bound par
351a0 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e ameter expansion
351b0 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 s. ^The [SQLITE
351c0 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d _OMIT_TRACE] com
351d0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 pile-time.** opt
351e0 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 ion causes sqlit
351f0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 e3_expanded_sql(
35200 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 ) to always retu
35210 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e rn NULL..**.** ^
35220 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 The string retur
35230 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 ned by sqlite3_s
35240 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64 ql(P) is managed
35250 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69 by SQLite and i
35260 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c s.** automatical
35270 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 ly freed when th
35280 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 e prepared state
35290 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 ment is finalize
352a0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e d..** ^The strin
352b0 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 g returned by sq
352c0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 lite3_expanded_s
352d0 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 ql(P), on the ot
352e0 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 her hand,.** is
352f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 obtained from [s
35300 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d qlite3_malloc()]
35310 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 and must be fre
35320 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 e by the applica
35330 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 tion.** by passi
35340 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 ng it to [sqlite
35350 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 53 51 3_free()]..*/.SQ
35360 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 LITE_API const c
35370 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c har *sqlite3_sql
35380 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 (sqlite3_stmt *p
35390 53 74 6d 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 Stmt);.SQLITE_AP
353a0 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f I char *sqlite3_
353b0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c expanded_sql(sql
353c0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 ite3_stmt *pStmt
353d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
353e0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 EF: Determine If
353f0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e An SQL Statemen
35400 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 t Writes The Dat
35410 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a abase.** METHOD:
35420 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
35430 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
35440 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 _stmt_readonly(X
35450 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
35460 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 rns true (non-ze
35470 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e ro) if.** and on
35480 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 ly if the [prepa
35490 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 red statement] X
354a0 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 makes no direct
354b0 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 changes to.** t
354c0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 he content of th
354d0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e e database file.
354e0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 .**.** Note that
354f0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 [application-de
35500 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 fined SQL functi
35510 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 ons] or.** [virt
35520 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 ual tables] migh
35530 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 t change the dat
35540 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 abase indirectly
35550 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 as a side effec
35560 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 t. .** ^(For ex
35570 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 ample, if an app
35580 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 lication defines
35590 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 a function "eva
355a0 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 l()" that .** ca
355b0 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 lls [sqlite3_exe
355c0 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 c()], then the f
355d0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 ollowing SQL sta
355e0 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 tement would.**
355f0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 change the datab
35600 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 ase file through
35610 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a side-effects:.*
35620 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 *.** <blockquote
35630 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c ><pre>.** SEL
35640 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 ECT eval('DELETE
35650 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 FROM t1') FROM
35660 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 t2;.** </pre></b
35670 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
35680 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 But because the
35690 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d [SELECT] statem
356a0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 ent does not cha
356b0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 nge the database
356c0 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c file.** directl
356d0 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f y, sqlite3_stmt_
356e0 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 readonly() would
356f0 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 still return tr
35700 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 ue.)^.**.** ^Tra
35710 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c nsaction control
35720 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 statements such
35730 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f as [BEGIN], [CO
35740 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b MMIT], [ROLLBACK
35750 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 ],.** [SAVEPOINT
35760 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d ], and [RELEASE]
35770 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 cause sqlite3_s
35780 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 tmt_readonly() t
35790 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a o return true,.*
357a0 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 * since the stat
357b0 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 ements themselve
357c0 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c s do not actuall
357d0 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 y modify the dat
357e0 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 abase but.** rat
357f0 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c her they control
35800 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 the timing of w
35810 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d hen other statem
35820 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 ents modify the
35830 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e .** database. ^
35840 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 The [ATTACH] and
35850 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d [DETACH] statem
35860 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a ents also cause.
35870 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f ** sqlite3_stmt_
35880 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 readonly() to re
35890 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c turn true since,
358a0 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 while those sta
358b0 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 tements.** chang
358c0 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 e the configurat
358d0 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 ion of a databas
358e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 e connection, th
358f0 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a ey do not make .
35900 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 ** changes to th
35910 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 e content of the
35920 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 database files
35930 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65 on disk..** ^The
35940 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
35950 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61 adonly() interfa
35960 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 ce returns true
35970 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63 for [BEGIN] sinc
35980 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72 e.** [BEGIN] mer
35990 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61 ely sets interna
359a0 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65 l flags, but the
359b0 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d [BEGIN|BEGIN IM
359c0 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20 MEDIATE] and.**
359d0 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43 [BEGIN|BEGIN EXC
359e0 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73 LUSIVE] commands
359f0 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61 do touch the da
35a00 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a tabase and so.**
35a10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 sqlite3_stmt_re
35a20 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73 adonly() returns
35a30 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65 false for those
35a40 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 53 51 commands..*/.SQ
35a50 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
35a60 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e ite3_stmt_readon
35a70 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 ly(sqlite3_stmt
35a80 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 *pStmt);../*.**
35a90 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d CAPI3REF: Determ
35aa0 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 ine If A Prepare
35ab0 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 d Statement Has
35ac0 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 Been Reset.** ME
35ad0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
35ae0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 mt.**.** ^The sq
35af0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 lite3_stmt_busy(
35b00 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 S) interface ret
35b10 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a urns true (non-z
35b20 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b ero) if the.** [
35b30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
35b40 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 nt] S has been s
35b50 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 tepped at least
35b60 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b once using .** [
35b70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d sqlite3_step(S)]
35b80 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 but has neither
35b90 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 run to completi
35ba0 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 on (returned.**
35bb0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 [SQLITE_DONE] fr
35bc0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 om [sqlite3_step
35bd0 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 (S)]) nor.** bee
35be0 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 n reset using [s
35bf0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d qlite3_reset(S)]
35c00 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f . ^The sqlite3_
35c10 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 stmt_busy(S).**
35c20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
35c30 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 s false if S is
35c40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
35c50 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a If S is not a .
35c60 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 ** NULL pointer
35c70 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 and is not a poi
35c80 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 nter to a valid
35c90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
35ca0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 ent].** object,
35cb0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f then the behavio
35cc0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 r is undefined a
35cd0 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 nd probably unde
35ce0 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 sirable..**.** T
35cf0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 his interface ca
35d00 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d n be used in com
35d10 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 bination [sqlite
35d20 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 3_next_stmt()].*
35d30 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 * to locate all
35d40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
35d50 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 nts associated w
35d60 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a ith a database .
35d70 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 ** connection th
35d80 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f at are in need o
35d90 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 f being reset.
35da0 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 This can be used
35db0 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 ,.** for example
35dc0 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 , in diagnostic
35dd0 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 routines to sear
35de0 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 ch for prepared
35df0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 .** statements t
35e00 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 hat are holding
35e10 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 a transaction op
35e20 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 en..*/.SQLITE_AP
35e30 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 I int sqlite3_st
35e40 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f mt_busy(sqlite3_
35e50 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
35e60 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 API3REF: Dynamic
35e70 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 ally Typed Value
35e80 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f Object.** KEYWO
35e90 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 RDS: {protected
35ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b sqlite3_value} {
35eb0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 unprotected sqli
35ec0 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a te3_value}.**.**
35ed0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 SQLite uses the
35ee0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
35ef0 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 bject to represe
35f00 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a nt all values.**
35f10 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f that can be sto
35f20 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 red in a databas
35f30 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 e table. SQLite
35f40 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 uses dynamic typ
35f50 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 ing.** for the v
35f60 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e alues it stores.
35f70 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 ^Values stored
35f80 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 in sqlite3_valu
35f90 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e e objects.** can
35fa0 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c be integers, fl
35fb0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c oating point val
35fc0 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c ues, strings, BL
35fd0 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a OBs, or NULL..**
35fe0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 .** An sqlite3_v
35ff0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 alue object may
36000 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 be either "prote
36010 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 cted" or "unprot
36020 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 ected"..** Some
36030 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 interfaces requi
36040 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 re a protected s
36050 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f qlite3_value. O
36060 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a ther interfaces.
36070 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 ** will accept e
36080 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 ither a protecte
36090 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 d or an unprotec
360a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
360b0 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 e..** Every inte
360c0 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70 rface that accep
360d0 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ts sqlite3_value
360e0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 arguments speci
360f0 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 fies.** whether
36100 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 or not it requir
36110 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 es a protected s
36120 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 qlite3_value. T
36130 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 he.** [sqlite3_v
36140 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 alue_dup()] inte
36150 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 rface can be use
36160 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 d to construct a
36170 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 new .** protect
36180 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 ed sqlite3_value
36190 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 from an unprote
361a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
361b0 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 ue..**.** The te
361c0 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 rms "protected"
361d0 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 and "unprotected
361e0 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 " refer to wheth
361f0 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d er or not.** a m
36200 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 utex is held. A
36210 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 n internal mutex
36220 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 is held for a p
36230 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
36240 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
36250 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 but no mutex is
36260 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 held for an unp
36270 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 rotected.** sqli
36280 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 te3_value object
36290 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 . If SQLite is
362a0 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 compiled to be s
362b0 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a ingle-threaded.*
362c0 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f * (with [SQLITE_
362d0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e THREADSAFE=0] an
362e0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f d with [sqlite3_
362f0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 threadsafe()] re
36300 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 turning 0).** or
36310 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 if SQLite is ru
36320 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 n in one of redu
36330 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 ced mutex modes
36340 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
36350 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d IG_SINGLETHREAD]
36360 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 or [SQLITE_CONF
36370 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a IG_MULTITHREAD].
36380 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 ** then there is
36390 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 no distinction
363a0 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 between protecte
363b0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 d and unprotecte
363c0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
363d0 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 ue objects and t
363e0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 hey can be used
363f0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e interchangeably.
36400 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f However,.** fo
36410 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 r maximum code p
36420 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 ortability it is
36430 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 recommended tha
36440 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a t applications.*
36450 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 * still make the
36460 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 distinction bet
36470 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 ween protected a
36480 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a nd unprotected.*
36490 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 * sqlite3_value
364a0 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 objects even whe
364b0 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 n not strictly r
364c0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e equired..**.** ^
364d0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 The sqlite3_valu
364e0 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 e objects that a
364f0 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 re passed as par
36500 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 ameters into the
36510 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 .** implementati
36520 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 on of [applicati
36530 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 on-defined SQL f
36540 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 unctions] are pr
36550 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 otected..** ^The
36560 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f sqlite3_value o
36570 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 bject returned b
36580 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f y.** [sqlite3_co
36590 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 lumn_value()] is
365a0 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a unprotected..**
365b0 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c Unprotected sql
365c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
365d0 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 ts may only be u
365e0 73 65 64 20 61 73 20 61 72 67 75 6d 65 6e 74 73 sed as arguments
365f0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f .** to [sqlite3_
36600 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2c result_value()],
36610 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 [sqlite3_bind_v
36620 61 6c 75 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 alue()], and.**
36630 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 [sqlite3_value_d
36640 75 70 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 up()]..** The [s
36650 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f qlite3_value_blo
36660 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 b | sqlite3_valu
36670 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 e_type()] family
36680 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 of.** interface
36690 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 s require protec
366a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 ted sqlite3_valu
366b0 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 e objects..*/.ty
366c0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
366d0 69 74 65 33 5f 76 61 6c 75 65 20 73 71 6c 69 74 ite3_value sqlit
366e0 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a e3_value;../*.**
366f0 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 CAPI3REF: SQL F
36700 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 unction Context
36710 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 Object.**.** The
36720 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 context in whic
36730 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f h an SQL functio
36740 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 n executes is st
36750 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 ored in an.** sq
36760 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 lite3_context ob
36770 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 ject. ^A pointe
36780 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f r to an sqlite3_
36790 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a context object.*
367a0 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 * is always firs
367b0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b t parameter to [
367c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
367d0 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
367e0 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 s]..** The appli
367f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
36800 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c QL function impl
36810 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 ementation will
36820 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 pass this.** poi
36830 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 nter through int
36840 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 o calls to [sqli
36850 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c te3_result_int |
36860 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 sqlite3_result(
36870 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
36880 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 aggregate_contex
36890 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 t()], [sqlite3_u
368a0 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 ser_data()],.**
368b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 [sqlite3_context
368c0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b _db_handle()], [
368d0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 sqlite3_get_auxd
368e0 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f ata()],.** and/o
368f0 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 r [sqlite3_set_a
36900 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 uxdata()]..*/.ty
36910 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
36920 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c ite3_context sql
36930 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f ite3_context;../
36940 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 *.** CAPI3REF: B
36950 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f inding Values To
36960 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d Prepared Statem
36970 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 ents.** KEYWORDS
36980 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 : {host paramete
36990 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 r} {host paramet
369a0 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d ers} {host param
369b0 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 eter name}.** KE
369c0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 YWORDS: {SQL par
369d0 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 ameter} {SQL par
369e0 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 ameters} {parame
369f0 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 ter binding}.**
36a00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f METHOD: sqlite3_
36a10 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 stmt.**.** ^(In
36a20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e the SQL statemen
36a30 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 t text input to
36a40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
36a50 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 _v2()] and its v
36a60 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 ariants,.** lite
36a70 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c rals may be repl
36a80 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d aced by a [param
36a90 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 eter] that match
36aa0 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 es one of follow
36ab0 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 ing.** templates
36ac0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 :.**.** <ul>.**
36ad0 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 <li> ?.** <li>
36ae0 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a ?NNN.** <li> :
36af0 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 VVV.** <li> @VV
36b00 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a V.** <li> $VVV.
36b10 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 ** </ul>.**.** I
36b20 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 n the templates
36b30 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 above, NNN repre
36b40 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 sents an integer
36b50 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 literal,.** and
36b60 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 VVV represents
36b70 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 an alphanumeric
36b80 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e identifier.)^ ^
36b90 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 The values of th
36ba0 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 ese.** parameter
36bb0 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 s (also called "
36bc0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e host parameter n
36bd0 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 ames" or "SQL pa
36be0 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 rameters").** ca
36bf0 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 n be set using t
36c00 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f he sqlite3_bind_
36c10 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 *() routines def
36c20 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a ined here..**.**
36c30 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 ^The first argu
36c40 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 ment to the sqli
36c50 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
36c60 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a tines is always.
36c70 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
36c80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d the [sqlite3_stm
36c90 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e t] object return
36ca0 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 ed from.** [sqli
36cb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 te3_prepare_v2()
36cc0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 ] or its variant
36cd0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 s..**.** ^The se
36ce0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 cond argument is
36cf0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 the index of th
36d00 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 e SQL parameter
36d10 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 to be set..** ^T
36d20 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 he leftmost SQL
36d30 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e parameter has an
36d40 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 index of 1. ^W
36d50 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d hen the same nam
36d60 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 ed.** SQL parame
36d70 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 ter is used more
36d80 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f than once, seco
36d90 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e nd and subsequen
36da0 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 t.** occurrences
36db0 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 have the same i
36dc0 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 ndex as the firs
36dd0 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a t occurrence..**
36de0 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 ^The index for
36df0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 named parameters
36e00 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 can be looked u
36e10 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b p using the.** [
36e20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
36e30 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 ameter_index()]
36e40 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 API if desired.
36e50 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 ^The index.** f
36e60 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 or "?NNN" parame
36e70 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 ters is the valu
36e80 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 e of NNN..** ^Th
36e90 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 e NNN value must
36ea0 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e be between 1 an
36eb0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c d the [sqlite3_l
36ec0 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d imit()].** param
36ed0 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d eter [SQLITE_LIM
36ee0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 IT_VARIABLE_NUMB
36ef0 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c ER] (default val
36f00 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 ue: 999)..**.**
36f10 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d ^The third argum
36f20 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 ent is the value
36f30 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 to bind to the
36f40 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 parameter..** ^I
36f50 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 f the third para
36f60 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
36f70 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 _bind_text() or
36f80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 sqlite3_bind_tex
36f90 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 t16().** or sqli
36fa0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 te3_bind_blob()
36fb0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
36fc0 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 r then the fourt
36fd0 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 h parameter.** i
36fe0 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 s ignored and th
36ff0 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 e end result is
37000 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 the same as sqli
37010 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e te3_bind_null().
37020 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 .**.** ^(In thos
37030 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 e routines that
37040 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 have a fourth ar
37050 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 gument, its valu
37060 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 e is the.** numb
37070 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
37080 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 he parameter. T
37090 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 o be clear: the
370a0 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 value is the.**
370b0 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 number of <u>byt
370c0 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 es</u> in the va
370d0 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d lue, not the num
370e0 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 ber of character
370f0 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 s.)^.** ^If the
37100 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
37110 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 to sqlite3_bind
37120 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 _text() or sqlit
37130 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
37140 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c .** is negative,
37150 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 then the length
37160 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 of the string i
37170 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 s.** the number
37180 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 of bytes up to t
37190 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 he first zero te
371a0 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 rminator..** If
371b0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
371c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
371d0 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e bind_blob() is n
371e0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a egative, then.**
371f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 the behavior is
37200 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 undefined..** I
37210 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 f a non-negative
37220 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
37230 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f r is provided to
37240 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
37250 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 xt().** or sqlit
37260 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 e3_bind_text16()
37270 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
37280 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a _text64() then.*
37290 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 * that parameter
372a0 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 must be the byt
372b0 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 e offset.** wher
372c0 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e e the NUL termin
372d0 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 ator would occur
372e0 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 assuming the st
372f0 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a ring were NUL.**
37300 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 terminated. If
37310 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 any NUL charact
37320 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 ers occur at byt
37330 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 e offsets less t
37340 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 han .** the valu
37350 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 e of the fourth
37360 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 parameter then t
37370 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 he resulting str
37380 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a ing value will.*
37390 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 * contain embedd
373a0 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 ed NULs. The re
373b0 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 sult of expressi
373c0 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 ons involving st
373d0 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d rings.** with em
373e0 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 bedded NULs is u
373f0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 ndefined..**.**
37400 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d ^The fifth argum
37410 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 ent to the BLOB
37420 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 and string bindi
37430 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a ng interfaces.**
37440 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 is a destructor
37450 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 used to dispose
37460 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a of the BLOB or.
37470 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 ** string after
37480 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 SQLite has finis
37490 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 hed with it. ^T
374a0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 he destructor is
374b0 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 called.** to di
374c0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f spose of the BLO
374d0 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e B or string even
374e0 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 if the call to
374f0 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a bind API fails..
37500 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 ** ^If the fifth
37510 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 argument is.**
37520 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 the special valu
37530 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 e [SQLITE_STATIC
37540 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 ], then SQLite a
37550 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a ssumes that the.
37560 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 ** information i
37570 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d s in static, unm
37580 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 anaged space and
37590 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 does not need t
375a0 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e o be freed..** ^
375b0 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 If the fifth arg
375c0 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 ument has the va
375d0 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e lue [SQLITE_TRAN
375e0 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 SIENT], then.**
375f0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 SQLite makes its
37600 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 own private cop
37610 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d y of the data im
37620 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 mediately, befor
37630 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 e.** the sqlite3
37640 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
37650 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a e returns..**.**
37660 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75 ^The sixth argu
37670 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f ment to sqlite3_
37680 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 bind_text64() mu
37690 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 st be one of.**
376a0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b [SQLITE_UTF8], [
376b0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b SQLITE_UTF16], [
376c0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c SQLITE_UTF16BE],
376d0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 or [SQLITE_UTF1
376e0 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 6LE].** to speci
376f0 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 fy the encoding
37700 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 of the text in t
37710 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
37720 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 er. If.** the s
37730 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f ixth argument to
37740 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
37750 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e xt64() is not on
37760 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f e of the.** allo
37770 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e wed values shown
37780 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 above, or if th
37790 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 e text encoding
377a0 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 is different.**
377b0 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e from the encodin
377c0 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 g specified by t
377d0 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 he sixth paramet
377e0 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 er, then the beh
377f0 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 avior.** is unde
37800 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 fined..**.** ^Th
37810 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a e sqlite3_bind_z
37820 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e eroblob() routin
37830 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f e binds a BLOB o
37840 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a f length N that.
37850 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 ** is filled wit
37860 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 h zeroes. ^A ze
37870 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 roblob uses a fi
37880 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 xed amount of me
37890 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e mory.** (just an
378a0 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 integer to hold
378b0 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 its size) while
378c0 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f it is being pro
378d0 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 cessed..** Zerob
378e0 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 lobs are intende
378f0 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c d to serve as pl
37900 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 aceholders for B
37910 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f LOBs whose.** co
37920 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 ntent is later w
37930 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 ritten using.**
37940 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 [sqlite3_blob_op
37950 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c en | incremental
37960 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 BLOB I/O] routi
37970 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 nes..** ^A negat
37980 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 ive value for th
37990 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c e zeroblob resul
379a0 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e ts in a zero-len
379b0 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 gth BLOB..**.**
379c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
379d0 64 5f 70 6f 69 6e 74 65 72 28 53 2c 49 2c 50 2c d_pointer(S,I,P,
379e0 54 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 61 75 T,D) routine cau
379f0 73 65 73 20 74 68 65 20 49 2d 74 68 20 70 61 72 ses the I-th par
37a00 61 6d 65 74 65 72 20 69 6e 0a 2a 2a 20 5b 70 72 ameter in.** [pr
37a10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
37a20 5d 20 53 20 74 6f 20 68 61 76 65 20 61 6e 20 53 ] S to have an S
37a30 51 4c 20 76 61 6c 75 65 20 6f 66 20 4e 55 4c 4c QL value of NULL
37a40 2c 20 62 75 74 20 74 6f 20 61 6c 73 6f 20 62 65 , but to also be
37a50 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 .** associated w
37a60 69 74 68 20 74 68 65 20 70 6f 69 6e 74 65 72 20 ith the pointer
37a70 50 20 6f 66 20 74 79 70 65 20 54 2e 20 20 5e 44 P of type T. ^D
37a80 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c is either a NUL
37a90 4c 20 70 6f 69 6e 74 65 72 20 6f 72 0a 2a 2a 20 L pointer or.**
37aa0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 64 a pointer to a d
37ab0 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 estructor functi
37ac0 6f 6e 20 66 6f 72 20 50 2e 20 5e 53 51 4c 69 74 on for P. ^SQLit
37ad0 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 e will invoke th
37ae0 65 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 20 e.** destructor
37af0 44 20 77 69 74 68 20 61 20 73 69 6e 67 6c 65 20 D with a single
37b00 61 72 67 75 6d 65 6e 74 20 6f 66 20 50 20 77 68 argument of P wh
37b10 65 6e 20 69 74 20 69 73 20 66 69 6e 69 73 68 65 en it is finishe
37b20 64 20 75 73 69 6e 67 0a 2a 2a 20 50 2e 20 20 54 d using.** P. T
37b30 68 65 20 54 20 70 61 72 61 6d 65 74 65 72 20 73 he T parameter s
37b40 68 6f 75 6c 64 20 62 65 20 61 20 73 74 61 74 69 hould be a stati
37b50 63 20 73 74 72 69 6e 67 2c 20 70 72 65 66 65 72 c string, prefer
37b60 61 62 6c 79 20 61 20 73 74 72 69 6e 67 0a 2a 2a ably a string.**
37b70 20 6c 69 74 65 72 61 6c 2e 20 54 68 65 20 73 71 literal. The sq
37b80 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 lite3_bind_point
37b90 65 72 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 er() routine is
37ba0 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b part of the.** [
37bb0 70 6f 69 6e 74 65 72 20 70 61 73 73 69 6e 67 20 pointer passing
37bc0 69 6e 74 65 72 66 61 63 65 5d 20 61 64 64 65 64 interface] added
37bd0 20 66 6f 72 20 53 51 4c 69 74 65 20 33 2e 32 30 for SQLite 3.20
37be0 2e 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e .0..**.** ^If an
37bf0 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 y of the sqlite3
37c00 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e _bind_*() routin
37c10 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 es are called wi
37c20 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 th a NULL pointe
37c30 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 r.** for the [pr
37c40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 epared statement
37c50 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 ] or with a prep
37c60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 ared statement f
37c70 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c or which.** [sql
37c80 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 ite3_step()] has
37c90 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 been called mor
37ca0 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 e recently than
37cb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 [sqlite3_reset()
37cc0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 ],.** then the c
37cd0 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 all will return
37ce0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e [SQLITE_MISUSE].
37cf0 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 If any sqlite3
37d00 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 _bind_().** rout
37d10 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 ine is passed a
37d20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d [prepared statem
37d30 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 ent] that has be
37d40 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 en finalized, th
37d50 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 e.** result is u
37d60 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f ndefined and pro
37d70 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a bably harmful..*
37d80 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 *.** ^Bindings a
37d90 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 re not cleared b
37da0 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 y the [sqlite3_r
37db0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e eset()] routine.
37dc0 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 .** ^Unbound par
37dd0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 ameters are inte
37de0 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e rpreted as NULL.
37df0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
37e00 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 te3_bind_* routi
37e10 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 nes return [SQLI
37e20 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 TE_OK] on succes
37e30 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f s or an.** [erro
37e40 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 r code] if anyth
37e50 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a ing goes wrong..
37e60 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 ** ^[SQLITE_TOOB
37e70 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 IG] might be ret
37e80 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a urned if the siz
37e90 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 e of a string or
37ea0 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 BLOB.** exceeds
37eb0 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 limits imposed
37ec0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 by [sqlite3_limi
37ed0 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 t]([SQLITE_LIMIT
37ee0 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 _LENGTH]) or.**
37ef0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 [SQLITE_MAX_LENG
37f00 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 TH]..** ^[SQLITE
37f10 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 _RANGE] is retur
37f20 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d ned if the param
37f30 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 eter.** index is
37f40 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 out of range.
37f50 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 ^[SQLITE_NOMEM]
37f60 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d is returned if m
37f70 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a alloc() fails..*
37f80 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b *.** See also: [
37f90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
37fa0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c ameter_count()],
37fb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
37fc0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
37fd0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 ()], and [sqlite
37fe0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
37ff0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 _index()]..*/.SQ
38000 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
38010 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 ite3_bind_blob(s
38020 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
38030 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 t, const void*,
38040 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 int n, void(*)(v
38050 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
38060 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
38070 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 ind_blob64(sqlit
38080 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
38090 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 onst void*, sqli
380a0 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 te3_uint64,.
380b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
380c0 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 void(*)(void
380d0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 *));.SQLITE_API
380e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
380f0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f _double(sqlite3_
38100 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 stmt*, int, doub
38110 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 le);.SQLITE_API
38120 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
38130 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d _int(sqlite3_stm
38140 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 t*, int, int);.S
38150 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
38160 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 lite3_bind_int64
38170 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
38180 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 int, sqlite3_int
38190 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64);.SQLITE_API
381a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
381b0 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 _null(sqlite3_st
381c0 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 mt*, int);.SQLIT
381d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 E_API int sqlite
381e0 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 3_bind_text(sqli
381f0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f te3_stmt*,int,co
38200 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f nst char*,int,vo
38210 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 id(*)(void*));.S
38220 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
38230 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 lite3_bind_text1
38240 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 6(sqlite3_stmt*,
38250 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 int, const void
38260 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 *, int, void(*)(
38270 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f void*));.SQLITE_
38280 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
38290 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 bind_text64(sqli
382a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 te3_stmt*, int,
382b0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c const char*, sql
382c0 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 ite3_uint64,.
382d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
382e0 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f void(*)(vo
382f0 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 id*), unsigned c
38300 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 har encoding);.S
38310 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
38320 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 lite3_bind_value
38330 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
38340 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 int, const sqlit
38350 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 e3_value*);.SQLI
38360 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
38370 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 65 72 28 e3_bind_pointer(
38380 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
38390 6e 74 2c 20 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 nt, void*, const
383a0 20 63 68 61 72 2a 2c 76 6f 69 64 28 2a 29 28 76 char*,void(*)(v
383b0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
383c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
383d0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c ind_zeroblob(sql
383e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c ite3_stmt*, int,
383f0 20 69 6e 74 20 6e 29 3b 0a 53 51 4c 49 54 45 5f int n);.SQLITE_
38400 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
38410 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 bind_zeroblob64(
38420 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 sqlite3_stmt*, i
38430 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 nt, sqlite3_uint
38440 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 64);../*.** CAPI
38450 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 3REF: Number Of
38460 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a SQL Parameters.*
38470 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
38480 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
38490 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 is routine can b
384a0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 e used to find t
384b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 he number of [SQ
384c0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a L parameters].**
384d0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 in a [prepared
384e0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c statement]. SQL
384f0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 parameters are
38500 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a tokens of the.**
38510 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e form "?", "?NNN
38520 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 ", ":AAA", "$AAA
38530 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 ", or "@AAA" tha
38540 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c t serve as.** pl
38550 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 aceholders for v
38560 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b alues that are [
38570 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
38580 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f b | bound].** to
38590 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 the parameters
385a0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e at a later time.
385b0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f .**.** ^(This ro
385c0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 utine actually r
385d0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 eturns the index
385e0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 of the largest
385f0 28 72 69 67 68 74