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 33 2e 30 2e 20 20 ersion 3.23.0.
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 0a 2a 2a 20 41 6e 20 61 72 72 61 79 20 6f 66 *.** An array of
0960: 20 6e 61 6d 65 73 20 6f 66 20 61 6c 6c 20 63 6f names of all co
0970: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
0980: 6e 73 2e 20 20 54 68 69 73 20 61 72 72 61 79 20 ns. This array
0990: 73 68 6f 75 6c 64 20 0a 2a 2a 20 62 65 20 73 6f should .** be so
09a0: 72 74 65 64 20 41 2d 5a 2e 0a 2a 2a 0a 2a 2a 20 rted A-Z..**.**
09b0: 54 68 69 73 20 61 72 72 61 79 20 6c 6f 6f 6b 73 This array looks
09c0: 20 6c 61 72 67 65 2c 20 62 75 74 20 69 6e 20 61 large, but in a
09d0: 20 74 79 70 69 63 61 6c 20 69 6e 73 74 61 6c 6c typical install
09e0: 61 74 69 6f 6e 20 61 63 74 75 61 6c 6c 79 20 75 ation actually u
09f0: 73 65 73 0a 2a 2a 20 6f 6e 6c 79 20 61 20 68 61 ses.** only a ha
0a00: 6e 64 66 75 6c 20 6f 66 20 63 6f 6d 70 69 6c 65 ndful of compile
0a10: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 73 2c 20 73 -time options, s
0a20: 6f 20 6d 6f 73 74 20 74 69 6d 65 73 20 74 68 69 o most times thi
0a30: 73 20 61 72 72 61 79 20 69 73 20 75 73 75 61 6c s array is usual
0a40: 6c 79 0a 2a 2a 20 72 61 74 68 65 72 20 73 68 6f ly.** rather sho
0a50: 72 74 20 61 6e 64 20 75 73 65 73 20 6c 69 74 74 rt and uses litt
0a60: 6c 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 2e le memory space.
0a70: 0a 2a 2f 0a 73 74 61 74 69 63 20 63 6f 6e 73 74 .*/.static const
0a80: 20 63 68 61 72 20 2a 20 63 6f 6e 73 74 20 73 71 char * const sq
0a90: 6c 69 74 65 33 61 7a 43 6f 6d 70 69 6c 65 4f 70 lite3azCompileOp
0aa0: 74 5b 5d 20 3d 20 7b 0a 0a 2f 2a 20 0a 2a 2a 20 t[] = {../* .**
0ab0: 42 45 47 49 4e 20 43 4f 44 45 20 47 45 4e 45 52 BEGIN CODE GENER
0ac0: 41 54 45 44 20 42 59 20 74 6f 6f 6c 2f 6d 6b 63 ATED BY tool/mkc
0ad0: 74 69 6d 65 2e 74 63 6c 20 0a 2a 2f 0a 23 69 66 time.tcl .*/.#if
0ae0: 20 53 51 4c 49 54 45 5f 33 32 42 49 54 5f 52 4f SQLITE_32BIT_RO
0af0: 57 49 44 0a 20 20 22 33 32 42 49 54 5f 52 4f 57 WID. "32BIT_ROW
0b00: 49 44 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 ID",.#endif.#if
0b10: 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c SQLITE_4_BYTE_AL
0b20: 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 0a 20 20 22 IGNED_MALLOC. "
0b30: 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 4_BYTE_ALIGNED_M
0b40: 41 4c 4c 4f 43 22 2c 0a 23 65 6e 64 69 66 0a 23 ALLOC",.#endif.#
0b50: 69 66 20 53 51 4c 49 54 45 5f 36 34 42 49 54 5f if SQLITE_64BIT_
0b60: 53 54 41 54 53 0a 20 20 22 36 34 42 49 54 5f 53 STATS. "64BIT_S
0b70: 54 41 54 53 22 2c 0a 23 65 6e 64 69 66 0a 23 69 TATS",.#endif.#i
0b80: 66 20 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 f SQLITE_ALLOW_C
0b90: 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 OVERING_INDEX_SC
0ba0: 41 4e 0a 20 20 22 41 4c 4c 4f 57 5f 43 4f 56 45 AN. "ALLOW_COVE
0bb0: 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 22 RING_INDEX_SCAN"
0bc0: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
0bd0: 49 54 45 5f 41 4c 4c 4f 57 5f 55 52 49 5f 41 55 ITE_ALLOW_URI_AU
0be0: 54 48 4f 52 49 54 59 0a 20 20 22 41 4c 4c 4f 57 THORITY. "ALLOW
0bf0: 5f 55 52 49 5f 41 55 54 48 4f 52 49 54 59 22 2c _URI_AUTHORITY",
0c00: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 .#endif.#ifdef S
0c10: 51 4c 49 54 45 5f 42 49 54 4d 41 53 4b 5f 54 59 QLITE_BITMASK_TY
0c20: 50 45 0a 20 20 22 42 49 54 4d 41 53 4b 5f 54 59 PE. "BITMASK_TY
0c30: 50 45 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 PE=" CTIMEOPT_VA
0c40: 4c 28 53 51 4c 49 54 45 5f 42 49 54 4d 41 53 4b L(SQLITE_BITMASK
0c50: 5f 54 59 50 45 29 2c 0a 23 65 6e 64 69 66 0a 23 _TYPE),.#endif.#
0c60: 69 66 20 53 51 4c 49 54 45 5f 42 55 47 5f 43 4f if SQLITE_BUG_CO
0c70: 4d 50 41 54 49 42 4c 45 5f 32 30 31 36 30 38 31 MPATIBLE_2016081
0c80: 39 0a 20 20 22 42 55 47 5f 43 4f 4d 50 41 54 49 9. "BUG_COMPATI
0c90: 42 4c 45 5f 32 30 31 36 30 38 31 39 22 2c 0a 23 BLE_20160819",.#
0ca0: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
0cb0: 5f 43 41 53 45 5f 53 45 4e 53 49 54 49 56 45 5f _CASE_SENSITIVE_
0cc0: 4c 49 4b 45 0a 20 20 22 43 41 53 45 5f 53 45 4e LIKE. "CASE_SEN
0cd0: 53 49 54 49 56 45 5f 4c 49 4b 45 22 2c 0a 23 65 SITIVE_LIKE",.#e
0ce0: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
0cf0: 43 48 45 43 4b 5f 50 41 47 45 53 0a 20 20 22 43 CHECK_PAGES. "C
0d00: 48 45 43 4b 5f 50 41 47 45 53 22 2c 0a 23 65 6e HECK_PAGES",.#en
0d10: 64 69 66 0a 23 69 66 20 64 65 66 69 6e 65 64 28 dif.#if defined(
0d20: 5f 5f 63 6c 61 6e 67 5f 5f 29 20 26 26 20 64 65 __clang__) && de
0d30: 66 69 6e 65 64 28 5f 5f 63 6c 61 6e 67 5f 6d 61 fined(__clang_ma
0d40: 6a 6f 72 5f 5f 29 0a 20 20 22 43 4f 4d 50 49 4c jor__). "COMPIL
0d50: 45 52 3d 63 6c 61 6e 67 2d 22 20 43 54 49 4d 45 ER=clang-" CTIME
0d60: 4f 50 54 5f 56 41 4c 28 5f 5f 63 6c 61 6e 67 5f OPT_VAL(__clang_
0d70: 6d 61 6a 6f 72 5f 5f 29 20 22 2e 22 0a 20 20 20 major__) ".".
0d80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
0d90: 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 5f 5f CTIMEOPT_VAL(__
0da0: 63 6c 61 6e 67 5f 6d 69 6e 6f 72 5f 5f 29 20 22 clang_minor__) "
0db0: 2e 22 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 .".
0dc0: 20 20 20 20 20 20 20 43 54 49 4d 45 4f 50 54 5f CTIMEOPT_
0dd0: 56 41 4c 28 5f 5f 63 6c 61 6e 67 5f 70 61 74 63 VAL(__clang_patc
0de0: 68 6c 65 76 65 6c 5f 5f 29 2c 0a 23 65 6c 69 66 hlevel__),.#elif
0df0: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 defined(_MSC_VE
0e00: 52 29 0a 20 20 22 43 4f 4d 50 49 4c 45 52 3d 6d R). "COMPILER=m
0e10: 73 76 63 2d 22 20 43 54 49 4d 45 4f 50 54 5f 56 svc-" CTIMEOPT_V
0e20: 41 4c 28 5f 4d 53 43 5f 56 45 52 29 2c 0a 23 65 AL(_MSC_VER),.#e
0e30: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e lif defined(__GN
0e40: 55 43 5f 5f 29 20 26 26 20 64 65 66 69 6e 65 64 UC__) && defined
0e50: 28 5f 5f 56 45 52 53 49 4f 4e 5f 5f 29 0a 20 20 (__VERSION__).
0e60: 22 43 4f 4d 50 49 4c 45 52 3d 67 63 63 2d 22 20 "COMPILER=gcc-"
0e70: 5f 5f 56 45 52 53 49 4f 4e 5f 5f 2c 0a 23 65 6e __VERSION__,.#en
0e80: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 43 dif.#if SQLITE_C
0e90: 4f 56 45 52 41 47 45 5f 54 45 53 54 0a 20 20 22 OVERAGE_TEST. "
0ea0: 43 4f 56 45 52 41 47 45 5f 54 45 53 54 22 2c 0a COVERAGE_TEST",.
0eb0: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
0ec0: 45 5f 44 45 42 55 47 0a 20 20 22 44 45 42 55 47 E_DEBUG. "DEBUG
0ed0: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
0ee0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 41 55 54 LITE_DEFAULT_AUT
0ef0: 4f 4d 41 54 49 43 5f 49 4e 44 45 58 0a 20 20 22 OMATIC_INDEX. "
0f00: 44 45 46 41 55 4c 54 5f 41 55 54 4f 4d 41 54 49 DEFAULT_AUTOMATI
0f10: 43 5f 49 4e 44 45 58 22 2c 0a 23 65 6e 64 69 66 C_INDEX",.#endif
0f20: 0a 23 69 66 20 53 51 4c 49 54 45 5f 44 45 46 41 .#if SQLITE_DEFA
0f30: 55 4c 54 5f 41 55 54 4f 56 41 43 55 55 4d 0a 20 ULT_AUTOVACUUM.
0f40: 20 22 44 45 46 41 55 4c 54 5f 41 55 54 4f 56 41 "DEFAULT_AUTOVA
0f50: 43 55 55 4d 22 2c 0a 23 65 6e 64 69 66 0a 23 69 CUUM",.#endif.#i
0f60: 66 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 fdef SQLITE_DEFA
0f70: 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45 0a 20 ULT_CACHE_SIZE.
0f80: 20 22 44 45 46 41 55 4c 54 5f 43 41 43 48 45 5f "DEFAULT_CACHE_
0f90: 53 49 5a 45 3d 22 20 43 54 49 4d 45 4f 50 54 5f SIZE=" CTIMEOPT_
0fa0: 56 41 4c 28 53 51 4c 49 54 45 5f 44 45 46 41 55 VAL(SQLITE_DEFAU
0fb0: 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45 29 2c 0a LT_CACHE_SIZE),.
0fc0: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
0fd0: 45 5f 44 45 46 41 55 4c 54 5f 43 4b 50 54 46 55 E_DEFAULT_CKPTFU
0fe0: 4c 4c 46 53 59 4e 43 0a 20 20 22 44 45 46 41 55 LLFSYNC. "DEFAU
0ff0: 4c 54 5f 43 4b 50 54 46 55 4c 4c 46 53 59 4e 43 LT_CKPTFULLFSYNC
1000: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 ",.#endif.#ifdef
1010: 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f SQLITE_DEFAULT_
1020: 46 49 4c 45 5f 46 4f 52 4d 41 54 0a 20 20 22 44 FILE_FORMAT. "D
1030: 45 46 41 55 4c 54 5f 46 49 4c 45 5f 46 4f 52 4d EFAULT_FILE_FORM
1040: 41 54 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 AT=" CTIMEOPT_VA
1050: 4c 28 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 L(SQLITE_DEFAULT
1060: 5f 46 49 4c 45 5f 46 4f 52 4d 41 54 29 2c 0a 23 _FILE_FORMAT),.#
1070: 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c endif.#ifdef SQL
1080: 49 54 45 5f 44 45 46 41 55 4c 54 5f 46 49 4c 45 ITE_DEFAULT_FILE
1090: 5f 50 45 52 4d 49 53 53 49 4f 4e 53 0a 20 20 22 _PERMISSIONS. "
10a0: 44 45 46 41 55 4c 54 5f 46 49 4c 45 5f 50 45 52 DEFAULT_FILE_PER
10b0: 4d 49 53 53 49 4f 4e 53 3d 22 20 43 54 49 4d 45 MISSIONS=" CTIME
10c0: 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 44 OPT_VAL(SQLITE_D
10d0: 45 46 41 55 4c 54 5f 46 49 4c 45 5f 50 45 52 4d EFAULT_FILE_PERM
10e0: 49 53 53 49 4f 4e 53 29 2c 0a 23 65 6e 64 69 66 ISSIONS),.#endif
10f0: 0a 23 69 66 20 53 51 4c 49 54 45 5f 44 45 46 41 .#if SQLITE_DEFA
1100: 55 4c 54 5f 46 4f 52 45 49 47 4e 5f 4b 45 59 53 ULT_FOREIGN_KEYS
1110: 0a 20 20 22 44 45 46 41 55 4c 54 5f 46 4f 52 45 . "DEFAULT_FORE
1120: 49 47 4e 5f 4b 45 59 53 22 2c 0a 23 65 6e 64 69 IGN_KEYS",.#endi
1130: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
1140: 44 45 46 41 55 4c 54 5f 4a 4f 55 52 4e 41 4c 5f DEFAULT_JOURNAL_
1150: 53 49 5a 45 5f 4c 49 4d 49 54 0a 20 20 22 44 45 SIZE_LIMIT. "DE
1160: 46 41 55 4c 54 5f 4a 4f 55 52 4e 41 4c 5f 53 49 FAULT_JOURNAL_SI
1170: 5a 45 5f 4c 49 4d 49 54 3d 22 20 43 54 49 4d 45 ZE_LIMIT=" CTIME
1180: 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 44 OPT_VAL(SQLITE_D
1190: 45 46 41 55 4c 54 5f 4a 4f 55 52 4e 41 4c 5f 53 EFAULT_JOURNAL_S
11a0: 49 5a 45 5f 4c 49 4d 49 54 29 2c 0a 23 65 6e 64 IZE_LIMIT),.#end
11b0: 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 if.#ifdef SQLITE
11c0: 5f 44 45 46 41 55 4c 54 5f 4c 4f 43 4b 49 4e 47 _DEFAULT_LOCKING
11d0: 5f 4d 4f 44 45 0a 20 20 22 44 45 46 41 55 4c 54 _MODE. "DEFAULT
11e0: 5f 4c 4f 43 4b 49 4e 47 5f 4d 4f 44 45 3d 22 20 _LOCKING_MODE="
11f0: 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c CTIMEOPT_VAL(SQL
1200: 49 54 45 5f 44 45 46 41 55 4c 54 5f 4c 4f 43 4b ITE_DEFAULT_LOCK
1210: 49 4e 47 5f 4d 4f 44 45 29 2c 0a 23 65 6e 64 69 ING_MODE),.#endi
1220: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
1230: 44 45 46 41 55 4c 54 5f 4c 4f 4f 4b 41 53 49 44 DEFAULT_LOOKASID
1240: 45 0a 20 20 22 44 45 46 41 55 4c 54 5f 4c 4f 4f E. "DEFAULT_LOO
1250: 4b 41 53 49 44 45 3d 22 20 43 54 49 4d 45 4f 50 KASIDE=" CTIMEOP
1260: 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 44 45 46 T_VAL(SQLITE_DEF
1270: 41 55 4c 54 5f 4c 4f 4f 4b 41 53 49 44 45 29 2c AULT_LOOKASIDE),
1280: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
1290: 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 TE_DEFAULT_MEMST
12a0: 41 54 55 53 0a 20 20 22 44 45 46 41 55 4c 54 5f ATUS. "DEFAULT_
12b0: 4d 45 4d 53 54 41 54 55 53 22 2c 0a 23 65 6e 64 MEMSTATUS",.#end
12c0: 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 if.#ifdef SQLITE
12d0: 5f 44 45 46 41 55 4c 54 5f 4d 4d 41 50 5f 53 49 _DEFAULT_MMAP_SI
12e0: 5a 45 0a 20 20 22 44 45 46 41 55 4c 54 5f 4d 4d ZE. "DEFAULT_MM
12f0: 41 50 5f 53 49 5a 45 3d 22 20 43 54 49 4d 45 4f AP_SIZE=" CTIMEO
1300: 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 44 45 PT_VAL(SQLITE_DE
1310: 46 41 55 4c 54 5f 4d 4d 41 50 5f 53 49 5a 45 29 FAULT_MMAP_SIZE)
1320: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 ,.#endif.#ifdef
1330: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 SQLITE_DEFAULT_P
1340: 41 47 45 5f 53 49 5a 45 0a 20 20 22 44 45 46 41 AGE_SIZE. "DEFA
1350: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 3d 22 20 ULT_PAGE_SIZE="
1360: 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c CTIMEOPT_VAL(SQL
1370: 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 ITE_DEFAULT_PAGE
1380: 5f 53 49 5a 45 29 2c 0a 23 65 6e 64 69 66 0a 23 _SIZE),.#endif.#
1390: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 ifdef SQLITE_DEF
13a0: 41 55 4c 54 5f 50 43 41 43 48 45 5f 49 4e 49 54 AULT_PCACHE_INIT
13b0: 53 5a 0a 20 20 22 44 45 46 41 55 4c 54 5f 50 43 SZ. "DEFAULT_PC
13c0: 41 43 48 45 5f 49 4e 49 54 53 5a 3d 22 20 43 54 ACHE_INITSZ=" CT
13d0: 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 IMEOPT_VAL(SQLIT
13e0: 45 5f 44 45 46 41 55 4c 54 5f 50 43 41 43 48 45 E_DEFAULT_PCACHE
13f0: 5f 49 4e 49 54 53 5a 29 2c 0a 23 65 6e 64 69 66 _INITSZ),.#endif
1400: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 44 .#ifdef SQLITE_D
1410: 45 46 41 55 4c 54 5f 50 52 4f 58 59 44 49 52 5f EFAULT_PROXYDIR_
1420: 50 45 52 4d 49 53 53 49 4f 4e 53 0a 20 20 22 44 PERMISSIONS. "D
1430: 45 46 41 55 4c 54 5f 50 52 4f 58 59 44 49 52 5f EFAULT_PROXYDIR_
1440: 50 45 52 4d 49 53 53 49 4f 4e 53 3d 22 20 43 54 PERMISSIONS=" CT
1450: 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 IMEOPT_VAL(SQLIT
1460: 45 5f 44 45 46 41 55 4c 54 5f 50 52 4f 58 59 44 E_DEFAULT_PROXYD
1470: 49 52 5f 50 45 52 4d 49 53 53 49 4f 4e 53 29 2c IR_PERMISSIONS),
1480: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
1490: 54 45 5f 44 45 46 41 55 4c 54 5f 52 45 43 55 52 TE_DEFAULT_RECUR
14a0: 53 49 56 45 5f 54 52 49 47 47 45 52 53 0a 20 20 SIVE_TRIGGERS.
14b0: 22 44 45 46 41 55 4c 54 5f 52 45 43 55 52 53 49 "DEFAULT_RECURSI
14c0: 56 45 5f 54 52 49 47 47 45 52 53 22 2c 0a 23 65 VE_TRIGGERS",.#e
14d0: 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 ndif.#ifdef SQLI
14e0: 54 45 5f 44 45 46 41 55 4c 54 5f 52 4f 57 45 53 TE_DEFAULT_ROWES
14f0: 54 0a 20 20 22 44 45 46 41 55 4c 54 5f 52 4f 57 T. "DEFAULT_ROW
1500: 45 53 54 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 EST=" CTIMEOPT_V
1510: 41 4c 28 53 51 4c 49 54 45 5f 44 45 46 41 55 4c AL(SQLITE_DEFAUL
1520: 54 5f 52 4f 57 45 53 54 29 2c 0a 23 65 6e 64 69 T_ROWEST),.#endi
1530: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
1540: 44 45 46 41 55 4c 54 5f 53 45 43 54 4f 52 5f 53 DEFAULT_SECTOR_S
1550: 49 5a 45 0a 20 20 22 44 45 46 41 55 4c 54 5f 53 IZE. "DEFAULT_S
1560: 45 43 54 4f 52 5f 53 49 5a 45 3d 22 20 43 54 49 ECTOR_SIZE=" CTI
1570: 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 MEOPT_VAL(SQLITE
1580: 5f 44 45 46 41 55 4c 54 5f 53 45 43 54 4f 52 5f _DEFAULT_SECTOR_
1590: 53 49 5a 45 29 2c 0a 23 65 6e 64 69 66 0a 23 69 SIZE),.#endif.#i
15a0: 66 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 fdef SQLITE_DEFA
15b0: 55 4c 54 5f 53 59 4e 43 48 52 4f 4e 4f 55 53 0a ULT_SYNCHRONOUS.
15c0: 20 20 22 44 45 46 41 55 4c 54 5f 53 59 4e 43 48 "DEFAULT_SYNCH
15d0: 52 4f 4e 4f 55 53 3d 22 20 43 54 49 4d 45 4f 50 RONOUS=" CTIMEOP
15e0: 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 44 45 46 T_VAL(SQLITE_DEF
15f0: 41 55 4c 54 5f 53 59 4e 43 48 52 4f 4e 4f 55 53 AULT_SYNCHRONOUS
1600: 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 ),.#endif.#ifdef
1610: 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f SQLITE_DEFAULT_
1620: 57 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 WAL_AUTOCHECKPOI
1630: 4e 54 0a 20 20 22 44 45 46 41 55 4c 54 5f 57 41 NT. "DEFAULT_WA
1640: 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54 L_AUTOCHECKPOINT
1650: 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 =" CTIMEOPT_VAL(
1660: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57 SQLITE_DEFAULT_W
1670: 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e AL_AUTOCHECKPOIN
1680: 54 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 T),.#endif.#ifde
1690: 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 f SQLITE_DEFAULT
16a0: 5f 57 41 4c 5f 53 59 4e 43 48 52 4f 4e 4f 55 53 _WAL_SYNCHRONOUS
16b0: 0a 20 20 22 44 45 46 41 55 4c 54 5f 57 41 4c 5f . "DEFAULT_WAL_
16c0: 53 59 4e 43 48 52 4f 4e 4f 55 53 3d 22 20 43 54 SYNCHRONOUS=" CT
16d0: 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 IMEOPT_VAL(SQLIT
16e0: 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 53 59 E_DEFAULT_WAL_SY
16f0: 4e 43 48 52 4f 4e 4f 55 53 29 2c 0a 23 65 6e 64 NCHRONOUS),.#end
1700: 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 if.#ifdef SQLITE
1710: 5f 44 45 46 41 55 4c 54 5f 57 4f 52 4b 45 52 5f _DEFAULT_WORKER_
1720: 54 48 52 45 41 44 53 0a 20 20 22 44 45 46 41 55 THREADS. "DEFAU
1730: 4c 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 LT_WORKER_THREAD
1740: 53 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c S=" CTIMEOPT_VAL
1750: 28 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f (SQLITE_DEFAULT_
1760: 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 29 2c WORKER_THREADS),
1770: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
1780: 54 45 5f 44 49 52 45 43 54 5f 4f 56 45 52 46 4c TE_DIRECT_OVERFL
1790: 4f 57 5f 52 45 41 44 0a 20 20 22 44 49 52 45 43 OW_READ. "DIREC
17a0: 54 5f 4f 56 45 52 46 4c 4f 57 5f 52 45 41 44 22 T_OVERFLOW_READ"
17b0: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
17c0: 49 54 45 5f 44 49 53 41 42 4c 45 5f 44 49 52 53 ITE_DISABLE_DIRS
17d0: 59 4e 43 0a 20 20 22 44 49 53 41 42 4c 45 5f 44 YNC. "DISABLE_D
17e0: 49 52 53 59 4e 43 22 2c 0a 23 65 6e 64 69 66 0a IRSYNC",.#endif.
17f0: 23 69 66 20 53 51 4c 49 54 45 5f 44 49 53 41 42 #if SQLITE_DISAB
1800: 4c 45 5f 46 54 53 33 5f 55 4e 49 43 4f 44 45 0a LE_FTS3_UNICODE.
1810: 20 20 22 44 49 53 41 42 4c 45 5f 46 54 53 33 5f "DISABLE_FTS3_
1820: 55 4e 49 43 4f 44 45 22 2c 0a 23 65 6e 64 69 66 UNICODE",.#endif
1830: 0a 23 69 66 20 53 51 4c 49 54 45 5f 44 49 53 41 .#if SQLITE_DISA
1840: 42 4c 45 5f 46 54 53 34 5f 44 45 46 45 52 52 45 BLE_FTS4_DEFERRE
1850: 44 0a 20 20 22 44 49 53 41 42 4c 45 5f 46 54 53 D. "DISABLE_FTS
1860: 34 5f 44 45 46 45 52 52 45 44 22 2c 0a 23 65 6e 4_DEFERRED",.#en
1870: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 44 dif.#if SQLITE_D
1880: 49 53 41 42 4c 45 5f 49 4e 54 52 49 4e 53 49 43 ISABLE_INTRINSIC
1890: 0a 20 20 22 44 49 53 41 42 4c 45 5f 49 4e 54 52 . "DISABLE_INTR
18a0: 49 4e 53 49 43 22 2c 0a 23 65 6e 64 69 66 0a 23 INSIC",.#endif.#
18b0: 69 66 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c if SQLITE_DISABL
18c0: 45 5f 4c 46 53 0a 20 20 22 44 49 53 41 42 4c 45 E_LFS. "DISABLE
18d0: 5f 4c 46 53 22 2c 0a 23 65 6e 64 69 66 0a 23 69 _LFS",.#endif.#i
18e0: 66 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 f SQLITE_DISABLE
18f0: 5f 50 41 47 45 43 41 43 48 45 5f 4f 56 45 52 46 _PAGECACHE_OVERF
1900: 4c 4f 57 5f 53 54 41 54 53 0a 20 20 22 44 49 53 LOW_STATS. "DIS
1910: 41 42 4c 45 5f 50 41 47 45 43 41 43 48 45 5f 4f ABLE_PAGECACHE_O
1920: 56 45 52 46 4c 4f 57 5f 53 54 41 54 53 22 2c 0a VERFLOW_STATS",.
1930: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
1940: 45 5f 44 49 53 41 42 4c 45 5f 53 4b 49 50 41 48 E_DISABLE_SKIPAH
1950: 45 41 44 5f 44 49 53 54 49 4e 43 54 0a 20 20 22 EAD_DISTINCT. "
1960: 44 49 53 41 42 4c 45 5f 53 4b 49 50 41 48 45 41 DISABLE_SKIPAHEA
1970: 44 5f 44 49 53 54 49 4e 43 54 22 2c 0a 23 65 6e D_DISTINCT",.#en
1980: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 dif.#ifdef SQLIT
1990: 45 5f 45 4e 41 42 4c 45 5f 38 5f 33 5f 4e 41 4d E_ENABLE_8_3_NAM
19a0: 45 53 0a 20 20 22 45 4e 41 42 4c 45 5f 38 5f 33 ES. "ENABLE_8_3
19b0: 5f 4e 41 4d 45 53 3d 22 20 43 54 49 4d 45 4f 50 _NAMES=" CTIMEOP
19c0: 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 45 4e 41 T_VAL(SQLITE_ENA
19d0: 42 4c 45 5f 38 5f 33 5f 4e 41 4d 45 53 29 2c 0a BLE_8_3_NAMES),.
19e0: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
19f0: 45 5f 45 4e 41 42 4c 45 5f 41 50 49 5f 41 52 4d E_ENABLE_API_ARM
1a00: 4f 52 0a 20 20 22 45 4e 41 42 4c 45 5f 41 50 49 OR. "ENABLE_API
1a10: 5f 41 52 4d 4f 52 22 2c 0a 23 65 6e 64 69 66 0a _ARMOR",.#endif.
1a20: 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c #if SQLITE_ENABL
1a30: 45 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 0a 20 E_ATOMIC_WRITE.
1a40: 20 22 45 4e 41 42 4c 45 5f 41 54 4f 4d 49 43 5f "ENABLE_ATOMIC_
1a50: 57 52 49 54 45 22 2c 0a 23 65 6e 64 69 66 0a 23 WRITE",.#endif.#
1a60: 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 if SQLITE_ENABLE
1a70: 5f 42 41 54 43 48 5f 41 54 4f 4d 49 43 5f 57 52 _BATCH_ATOMIC_WR
1a80: 49 54 45 0a 20 20 22 45 4e 41 42 4c 45 5f 42 41 ITE. "ENABLE_BA
1a90: 54 43 48 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 TCH_ATOMIC_WRITE
1aa0: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
1ab0: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f LITE_ENABLE_CERO
1ac0: 44 0a 20 20 22 45 4e 41 42 4c 45 5f 43 45 52 4f D. "ENABLE_CERO
1ad0: 44 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 D",.#endif.#if S
1ae0: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c QLITE_ENABLE_COL
1af0: 55 4d 4e 5f 4d 45 54 41 44 41 54 41 0a 20 20 22 UMN_METADATA. "
1b00: 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 ENABLE_COLUMN_ME
1b10: 54 41 44 41 54 41 22 2c 0a 23 65 6e 64 69 66 0a TADATA",.#endif.
1b20: 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c #if SQLITE_ENABL
1b30: 45 5f 43 4f 4c 55 4d 4e 5f 55 53 45 44 5f 4d 41 E_COLUMN_USED_MA
1b40: 53 4b 0a 20 20 22 45 4e 41 42 4c 45 5f 43 4f 4c SK. "ENABLE_COL
1b50: 55 4d 4e 5f 55 53 45 44 5f 4d 41 53 4b 22 2c 0a UMN_USED_MASK",.
1b60: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
1b70: 45 5f 45 4e 41 42 4c 45 5f 43 4f 53 54 4d 55 4c E_ENABLE_COSTMUL
1b80: 54 0a 20 20 22 45 4e 41 42 4c 45 5f 43 4f 53 54 T. "ENABLE_COST
1b90: 4d 55 4c 54 22 2c 0a 23 65 6e 64 69 66 0a 23 69 MULT",.#endif.#i
1ba0: 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f f SQLITE_ENABLE_
1bb0: 43 55 52 53 4f 52 5f 48 49 4e 54 53 0a 20 20 22 CURSOR_HINTS. "
1bc0: 45 4e 41 42 4c 45 5f 43 55 52 53 4f 52 5f 48 49 ENABLE_CURSOR_HI
1bd0: 4e 54 53 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 NTS",.#endif.#if
1be0: 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 44 SQLITE_ENABLE_D
1bf0: 42 53 54 41 54 5f 56 54 41 42 0a 20 20 22 45 4e BSTAT_VTAB. "EN
1c00: 41 42 4c 45 5f 44 42 53 54 41 54 5f 56 54 41 42 ABLE_DBSTAT_VTAB
1c10: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
1c20: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 45 58 50 45 LITE_ENABLE_EXPE
1c30: 4e 53 49 56 45 5f 41 53 53 45 52 54 0a 20 20 22 NSIVE_ASSERT. "
1c40: 45 4e 41 42 4c 45 5f 45 58 50 45 4e 53 49 56 45 ENABLE_EXPENSIVE
1c50: 5f 41 53 53 45 52 54 22 2c 0a 23 65 6e 64 69 66 _ASSERT",.#endif
1c60: 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 .#if SQLITE_ENAB
1c70: 4c 45 5f 46 54 53 31 0a 20 20 22 45 4e 41 42 4c LE_FTS1. "ENABL
1c80: 45 5f 46 54 53 31 22 2c 0a 23 65 6e 64 69 66 0a E_FTS1",.#endif.
1c90: 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c #if SQLITE_ENABL
1ca0: 45 5f 46 54 53 32 0a 20 20 22 45 4e 41 42 4c 45 E_FTS2. "ENABLE
1cb0: 5f 46 54 53 32 22 2c 0a 23 65 6e 64 69 66 0a 23 _FTS2",.#endif.#
1cc0: 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 if SQLITE_ENABLE
1cd0: 5f 46 54 53 33 0a 20 20 22 45 4e 41 42 4c 45 5f _FTS3. "ENABLE_
1ce0: 46 54 53 33 22 2c 0a 23 65 6e 64 69 66 0a 23 69 FTS3",.#endif.#i
1cf0: 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f f SQLITE_ENABLE_
1d00: 46 54 53 33 5f 50 41 52 45 4e 54 48 45 53 49 53 FTS3_PARENTHESIS
1d10: 0a 20 20 22 45 4e 41 42 4c 45 5f 46 54 53 33 5f . "ENABLE_FTS3_
1d20: 50 41 52 45 4e 54 48 45 53 49 53 22 2c 0a 23 65 PARENTHESIS",.#e
1d30: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
1d40: 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 ENABLE_FTS3_TOKE
1d50: 4e 49 5a 45 52 0a 20 20 22 45 4e 41 42 4c 45 5f NIZER. "ENABLE_
1d60: 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 22 2c FTS3_TOKENIZER",
1d70: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
1d80: 54 45 5f 45 4e 41 42 4c 45 5f 46 54 53 34 0a 20 TE_ENABLE_FTS4.
1d90: 20 22 45 4e 41 42 4c 45 5f 46 54 53 34 22 2c 0a "ENABLE_FTS4",.
1da0: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
1db0: 45 5f 45 4e 41 42 4c 45 5f 46 54 53 35 0a 20 20 E_ENABLE_FTS5.
1dc0: 22 45 4e 41 42 4c 45 5f 46 54 53 35 22 2c 0a 23 "ENABLE_FTS5",.#
1dd0: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
1de0: 5f 45 4e 41 42 4c 45 5f 48 49 44 44 45 4e 5f 43 _ENABLE_HIDDEN_C
1df0: 4f 4c 55 4d 4e 53 0a 20 20 22 45 4e 41 42 4c 45 OLUMNS. "ENABLE
1e00: 5f 48 49 44 44 45 4e 5f 43 4f 4c 55 4d 4e 53 22 _HIDDEN_COLUMNS"
1e10: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
1e20: 49 54 45 5f 45 4e 41 42 4c 45 5f 49 43 55 0a 20 ITE_ENABLE_ICU.
1e30: 20 22 45 4e 41 42 4c 45 5f 49 43 55 22 2c 0a 23 "ENABLE_ICU",.#
1e40: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
1e50: 5f 45 4e 41 42 4c 45 5f 49 4f 54 52 41 43 45 0a _ENABLE_IOTRACE.
1e60: 20 20 22 45 4e 41 42 4c 45 5f 49 4f 54 52 41 43 "ENABLE_IOTRAC
1e70: 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 E",.#endif.#if S
1e80: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4a 53 4f QLITE_ENABLE_JSO
1e90: 4e 31 0a 20 20 22 45 4e 41 42 4c 45 5f 4a 53 4f N1. "ENABLE_JSO
1ea0: 4e 31 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 N1",.#endif.#if
1eb0: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c 4f SQLITE_ENABLE_LO
1ec0: 41 44 5f 45 58 54 45 4e 53 49 4f 4e 0a 20 20 22 AD_EXTENSION. "
1ed0: 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 ENABLE_LOAD_EXTE
1ee0: 4e 53 49 4f 4e 22 2c 0a 23 65 6e 64 69 66 0a 23 NSION",.#endif.#
1ef0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 ifdef SQLITE_ENA
1f00: 42 4c 45 5f 4c 4f 43 4b 49 4e 47 5f 53 54 59 4c BLE_LOCKING_STYL
1f10: 45 0a 20 20 22 45 4e 41 42 4c 45 5f 4c 4f 43 4b E. "ENABLE_LOCK
1f20: 49 4e 47 5f 53 54 59 4c 45 3d 22 20 43 54 49 4d ING_STYLE=" CTIM
1f30: 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f EOPT_VAL(SQLITE_
1f40: 45 4e 41 42 4c 45 5f 4c 4f 43 4b 49 4e 47 5f 53 ENABLE_LOCKING_S
1f50: 54 59 4c 45 29 2c 0a 23 65 6e 64 69 66 0a 23 69 TYLE),.#endif.#i
1f60: 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f f SQLITE_ENABLE_
1f70: 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e MEMORY_MANAGEMEN
1f80: 54 0a 20 20 22 45 4e 41 42 4c 45 5f 4d 45 4d 4f T. "ENABLE_MEMO
1f90: 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 22 2c 0a RY_MANAGEMENT",.
1fa0: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
1fb0: 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 E_ENABLE_MEMSYS3
1fc0: 0a 20 20 22 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 . "ENABLE_MEMSY
1fd0: 53 33 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 S3",.#endif.#if
1fe0: 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 SQLITE_ENABLE_ME
1ff0: 4d 53 59 53 35 0a 20 20 22 45 4e 41 42 4c 45 5f MSYS5. "ENABLE_
2000: 4d 45 4d 53 59 53 35 22 2c 0a 23 65 6e 64 69 66 MEMSYS5",.#endif
2010: 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 .#if SQLITE_ENAB
2020: 4c 45 5f 4d 55 4c 54 49 50 4c 45 58 0a 20 20 22 LE_MULTIPLEX. "
2030: 45 4e 41 42 4c 45 5f 4d 55 4c 54 49 50 4c 45 58 ENABLE_MULTIPLEX
2040: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
2050: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4e 55 4c 4c LITE_ENABLE_NULL
2060: 5f 54 52 49 4d 0a 20 20 22 45 4e 41 42 4c 45 5f _TRIM. "ENABLE_
2070: 4e 55 4c 4c 5f 54 52 49 4d 22 2c 0a 23 65 6e 64 NULL_TRIM",.#end
2080: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e if.#if SQLITE_EN
2090: 41 42 4c 45 5f 4f 56 45 52 53 49 5a 45 5f 43 45 ABLE_OVERSIZE_CE
20a0: 4c 4c 5f 43 48 45 43 4b 0a 20 20 22 45 4e 41 42 LL_CHECK. "ENAB
20b0: 4c 45 5f 4f 56 45 52 53 49 5a 45 5f 43 45 4c 4c LE_OVERSIZE_CELL
20c0: 5f 43 48 45 43 4b 22 2c 0a 23 65 6e 64 69 66 0a _CHECK",.#endif.
20d0: 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c #if SQLITE_ENABL
20e0: 45 5f 50 52 45 55 50 44 41 54 45 5f 48 4f 4f 4b E_PREUPDATE_HOOK
20f0: 0a 20 20 22 45 4e 41 42 4c 45 5f 50 52 45 55 50 . "ENABLE_PREUP
2100: 44 41 54 45 5f 48 4f 4f 4b 22 2c 0a 23 65 6e 64 DATE_HOOK",.#end
2110: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e if.#if SQLITE_EN
2120: 41 42 4c 45 5f 51 50 53 47 0a 20 20 22 45 4e 41 ABLE_QPSG. "ENA
2130: 42 4c 45 5f 51 50 53 47 22 2c 0a 23 65 6e 64 69 BLE_QPSG",.#endi
2140: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 f.#if SQLITE_ENA
2150: 42 4c 45 5f 52 42 55 0a 20 20 22 45 4e 41 42 4c BLE_RBU. "ENABL
2160: 45 5f 52 42 55 22 2c 0a 23 65 6e 64 69 66 0a 23 E_RBU",.#endif.#
2170: 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 if SQLITE_ENABLE
2180: 5f 52 54 52 45 45 0a 20 20 22 45 4e 41 42 4c 45 _RTREE. "ENABLE
2190: 5f 52 54 52 45 45 22 2c 0a 23 65 6e 64 69 66 0a _RTREE",.#endif.
21a0: 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c #if SQLITE_ENABL
21b0: 45 5f 53 45 4c 45 43 54 54 52 41 43 45 0a 20 20 E_SELECTTRACE.
21c0: 22 45 4e 41 42 4c 45 5f 53 45 4c 45 43 54 54 52 "ENABLE_SELECTTR
21d0: 41 43 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 ACE",.#endif.#if
21e0: 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 SQLITE_ENABLE_S
21f0: 45 53 53 49 4f 4e 0a 20 20 22 45 4e 41 42 4c 45 ESSION. "ENABLE
2200: 5f 53 45 53 53 49 4f 4e 22 2c 0a 23 65 6e 64 69 _SESSION",.#endi
2210: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 f.#if SQLITE_ENA
2220: 42 4c 45 5f 53 4e 41 50 53 48 4f 54 0a 20 20 22 BLE_SNAPSHOT. "
2230: 45 4e 41 42 4c 45 5f 53 4e 41 50 53 48 4f 54 22 ENABLE_SNAPSHOT"
2240: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
2250: 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f ITE_ENABLE_SQLLO
2260: 47 0a 20 20 22 45 4e 41 42 4c 45 5f 53 51 4c 4c G. "ENABLE_SQLL
2270: 4f 47 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 OG",.#endif.#if
2280: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 45 defined(SQLITE_E
2290: 4e 41 42 4c 45 5f 53 54 41 54 34 29 0a 20 20 22 NABLE_STAT4). "
22a0: 45 4e 41 42 4c 45 5f 53 54 41 54 34 22 2c 0a 23 ENABLE_STAT4",.#
22b0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 53 51 4c elif defined(SQL
22c0: 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 ITE_ENABLE_STAT3
22d0: 29 0a 20 20 22 45 4e 41 42 4c 45 5f 53 54 41 54 ). "ENABLE_STAT
22e0: 33 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 3",.#endif.#if S
22f0: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 4d QLITE_ENABLE_STM
2300: 54 56 54 41 42 0a 20 20 22 45 4e 41 42 4c 45 5f TVTAB. "ENABLE_
2310: 53 54 4d 54 56 54 41 42 22 2c 0a 23 65 6e 64 69 STMTVTAB",.#endi
2320: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e 41 f.#if SQLITE_ENA
2330: 42 4c 45 5f 53 54 4d 54 5f 53 43 41 4e 53 54 41 BLE_STMT_SCANSTA
2340: 54 55 53 0a 20 20 22 45 4e 41 42 4c 45 5f 53 54 TUS. "ENABLE_ST
2350: 4d 54 5f 53 43 41 4e 53 54 41 54 55 53 22 2c 0a MT_SCANSTATUS",.
2360: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
2370: 45 5f 45 4e 41 42 4c 45 5f 55 4e 4b 4e 4f 57 4e E_ENABLE_UNKNOWN
2380: 5f 53 51 4c 5f 46 55 4e 43 54 49 4f 4e 0a 20 20 _SQL_FUNCTION.
2390: 22 45 4e 41 42 4c 45 5f 55 4e 4b 4e 4f 57 4e 5f "ENABLE_UNKNOWN_
23a0: 53 51 4c 5f 46 55 4e 43 54 49 4f 4e 22 2c 0a 23 SQL_FUNCTION",.#
23b0: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
23c0: 5f 45 4e 41 42 4c 45 5f 55 4e 4c 4f 43 4b 5f 4e _ENABLE_UNLOCK_N
23d0: 4f 54 49 46 59 0a 20 20 22 45 4e 41 42 4c 45 5f OTIFY. "ENABLE_
23e0: 55 4e 4c 4f 43 4b 5f 4e 4f 54 49 46 59 22 2c 0a UNLOCK_NOTIFY",.
23f0: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
2400: 45 5f 45 4e 41 42 4c 45 5f 55 50 44 41 54 45 5f E_ENABLE_UPDATE_
2410: 44 45 4c 45 54 45 5f 4c 49 4d 49 54 0a 20 20 22 DELETE_LIMIT. "
2420: 45 4e 41 42 4c 45 5f 55 50 44 41 54 45 5f 44 45 ENABLE_UPDATE_DE
2430: 4c 45 54 45 5f 4c 49 4d 49 54 22 2c 0a 23 65 6e LETE_LIMIT",.#en
2440: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 dif.#if SQLITE_E
2450: 4e 41 42 4c 45 5f 55 52 49 5f 30 30 5f 45 52 52 NABLE_URI_00_ERR
2460: 4f 52 0a 20 20 22 45 4e 41 42 4c 45 5f 55 52 49 OR. "ENABLE_URI
2470: 5f 30 30 5f 45 52 52 4f 52 22 2c 0a 23 65 6e 64 _00_ERROR",.#end
2480: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 45 4e if.#if SQLITE_EN
2490: 41 42 4c 45 5f 56 46 53 54 52 41 43 45 0a 20 20 ABLE_VFSTRACE.
24a0: 22 45 4e 41 42 4c 45 5f 56 46 53 54 52 41 43 45 "ENABLE_VFSTRACE
24b0: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
24c0: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 57 48 45 52 LITE_ENABLE_WHER
24d0: 45 54 52 41 43 45 0a 20 20 22 45 4e 41 42 4c 45 ETRACE. "ENABLE
24e0: 5f 57 48 45 52 45 54 52 41 43 45 22 2c 0a 23 65 _WHERETRACE",.#e
24f0: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
2500: 45 4e 41 42 4c 45 5f 5a 49 50 56 46 53 0a 20 20 ENABLE_ZIPVFS.
2510: 22 45 4e 41 42 4c 45 5f 5a 49 50 56 46 53 22 2c "ENABLE_ZIPVFS",
2520: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
2530: 54 45 5f 45 58 50 4c 41 49 4e 5f 45 53 54 49 4d TE_EXPLAIN_ESTIM
2540: 41 54 45 44 5f 52 4f 57 53 0a 20 20 22 45 58 50 ATED_ROWS. "EXP
2550: 4c 41 49 4e 5f 45 53 54 49 4d 41 54 45 44 5f 52 LAIN_ESTIMATED_R
2560: 4f 57 53 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 OWS",.#endif.#if
2570: 20 53 51 4c 49 54 45 5f 45 58 54 52 41 5f 49 46 SQLITE_EXTRA_IF
2580: 4e 55 4c 4c 52 4f 57 0a 20 20 22 45 58 54 52 41 NULLROW. "EXTRA
2590: 5f 49 46 4e 55 4c 4c 52 4f 57 22 2c 0a 23 65 6e _IFNULLROW",.#en
25a0: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 dif.#ifdef SQLIT
25b0: 45 5f 45 58 54 52 41 5f 49 4e 49 54 0a 20 20 22 E_EXTRA_INIT. "
25c0: 45 58 54 52 41 5f 49 4e 49 54 3d 22 20 43 54 49 EXTRA_INIT=" CTI
25d0: 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 MEOPT_VAL(SQLITE
25e0: 5f 45 58 54 52 41 5f 49 4e 49 54 29 2c 0a 23 65 _EXTRA_INIT),.#e
25f0: 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 ndif.#ifdef SQLI
2600: 54 45 5f 45 58 54 52 41 5f 53 48 55 54 44 4f 57 TE_EXTRA_SHUTDOW
2610: 4e 0a 20 20 22 45 58 54 52 41 5f 53 48 55 54 44 N. "EXTRA_SHUTD
2620: 4f 57 4e 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 OWN=" CTIMEOPT_V
2630: 41 4c 28 53 51 4c 49 54 45 5f 45 58 54 52 41 5f AL(SQLITE_EXTRA_
2640: 53 48 55 54 44 4f 57 4e 29 2c 0a 23 65 6e 64 69 SHUTDOWN),.#endi
2650: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
2660: 46 54 53 33 5f 4d 41 58 5f 45 58 50 52 5f 44 45 FTS3_MAX_EXPR_DE
2670: 50 54 48 0a 20 20 22 46 54 53 33 5f 4d 41 58 5f PTH. "FTS3_MAX_
2680: 45 58 50 52 5f 44 45 50 54 48 3d 22 20 43 54 49 EXPR_DEPTH=" CTI
2690: 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 MEOPT_VAL(SQLITE
26a0: 5f 46 54 53 33 5f 4d 41 58 5f 45 58 50 52 5f 44 _FTS3_MAX_EXPR_D
26b0: 45 50 54 48 29 2c 0a 23 65 6e 64 69 66 0a 23 69 EPTH),.#endif.#i
26c0: 66 20 53 51 4c 49 54 45 5f 46 54 53 35 5f 45 4e f SQLITE_FTS5_EN
26d0: 41 42 4c 45 5f 54 45 53 54 5f 4d 49 0a 20 20 22 ABLE_TEST_MI. "
26e0: 46 54 53 35 5f 45 4e 41 42 4c 45 5f 54 45 53 54 FTS5_ENABLE_TEST
26f0: 5f 4d 49 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 _MI",.#endif.#if
2700: 20 53 51 4c 49 54 45 5f 46 54 53 35 5f 4e 4f 5f SQLITE_FTS5_NO_
2710: 57 49 54 48 4f 55 54 5f 52 4f 57 49 44 0a 20 20 WITHOUT_ROWID.
2720: 22 46 54 53 35 5f 4e 4f 5f 57 49 54 48 4f 55 54 "FTS5_NO_WITHOUT
2730: 5f 52 4f 57 49 44 22 2c 0a 23 65 6e 64 69 66 0a _ROWID",.#endif.
2740: 23 69 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 #if SQLITE_HAS_C
2750: 4f 44 45 43 0a 20 20 22 48 41 53 5f 43 4f 44 45 ODEC. "HAS_CODE
2760: 43 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 48 C",.#endif.#if H
2770: 41 56 45 5f 49 53 4e 41 4e 20 7c 7c 20 53 51 4c AVE_ISNAN || SQL
2780: 49 54 45 5f 48 41 56 45 5f 49 53 4e 41 4e 0a 20 ITE_HAVE_ISNAN.
2790: 20 22 48 41 56 45 5f 49 53 4e 41 4e 22 2c 0a 23 "HAVE_ISNAN",.#
27a0: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
27b0: 5f 48 4f 4d 45 47 52 4f 57 4e 5f 52 45 43 55 52 _HOMEGROWN_RECUR
27c0: 53 49 56 45 5f 4d 55 54 45 58 0a 20 20 22 48 4f SIVE_MUTEX. "HO
27d0: 4d 45 47 52 4f 57 4e 5f 52 45 43 55 52 53 49 56 MEGROWN_RECURSIV
27e0: 45 5f 4d 55 54 45 58 22 2c 0a 23 65 6e 64 69 66 E_MUTEX",.#endif
27f0: 0a 23 69 66 20 53 51 4c 49 54 45 5f 49 47 4e 4f .#if SQLITE_IGNO
2800: 52 45 5f 41 46 50 5f 4c 4f 43 4b 5f 45 52 52 4f RE_AFP_LOCK_ERRO
2810: 52 53 0a 20 20 22 49 47 4e 4f 52 45 5f 41 46 50 RS. "IGNORE_AFP
2820: 5f 4c 4f 43 4b 5f 45 52 52 4f 52 53 22 2c 0a 23 _LOCK_ERRORS",.#
2830: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
2840: 5f 49 47 4e 4f 52 45 5f 46 4c 4f 43 4b 5f 4c 4f _IGNORE_FLOCK_LO
2850: 43 4b 5f 45 52 52 4f 52 53 0a 20 20 22 49 47 4e CK_ERRORS. "IGN
2860: 4f 52 45 5f 46 4c 4f 43 4b 5f 4c 4f 43 4b 5f 45 ORE_FLOCK_LOCK_E
2870: 52 52 4f 52 53 22 2c 0a 23 65 6e 64 69 66 0a 23 RRORS",.#endif.#
2880: 69 66 20 53 51 4c 49 54 45 5f 49 4e 4c 49 4e 45 if SQLITE_INLINE
2890: 5f 4d 45 4d 43 50 59 0a 20 20 22 49 4e 4c 49 4e _MEMCPY. "INLIN
28a0: 45 5f 4d 45 4d 43 50 59 22 2c 0a 23 65 6e 64 69 E_MEMCPY",.#endi
28b0: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 49 4e 54 f.#if SQLITE_INT
28c0: 36 34 5f 54 59 50 45 0a 20 20 22 49 4e 54 36 34 64_TYPE. "INT64
28d0: 5f 54 59 50 45 22 2c 0a 23 65 6e 64 69 66 0a 23 _TYPE",.#endif.#
28e0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 ifdef SQLITE_INT
28f0: 45 47 52 49 54 59 5f 43 48 45 43 4b 5f 45 52 52 EGRITY_CHECK_ERR
2900: 4f 52 5f 4d 41 58 0a 20 20 22 49 4e 54 45 47 52 OR_MAX. "INTEGR
2910: 49 54 59 5f 43 48 45 43 4b 5f 45 52 52 4f 52 5f ITY_CHECK_ERROR_
2920: 4d 41 58 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 MAX=" CTIMEOPT_V
2930: 41 4c 28 53 51 4c 49 54 45 5f 49 4e 54 45 47 52 AL(SQLITE_INTEGR
2940: 49 54 59 5f 43 48 45 43 4b 5f 45 52 52 4f 52 5f ITY_CHECK_ERROR_
2950: 4d 41 58 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 MAX),.#endif.#if
2960: 20 53 51 4c 49 54 45 5f 4c 49 4b 45 5f 44 4f 45 SQLITE_LIKE_DOE
2970: 53 4e 54 5f 4d 41 54 43 48 5f 42 4c 4f 42 53 0a SNT_MATCH_BLOBS.
2980: 20 20 22 4c 49 4b 45 5f 44 4f 45 53 4e 54 5f 4d "LIKE_DOESNT_M
2990: 41 54 43 48 5f 42 4c 4f 42 53 22 2c 0a 23 65 6e ATCH_BLOBS",.#en
29a0: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4c dif.#if SQLITE_L
29b0: 4f 43 4b 5f 54 52 41 43 45 0a 20 20 22 4c 4f 43 OCK_TRACE. "LOC
29c0: 4b 5f 54 52 41 43 45 22 2c 0a 23 65 6e 64 69 66 K_TRACE",.#endif
29d0: 0a 23 69 66 20 53 51 4c 49 54 45 5f 4c 4f 47 5f .#if SQLITE_LOG_
29e0: 43 41 43 48 45 5f 53 50 49 4c 4c 0a 20 20 22 4c CACHE_SPILL. "L
29f0: 4f 47 5f 43 41 43 48 45 5f 53 50 49 4c 4c 22 2c OG_CACHE_SPILL",
2a00: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 .#endif.#ifdef S
2a10: 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 QLITE_MALLOC_SOF
2a20: 54 5f 4c 49 4d 49 54 0a 20 20 22 4d 41 4c 4c 4f T_LIMIT. "MALLO
2a30: 43 5f 53 4f 46 54 5f 4c 49 4d 49 54 3d 22 20 43 C_SOFT_LIMIT=" C
2a40: 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 TIMEOPT_VAL(SQLI
2a50: 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f 4c TE_MALLOC_SOFT_L
2a60: 49 4d 49 54 29 2c 0a 23 65 6e 64 69 66 0a 23 69 IMIT),.#endif.#i
2a70: 66 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f fdef SQLITE_MAX_
2a80: 41 54 54 41 43 48 45 44 0a 20 20 22 4d 41 58 5f ATTACHED. "MAX_
2a90: 41 54 54 41 43 48 45 44 3d 22 20 43 54 49 4d 45 ATTACHED=" CTIME
2aa0: 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 4d OPT_VAL(SQLITE_M
2ab0: 41 58 5f 41 54 54 41 43 48 45 44 29 2c 0a 23 65 AX_ATTACHED),.#e
2ac0: 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 ndif.#ifdef SQLI
2ad0: 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 0a 20 20 TE_MAX_COLUMN.
2ae0: 22 4d 41 58 5f 43 4f 4c 55 4d 4e 3d 22 20 43 54 "MAX_COLUMN=" CT
2af0: 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 IMEOPT_VAL(SQLIT
2b00: 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 29 2c 0a 23 E_MAX_COLUMN),.#
2b10: 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c endif.#ifdef SQL
2b20: 49 54 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 ITE_MAX_COMPOUND
2b30: 5f 53 45 4c 45 43 54 0a 20 20 22 4d 41 58 5f 43 _SELECT. "MAX_C
2b40: 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3d 22 OMPOUND_SELECT="
2b50: 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 CTIMEOPT_VAL(SQ
2b60: 4c 49 54 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e LITE_MAX_COMPOUN
2b70: 44 5f 53 45 4c 45 43 54 29 2c 0a 23 65 6e 64 69 D_SELECT),.#endi
2b80: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
2b90: 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 MAX_DEFAULT_PAGE
2ba0: 5f 53 49 5a 45 0a 20 20 22 4d 41 58 5f 44 45 46 _SIZE. "MAX_DEF
2bb0: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 3d 22 AULT_PAGE_SIZE="
2bc0: 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 CTIMEOPT_VAL(SQ
2bd0: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 LITE_MAX_DEFAULT
2be0: 5f 50 41 47 45 5f 53 49 5a 45 29 2c 0a 23 65 6e _PAGE_SIZE),.#en
2bf0: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 dif.#ifdef SQLIT
2c00: 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54 48 E_MAX_EXPR_DEPTH
2c10: 0a 20 20 22 4d 41 58 5f 45 58 50 52 5f 44 45 50 . "MAX_EXPR_DEP
2c20: 54 48 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 TH=" CTIMEOPT_VA
2c30: 4c 28 53 51 4c 49 54 45 5f 4d 41 58 5f 45 58 50 L(SQLITE_MAX_EXP
2c40: 52 5f 44 45 50 54 48 29 2c 0a 23 65 6e 64 69 66 R_DEPTH),.#endif
2c50: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4d .#ifdef SQLITE_M
2c60: 41 58 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 0a AX_FUNCTION_ARG.
2c70: 20 20 22 4d 41 58 5f 46 55 4e 43 54 49 4f 4e 5f "MAX_FUNCTION_
2c80: 41 52 47 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 ARG=" CTIMEOPT_V
2c90: 41 4c 28 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 AL(SQLITE_MAX_FU
2ca0: 4e 43 54 49 4f 4e 5f 41 52 47 29 2c 0a 23 65 6e NCTION_ARG),.#en
2cb0: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 dif.#ifdef SQLIT
2cc0: 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 0a 20 20 22 E_MAX_LENGTH. "
2cd0: 4d 41 58 5f 4c 45 4e 47 54 48 3d 22 20 43 54 49 MAX_LENGTH=" CTI
2ce0: 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 MEOPT_VAL(SQLITE
2cf0: 5f 4d 41 58 5f 4c 45 4e 47 54 48 29 2c 0a 23 65 _MAX_LENGTH),.#e
2d00: 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 ndif.#ifdef SQLI
2d10: 54 45 5f 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 TE_MAX_LIKE_PATT
2d20: 45 52 4e 5f 4c 45 4e 47 54 48 0a 20 20 22 4d 41 ERN_LENGTH. "MA
2d30: 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c X_LIKE_PATTERN_L
2d40: 45 4e 47 54 48 3d 22 20 43 54 49 4d 45 4f 50 54 ENGTH=" CTIMEOPT
2d50: 5f 56 41 4c 28 53 51 4c 49 54 45 5f 4d 41 58 5f _VAL(SQLITE_MAX_
2d60: 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e LIKE_PATTERN_LEN
2d70: 47 54 48 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 GTH),.#endif.#if
2d80: 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4d def SQLITE_MAX_M
2d90: 45 4d 4f 52 59 0a 20 20 22 4d 41 58 5f 4d 45 4d EMORY. "MAX_MEM
2da0: 4f 52 59 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 ORY=" CTIMEOPT_V
2db0: 41 4c 28 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 45 AL(SQLITE_MAX_ME
2dc0: 4d 4f 52 59 29 2c 0a 23 65 6e 64 69 66 0a 23 69 MORY),.#endif.#i
2dd0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f fdef SQLITE_MAX_
2de0: 4d 4d 41 50 5f 53 49 5a 45 0a 20 20 22 4d 41 58 MMAP_SIZE. "MAX
2df0: 5f 4d 4d 41 50 5f 53 49 5a 45 3d 22 20 43 54 49 _MMAP_SIZE=" CTI
2e00: 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 MEOPT_VAL(SQLITE
2e10: 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 29 2c _MAX_MMAP_SIZE),
2e20: 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 .#endif.#ifdef S
2e30: 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 QLITE_MAX_MMAP_S
2e40: 49 5a 45 5f 0a 20 20 22 4d 41 58 5f 4d 4d 41 50 IZE_. "MAX_MMAP
2e50: 5f 53 49 5a 45 5f 3d 22 20 43 54 49 4d 45 4f 50 _SIZE_=" CTIMEOP
2e60: 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 4d 41 58 T_VAL(SQLITE_MAX
2e70: 5f 4d 4d 41 50 5f 53 49 5a 45 5f 29 2c 0a 23 65 _MMAP_SIZE_),.#e
2e80: 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 ndif.#ifdef SQLI
2e90: 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43 4f 55 4e TE_MAX_PAGE_COUN
2ea0: 54 0a 20 20 22 4d 41 58 5f 50 41 47 45 5f 43 4f T. "MAX_PAGE_CO
2eb0: 55 4e 54 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 UNT=" CTIMEOPT_V
2ec0: 41 4c 28 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 AL(SQLITE_MAX_PA
2ed0: 47 45 5f 43 4f 55 4e 54 29 2c 0a 23 65 6e 64 69 GE_COUNT),.#endi
2ee0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
2ef0: 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 20 20 MAX_PAGE_SIZE.
2f00: 22 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 3d 22 "MAX_PAGE_SIZE="
2f10: 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 CTIMEOPT_VAL(SQ
2f20: 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 LITE_MAX_PAGE_SI
2f30: 5a 45 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 ZE),.#endif.#ifd
2f40: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 ef SQLITE_MAX_SC
2f50: 48 45 4d 41 5f 52 45 54 52 59 0a 20 20 22 4d 41 HEMA_RETRY. "MA
2f60: 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 3d 22 X_SCHEMA_RETRY="
2f70: 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 CTIMEOPT_VAL(SQ
2f80: 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f LITE_MAX_SCHEMA_
2f90: 52 45 54 52 59 29 2c 0a 23 65 6e 64 69 66 0a 23 RETRY),.#endif.#
2fa0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 ifdef SQLITE_MAX
2fb0: 5f 53 51 4c 5f 4c 45 4e 47 54 48 0a 20 20 22 4d _SQL_LENGTH. "M
2fc0: 41 58 5f 53 51 4c 5f 4c 45 4e 47 54 48 3d 22 20 AX_SQL_LENGTH="
2fd0: 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c CTIMEOPT_VAL(SQL
2fe0: 49 54 45 5f 4d 41 58 5f 53 51 4c 5f 4c 45 4e 47 ITE_MAX_SQL_LENG
2ff0: 54 48 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 TH),.#endif.#ifd
3000: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 54 52 ef SQLITE_MAX_TR
3010: 49 47 47 45 52 5f 44 45 50 54 48 0a 20 20 22 4d IGGER_DEPTH. "M
3020: 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 AX_TRIGGER_DEPTH
3030: 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 =" CTIMEOPT_VAL(
3040: 53 51 4c 49 54 45 5f 4d 41 58 5f 54 52 49 47 47 SQLITE_MAX_TRIGG
3050: 45 52 5f 44 45 50 54 48 29 2c 0a 23 65 6e 64 69 ER_DEPTH),.#endi
3060: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
3070: 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d MAX_VARIABLE_NUM
3080: 42 45 52 0a 20 20 22 4d 41 58 5f 56 41 52 49 41 BER. "MAX_VARIA
3090: 42 4c 45 5f 4e 55 4d 42 45 52 3d 22 20 43 54 49 BLE_NUMBER=" CTI
30a0: 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 MEOPT_VAL(SQLITE
30b0: 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55 _MAX_VARIABLE_NU
30c0: 4d 42 45 52 29 2c 0a 23 65 6e 64 69 66 0a 23 69 MBER),.#endif.#i
30d0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f fdef SQLITE_MAX_
30e0: 56 44 42 45 5f 4f 50 0a 20 20 22 4d 41 58 5f 56 VDBE_OP. "MAX_V
30f0: 44 42 45 5f 4f 50 3d 22 20 43 54 49 4d 45 4f 50 DBE_OP=" CTIMEOP
3100: 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 4d 41 58 T_VAL(SQLITE_MAX
3110: 5f 56 44 42 45 5f 4f 50 29 2c 0a 23 65 6e 64 69 _VDBE_OP),.#endi
3120: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
3130: 4d 41 58 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 MAX_WORKER_THREA
3140: 44 53 0a 20 20 22 4d 41 58 5f 57 4f 52 4b 45 52 DS. "MAX_WORKER
3150: 5f 54 48 52 45 41 44 53 3d 22 20 43 54 49 4d 45 _THREADS=" CTIME
3160: 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 5f 4d OPT_VAL(SQLITE_M
3170: 41 58 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 AX_WORKER_THREAD
3180: 53 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 S),.#endif.#if S
3190: 51 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 0a 20 QLITE_MEMDEBUG.
31a0: 20 22 4d 45 4d 44 45 42 55 47 22 2c 0a 23 65 6e "MEMDEBUG",.#en
31b0: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4d dif.#if SQLITE_M
31c0: 49 58 45 44 5f 45 4e 44 49 41 4e 5f 36 34 42 49 IXED_ENDIAN_64BI
31d0: 54 5f 46 4c 4f 41 54 0a 20 20 22 4d 49 58 45 44 T_FLOAT. "MIXED
31e0: 5f 45 4e 44 49 41 4e 5f 36 34 42 49 54 5f 46 4c _ENDIAN_64BIT_FL
31f0: 4f 41 54 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 OAT",.#endif.#if
3200: 20 53 51 4c 49 54 45 5f 4d 4d 41 50 5f 52 45 41 SQLITE_MMAP_REA
3210: 44 57 52 49 54 45 0a 20 20 22 4d 4d 41 50 5f 52 DWRITE. "MMAP_R
3220: 45 41 44 57 52 49 54 45 22 2c 0a 23 65 6e 64 69 EADWRITE",.#endi
3230: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4d 55 54 f.#if SQLITE_MUT
3240: 45 58 5f 4e 4f 4f 50 0a 20 20 22 4d 55 54 45 58 EX_NOOP. "MUTEX
3250: 5f 4e 4f 4f 50 22 2c 0a 23 65 6e 64 69 66 0a 23 _NOOP",.#endif.#
3260: 69 66 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f if SQLITE_MUTEX_
3270: 4e 52 45 46 0a 20 20 22 4d 55 54 45 58 5f 4e 52 NREF. "MUTEX_NR
3280: 45 46 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 EF",.#endif.#if
3290: 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 4f 4d 49 SQLITE_MUTEX_OMI
32a0: 54 0a 20 20 22 4d 55 54 45 58 5f 4f 4d 49 54 22 T. "MUTEX_OMIT"
32b0: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
32c0: 49 54 45 5f 4d 55 54 45 58 5f 50 54 48 52 45 41 ITE_MUTEX_PTHREA
32d0: 44 53 0a 20 20 22 4d 55 54 45 58 5f 50 54 48 52 DS. "MUTEX_PTHR
32e0: 45 41 44 53 22 2c 0a 23 65 6e 64 69 66 0a 23 69 EADS",.#endif.#i
32f0: 66 20 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 57 f SQLITE_MUTEX_W
3300: 33 32 0a 20 20 22 4d 55 54 45 58 5f 57 33 32 22 32. "MUTEX_W32"
3310: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
3320: 49 54 45 5f 4e 45 45 44 5f 45 52 52 5f 4e 41 4d ITE_NEED_ERR_NAM
3330: 45 0a 20 20 22 4e 45 45 44 5f 45 52 52 5f 4e 41 E. "NEED_ERR_NA
3340: 4d 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 ME",.#endif.#if
3350: 53 51 4c 49 54 45 5f 4e 4f 49 4e 4c 49 4e 45 0a SQLITE_NOINLINE.
3360: 20 20 22 4e 4f 49 4e 4c 49 4e 45 22 2c 0a 23 65 "NOINLINE",.#e
3370: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
3380: 4e 4f 5f 53 59 4e 43 0a 20 20 22 4e 4f 5f 53 59 NO_SYNC. "NO_SY
3390: 4e 43 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 NC",.#endif.#if
33a0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 4c 54 45 SQLITE_OMIT_ALTE
33b0: 52 54 41 42 4c 45 0a 20 20 22 4f 4d 49 54 5f 41 RTABLE. "OMIT_A
33c0: 4c 54 45 52 54 41 42 4c 45 22 2c 0a 23 65 6e 64 LTERTABLE",.#end
33d0: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d if.#if SQLITE_OM
33e0: 49 54 5f 41 4e 41 4c 59 5a 45 0a 20 20 22 4f 4d IT_ANALYZE. "OM
33f0: 49 54 5f 41 4e 41 4c 59 5a 45 22 2c 0a 23 65 6e IT_ANALYZE",.#en
3400: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f dif.#if SQLITE_O
3410: 4d 49 54 5f 41 54 54 41 43 48 0a 20 20 22 4f 4d MIT_ATTACH. "OM
3420: 49 54 5f 41 54 54 41 43 48 22 2c 0a 23 65 6e 64 IT_ATTACH",.#end
3430: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d if.#if SQLITE_OM
3440: 49 54 5f 41 55 54 48 4f 52 49 5a 41 54 49 4f 4e IT_AUTHORIZATION
3450: 0a 20 20 22 4f 4d 49 54 5f 41 55 54 48 4f 52 49 . "OMIT_AUTHORI
3460: 5a 41 54 49 4f 4e 22 2c 0a 23 65 6e 64 69 66 0a ZATION",.#endif.
3470: 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f #if SQLITE_OMIT_
3480: 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 0a 20 20 AUTOINCREMENT.
3490: 22 4f 4d 49 54 5f 41 55 54 4f 49 4e 43 52 45 4d "OMIT_AUTOINCREM
34a0: 45 4e 54 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 ENT",.#endif.#if
34b0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 SQLITE_OMIT_AUT
34c0: 4f 49 4e 49 54 0a 20 20 22 4f 4d 49 54 5f 41 55 OINIT. "OMIT_AU
34d0: 54 4f 49 4e 49 54 22 2c 0a 23 65 6e 64 69 66 0a TOINIT",.#endif.
34e0: 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f #if SQLITE_OMIT_
34f0: 41 55 54 4f 4d 41 54 49 43 5f 49 4e 44 45 58 0a AUTOMATIC_INDEX.
3500: 20 20 22 4f 4d 49 54 5f 41 55 54 4f 4d 41 54 49 "OMIT_AUTOMATI
3510: 43 5f 49 4e 44 45 58 22 2c 0a 23 65 6e 64 69 66 C_INDEX",.#endif
3520: 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 .#if SQLITE_OMIT
3530: 5f 41 55 54 4f 52 45 53 45 54 0a 20 20 22 4f 4d _AUTORESET. "OM
3540: 49 54 5f 41 55 54 4f 52 45 53 45 54 22 2c 0a 23 IT_AUTORESET",.#
3550: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
3560: 5f 4f 4d 49 54 5f 41 55 54 4f 56 41 43 55 55 4d _OMIT_AUTOVACUUM
3570: 0a 20 20 22 4f 4d 49 54 5f 41 55 54 4f 56 41 43 . "OMIT_AUTOVAC
3580: 55 55 4d 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 UUM",.#endif.#if
3590: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 42 45 54 SQLITE_OMIT_BET
35a0: 57 45 45 4e 5f 4f 50 54 49 4d 49 5a 41 54 49 4f WEEN_OPTIMIZATIO
35b0: 4e 0a 20 20 22 4f 4d 49 54 5f 42 45 54 57 45 45 N. "OMIT_BETWEE
35c0: 4e 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 22 2c N_OPTIMIZATION",
35d0: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
35e0: 54 45 5f 4f 4d 49 54 5f 42 4c 4f 42 5f 4c 49 54 TE_OMIT_BLOB_LIT
35f0: 45 52 41 4c 0a 20 20 22 4f 4d 49 54 5f 42 4c 4f ERAL. "OMIT_BLO
3600: 42 5f 4c 49 54 45 52 41 4c 22 2c 0a 23 65 6e 64 B_LITERAL",.#end
3610: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d if.#if SQLITE_OM
3620: 49 54 5f 42 54 52 45 45 43 4f 55 4e 54 0a 20 20 IT_BTREECOUNT.
3630: 22 4f 4d 49 54 5f 42 54 52 45 45 43 4f 55 4e 54 "OMIT_BTREECOUNT
3640: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
3650: 4c 49 54 45 5f 4f 4d 49 54 5f 43 41 53 54 0a 20 LITE_OMIT_CAST.
3660: 20 22 4f 4d 49 54 5f 43 41 53 54 22 2c 0a 23 65 "OMIT_CAST",.#e
3670: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
3680: 4f 4d 49 54 5f 43 48 45 43 4b 0a 20 20 22 4f 4d OMIT_CHECK. "OM
3690: 49 54 5f 43 48 45 43 4b 22 2c 0a 23 65 6e 64 69 IT_CHECK",.#endi
36a0: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 f.#if SQLITE_OMI
36b0: 54 5f 43 4f 4d 50 4c 45 54 45 0a 20 20 22 4f 4d T_COMPLETE. "OM
36c0: 49 54 5f 43 4f 4d 50 4c 45 54 45 22 2c 0a 23 65 IT_COMPLETE",.#e
36d0: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
36e0: 4f 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 OMIT_COMPOUND_SE
36f0: 4c 45 43 54 0a 20 20 22 4f 4d 49 54 5f 43 4f 4d LECT. "OMIT_COM
3700: 50 4f 55 4e 44 5f 53 45 4c 45 43 54 22 2c 0a 23 POUND_SELECT",.#
3710: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
3720: 5f 4f 4d 49 54 5f 43 4f 4e 46 4c 49 43 54 5f 43 _OMIT_CONFLICT_C
3730: 4c 41 55 53 45 0a 20 20 22 4f 4d 49 54 5f 43 4f LAUSE. "OMIT_CO
3740: 4e 46 4c 49 43 54 5f 43 4c 41 55 53 45 22 2c 0a NFLICT_CLAUSE",.
3750: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
3760: 45 5f 4f 4d 49 54 5f 43 54 45 0a 20 20 22 4f 4d E_OMIT_CTE. "OM
3770: 49 54 5f 43 54 45 22 2c 0a 23 65 6e 64 69 66 0a IT_CTE",.#endif.
3780: 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f #if SQLITE_OMIT_
3790: 44 41 54 45 54 49 4d 45 5f 46 55 4e 43 53 0a 20 DATETIME_FUNCS.
37a0: 20 22 4f 4d 49 54 5f 44 41 54 45 54 49 4d 45 5f "OMIT_DATETIME_
37b0: 46 55 4e 43 53 22 2c 0a 23 65 6e 64 69 66 0a 23 FUNCS",.#endif.#
37c0: 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 if SQLITE_OMIT_D
37d0: 45 43 4c 54 59 50 45 0a 20 20 22 4f 4d 49 54 5f ECLTYPE. "OMIT_
37e0: 44 45 43 4c 54 59 50 45 22 2c 0a 23 65 6e 64 69 DECLTYPE",.#endi
37f0: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 f.#if SQLITE_OMI
3800: 54 5f 44 45 50 52 45 43 41 54 45 44 0a 20 20 22 T_DEPRECATED. "
3810: 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 22 OMIT_DEPRECATED"
3820: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
3830: 49 54 45 5f 4f 4d 49 54 5f 44 49 53 4b 49 4f 0a ITE_OMIT_DISKIO.
3840: 20 20 22 4f 4d 49 54 5f 44 49 53 4b 49 4f 22 2c "OMIT_DISKIO",
3850: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
3860: 54 45 5f 4f 4d 49 54 5f 45 58 50 4c 41 49 4e 0a TE_OMIT_EXPLAIN.
3870: 20 20 22 4f 4d 49 54 5f 45 58 50 4c 41 49 4e 22 "OMIT_EXPLAIN"
3880: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
3890: 49 54 45 5f 4f 4d 49 54 5f 46 4c 41 47 5f 50 52 ITE_OMIT_FLAG_PR
38a0: 41 47 4d 41 53 0a 20 20 22 4f 4d 49 54 5f 46 4c AGMAS. "OMIT_FL
38b0: 41 47 5f 50 52 41 47 4d 41 53 22 2c 0a 23 65 6e AG_PRAGMAS",.#en
38c0: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f dif.#if SQLITE_O
38d0: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 MIT_FLOATING_POI
38e0: 4e 54 0a 20 20 22 4f 4d 49 54 5f 46 4c 4f 41 54 NT. "OMIT_FLOAT
38f0: 49 4e 47 5f 50 4f 49 4e 54 22 2c 0a 23 65 6e 64 ING_POINT",.#end
3900: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d if.#if SQLITE_OM
3910: 49 54 5f 46 4f 52 45 49 47 4e 5f 4b 45 59 0a 20 IT_FOREIGN_KEY.
3920: 20 22 4f 4d 49 54 5f 46 4f 52 45 49 47 4e 5f 4b "OMIT_FOREIGN_K
3930: 45 59 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 EY",.#endif.#if
3940: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 47 45 54 5f SQLITE_OMIT_GET_
3950: 54 41 42 4c 45 0a 20 20 22 4f 4d 49 54 5f 47 45 TABLE. "OMIT_GE
3960: 54 5f 54 41 42 4c 45 22 2c 0a 23 65 6e 64 69 66 T_TABLE",.#endif
3970: 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 .#if SQLITE_OMIT
3980: 5f 48 45 58 5f 49 4e 54 45 47 45 52 0a 20 20 22 _HEX_INTEGER. "
3990: 4f 4d 49 54 5f 48 45 58 5f 49 4e 54 45 47 45 52 OMIT_HEX_INTEGER
39a0: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
39b0: 4c 49 54 45 5f 4f 4d 49 54 5f 49 4e 43 52 42 4c LITE_OMIT_INCRBL
39c0: 4f 42 0a 20 20 22 4f 4d 49 54 5f 49 4e 43 52 42 OB. "OMIT_INCRB
39d0: 4c 4f 42 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 LOB",.#endif.#if
39e0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 49 4e 54 SQLITE_OMIT_INT
39f0: 45 47 52 49 54 59 5f 43 48 45 43 4b 0a 20 20 22 EGRITY_CHECK. "
3a00: 4f 4d 49 54 5f 49 4e 54 45 47 52 49 54 59 5f 43 OMIT_INTEGRITY_C
3a10: 48 45 43 4b 22 2c 0a 23 65 6e 64 69 66 0a 23 69 HECK",.#endif.#i
3a20: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4c 49 f SQLITE_OMIT_LI
3a30: 4b 45 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 0a KE_OPTIMIZATION.
3a40: 20 20 22 4f 4d 49 54 5f 4c 49 4b 45 5f 4f 50 54 "OMIT_LIKE_OPT
3a50: 49 4d 49 5a 41 54 49 4f 4e 22 2c 0a 23 65 6e 64 IMIZATION",.#end
3a60: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d if.#if SQLITE_OM
3a70: 49 54 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f IT_LOAD_EXTENSIO
3a80: 4e 0a 20 20 22 4f 4d 49 54 5f 4c 4f 41 44 5f 45 N. "OMIT_LOAD_E
3a90: 58 54 45 4e 53 49 4f 4e 22 2c 0a 23 65 6e 64 69 XTENSION",.#endi
3aa0: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 f.#if SQLITE_OMI
3ab0: 54 5f 4c 4f 43 41 4c 54 49 4d 45 0a 20 20 22 4f T_LOCALTIME. "O
3ac0: 4d 49 54 5f 4c 4f 43 41 4c 54 49 4d 45 22 2c 0a MIT_LOCALTIME",.
3ad0: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
3ae0: 45 5f 4f 4d 49 54 5f 4c 4f 4f 4b 41 53 49 44 45 E_OMIT_LOOKASIDE
3af0: 0a 20 20 22 4f 4d 49 54 5f 4c 4f 4f 4b 41 53 49 . "OMIT_LOOKASI
3b00: 44 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 DE",.#endif.#if
3b10: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f SQLITE_OMIT_MEMO
3b20: 52 59 44 42 0a 20 20 22 4f 4d 49 54 5f 4d 45 4d RYDB. "OMIT_MEM
3b30: 4f 52 59 44 42 22 2c 0a 23 65 6e 64 69 66 0a 23 ORYDB",.#endif.#
3b40: 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4f if SQLITE_OMIT_O
3b50: 52 5f 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 0a 20 R_OPTIMIZATION.
3b60: 20 22 4f 4d 49 54 5f 4f 52 5f 4f 50 54 49 4d 49 "OMIT_OR_OPTIMI
3b70: 5a 41 54 49 4f 4e 22 2c 0a 23 65 6e 64 69 66 0a ZATION",.#endif.
3b80: 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f #if SQLITE_OMIT_
3b90: 50 41 47 45 52 5f 50 52 41 47 4d 41 53 0a 20 20 PAGER_PRAGMAS.
3ba0: 22 4f 4d 49 54 5f 50 41 47 45 52 5f 50 52 41 47 "OMIT_PAGER_PRAG
3bb0: 4d 41 53 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 MAS",.#endif.#if
3bc0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 50 41 52 SQLITE_OMIT_PAR
3bd0: 53 45 52 5f 54 52 41 43 45 0a 20 20 22 4f 4d 49 SER_TRACE. "OMI
3be0: 54 5f 50 41 52 53 45 52 5f 54 52 41 43 45 22 2c T_PARSER_TRACE",
3bf0: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
3c00: 54 45 5f 4f 4d 49 54 5f 50 4f 50 45 4e 0a 20 20 TE_OMIT_POPEN.
3c10: 22 4f 4d 49 54 5f 50 4f 50 45 4e 22 2c 0a 23 65 "OMIT_POPEN",.#e
3c20: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
3c30: 4f 4d 49 54 5f 50 52 41 47 4d 41 0a 20 20 22 4f OMIT_PRAGMA. "O
3c40: 4d 49 54 5f 50 52 41 47 4d 41 22 2c 0a 23 65 6e MIT_PRAGMA",.#en
3c50: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f dif.#if SQLITE_O
3c60: 4d 49 54 5f 50 52 4f 47 52 45 53 53 5f 43 41 4c MIT_PROGRESS_CAL
3c70: 4c 42 41 43 4b 0a 20 20 22 4f 4d 49 54 5f 50 52 LBACK. "OMIT_PR
3c80: 4f 47 52 45 53 53 5f 43 41 4c 4c 42 41 43 4b 22 OGRESS_CALLBACK"
3c90: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
3ca0: 49 54 45 5f 4f 4d 49 54 5f 51 55 49 43 4b 42 41 ITE_OMIT_QUICKBA
3cb0: 4c 41 4e 43 45 0a 20 20 22 4f 4d 49 54 5f 51 55 LANCE. "OMIT_QU
3cc0: 49 43 4b 42 41 4c 41 4e 43 45 22 2c 0a 23 65 6e ICKBALANCE",.#en
3cd0: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f dif.#if SQLITE_O
3ce0: 4d 49 54 5f 52 45 49 4e 44 45 58 0a 20 20 22 4f MIT_REINDEX. "O
3cf0: 4d 49 54 5f 52 45 49 4e 44 45 58 22 2c 0a 23 65 MIT_REINDEX",.#e
3d00: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
3d10: 4f 4d 49 54 5f 53 43 48 45 4d 41 5f 50 52 41 47 OMIT_SCHEMA_PRAG
3d20: 4d 41 53 0a 20 20 22 4f 4d 49 54 5f 53 43 48 45 MAS. "OMIT_SCHE
3d30: 4d 41 5f 50 52 41 47 4d 41 53 22 2c 0a 23 65 6e MA_PRAGMAS",.#en
3d40: 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f dif.#if SQLITE_O
3d50: 4d 49 54 5f 53 43 48 45 4d 41 5f 56 45 52 53 49 MIT_SCHEMA_VERSI
3d60: 4f 4e 5f 50 52 41 47 4d 41 53 0a 20 20 22 4f 4d ON_PRAGMAS. "OM
3d70: 49 54 5f 53 43 48 45 4d 41 5f 56 45 52 53 49 4f IT_SCHEMA_VERSIO
3d80: 4e 5f 50 52 41 47 4d 41 53 22 2c 0a 23 65 6e 64 N_PRAGMAS",.#end
3d90: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d if.#if SQLITE_OM
3da0: 49 54 5f 53 48 41 52 45 44 5f 43 41 43 48 45 0a IT_SHARED_CACHE.
3db0: 20 20 22 4f 4d 49 54 5f 53 48 41 52 45 44 5f 43 "OMIT_SHARED_C
3dc0: 41 43 48 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 ACHE",.#endif.#i
3dd0: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 53 48 f SQLITE_OMIT_SH
3de0: 55 54 44 4f 57 4e 5f 44 49 52 45 43 54 4f 52 49 UTDOWN_DIRECTORI
3df0: 45 53 0a 20 20 22 4f 4d 49 54 5f 53 48 55 54 44 ES. "OMIT_SHUTD
3e00: 4f 57 4e 5f 44 49 52 45 43 54 4f 52 49 45 53 22 OWN_DIRECTORIES"
3e10: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
3e20: 49 54 45 5f 4f 4d 49 54 5f 53 55 42 51 55 45 52 ITE_OMIT_SUBQUER
3e30: 59 0a 20 20 22 4f 4d 49 54 5f 53 55 42 51 55 45 Y. "OMIT_SUBQUE
3e40: 52 59 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 RY",.#endif.#if
3e50: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 43 4c 5f SQLITE_OMIT_TCL_
3e60: 56 41 52 49 41 42 4c 45 0a 20 20 22 4f 4d 49 54 VARIABLE. "OMIT
3e70: 5f 54 43 4c 5f 56 41 52 49 41 42 4c 45 22 2c 0a _TCL_VARIABLE",.
3e80: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
3e90: 45 5f 4f 4d 49 54 5f 54 45 4d 50 44 42 0a 20 20 E_OMIT_TEMPDB.
3ea0: 22 4f 4d 49 54 5f 54 45 4d 50 44 42 22 2c 0a 23 "OMIT_TEMPDB",.#
3eb0: 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 endif.#if SQLITE
3ec0: 5f 4f 4d 49 54 5f 54 45 53 54 5f 43 4f 4e 54 52 _OMIT_TEST_CONTR
3ed0: 4f 4c 0a 20 20 22 4f 4d 49 54 5f 54 45 53 54 5f OL. "OMIT_TEST_
3ee0: 43 4f 4e 54 52 4f 4c 22 2c 0a 23 65 6e 64 69 66 CONTROL",.#endif
3ef0: 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 .#if SQLITE_OMIT
3f00: 5f 54 52 41 43 45 0a 20 20 22 4f 4d 49 54 5f 54 _TRACE. "OMIT_T
3f10: 52 41 43 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 RACE",.#endif.#i
3f20: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 52 f SQLITE_OMIT_TR
3f30: 49 47 47 45 52 0a 20 20 22 4f 4d 49 54 5f 54 52 IGGER. "OMIT_TR
3f40: 49 47 47 45 52 22 2c 0a 23 65 6e 64 69 66 0a 23 IGGER",.#endif.#
3f50: 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 if SQLITE_OMIT_T
3f60: 52 55 4e 43 41 54 45 5f 4f 50 54 49 4d 49 5a 41 RUNCATE_OPTIMIZA
3f70: 54 49 4f 4e 0a 20 20 22 4f 4d 49 54 5f 54 52 55 TION. "OMIT_TRU
3f80: 4e 43 41 54 45 5f 4f 50 54 49 4d 49 5a 41 54 49 NCATE_OPTIMIZATI
3f90: 4f 4e 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 ON",.#endif.#if
3fa0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 55 54 46 31 SQLITE_OMIT_UTF1
3fb0: 36 0a 20 20 22 4f 4d 49 54 5f 55 54 46 31 36 22 6. "OMIT_UTF16"
3fc0: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
3fd0: 49 54 45 5f 4f 4d 49 54 5f 56 41 43 55 55 4d 0a ITE_OMIT_VACUUM.
3fe0: 20 20 22 4f 4d 49 54 5f 56 41 43 55 55 4d 22 2c "OMIT_VACUUM",
3ff0: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
4000: 54 45 5f 4f 4d 49 54 5f 56 49 45 57 0a 20 20 22 TE_OMIT_VIEW. "
4010: 4f 4d 49 54 5f 56 49 45 57 22 2c 0a 23 65 6e 64 OMIT_VIEW",.#end
4020: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d if.#if SQLITE_OM
4030: 49 54 5f 56 49 52 54 55 41 4c 54 41 42 4c 45 0a IT_VIRTUALTABLE.
4040: 20 20 22 4f 4d 49 54 5f 56 49 52 54 55 41 4c 54 "OMIT_VIRTUALT
4050: 41 42 4c 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 ABLE",.#endif.#i
4060: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 57 41 f SQLITE_OMIT_WA
4070: 4c 0a 20 20 22 4f 4d 49 54 5f 57 41 4c 22 2c 0a L. "OMIT_WAL",.
4080: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
4090: 45 5f 4f 4d 49 54 5f 57 53 44 0a 20 20 22 4f 4d E_OMIT_WSD. "OM
40a0: 49 54 5f 57 53 44 22 2c 0a 23 65 6e 64 69 66 0a IT_WSD",.#endif.
40b0: 23 69 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f #if SQLITE_OMIT_
40c0: 58 46 45 52 5f 4f 50 54 0a 20 20 22 4f 4d 49 54 XFER_OPT. "OMIT
40d0: 5f 58 46 45 52 5f 4f 50 54 22 2c 0a 23 65 6e 64 _XFER_OPT",.#end
40e0: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 50 43 if.#if SQLITE_PC
40f0: 41 43 48 45 5f 53 45 50 41 52 41 54 45 5f 48 45 ACHE_SEPARATE_HE
4100: 41 44 45 52 0a 20 20 22 50 43 41 43 48 45 5f 53 ADER. "PCACHE_S
4110: 45 50 41 52 41 54 45 5f 48 45 41 44 45 52 22 2c EPARATE_HEADER",
4120: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
4130: 54 45 5f 50 45 52 46 4f 52 4d 41 4e 43 45 5f 54 TE_PERFORMANCE_T
4140: 52 41 43 45 0a 20 20 22 50 45 52 46 4f 52 4d 41 RACE. "PERFORMA
4150: 4e 43 45 5f 54 52 41 43 45 22 2c 0a 23 65 6e 64 NCE_TRACE",.#end
4160: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 50 4f if.#if SQLITE_PO
4170: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 WERSAFE_OVERWRIT
4180: 45 0a 20 20 22 50 4f 57 45 52 53 41 46 45 5f 4f E. "POWERSAFE_O
4190: 56 45 52 57 52 49 54 45 22 2c 0a 23 65 6e 64 69 VERWRITE",.#endi
41a0: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 50 52 45 f.#if SQLITE_PRE
41b0: 46 45 52 5f 50 52 4f 58 59 5f 4c 4f 43 4b 49 4e FER_PROXY_LOCKIN
41c0: 47 0a 20 20 22 50 52 45 46 45 52 5f 50 52 4f 58 G. "PREFER_PROX
41d0: 59 5f 4c 4f 43 4b 49 4e 47 22 2c 0a 23 65 6e 64 Y_LOCKING",.#end
41e0: 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 50 52 if.#if SQLITE_PR
41f0: 4f 58 59 5f 44 45 42 55 47 0a 20 20 22 50 52 4f OXY_DEBUG. "PRO
4200: 58 59 5f 44 45 42 55 47 22 2c 0a 23 65 6e 64 69 XY_DEBUG",.#endi
4210: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 52 45 56 f.#if SQLITE_REV
4220: 45 52 53 45 5f 55 4e 4f 52 44 45 52 45 44 5f 53 ERSE_UNORDERED_S
4230: 45 4c 45 43 54 53 0a 20 20 22 52 45 56 45 52 53 ELECTS. "REVERS
4240: 45 5f 55 4e 4f 52 44 45 52 45 44 5f 53 45 4c 45 E_UNORDERED_SELE
4250: 43 54 53 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 CTS",.#endif.#if
4260: 20 53 51 4c 49 54 45 5f 52 54 52 45 45 5f 49 4e SQLITE_RTREE_IN
4270: 54 5f 4f 4e 4c 59 0a 20 20 22 52 54 52 45 45 5f T_ONLY. "RTREE_
4280: 49 4e 54 5f 4f 4e 4c 59 22 2c 0a 23 65 6e 64 69 INT_ONLY",.#endi
4290: 66 0a 23 69 66 20 53 51 4c 49 54 45 5f 53 45 43 f.#if SQLITE_SEC
42a0: 55 52 45 5f 44 45 4c 45 54 45 0a 20 20 22 53 45 URE_DELETE. "SE
42b0: 43 55 52 45 5f 44 45 4c 45 54 45 22 2c 0a 23 65 CURE_DELETE",.#e
42c0: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
42d0: 53 4d 41 4c 4c 5f 53 54 41 43 4b 0a 20 20 22 53 SMALL_STACK. "S
42e0: 4d 41 4c 4c 5f 53 54 41 43 4b 22 2c 0a 23 65 6e MALL_STACK",.#en
42f0: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 dif.#ifdef SQLIT
4300: 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 0a 20 E_SORTER_PMASZ.
4310: 20 22 53 4f 52 54 45 52 5f 50 4d 41 53 5a 3d 22 "SORTER_PMASZ="
4320: 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 CTIMEOPT_VAL(SQ
4330: 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 LITE_SORTER_PMAS
4340: 5a 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 Z),.#endif.#if S
4350: 51 4c 49 54 45 5f 53 4f 55 4e 44 45 58 0a 20 20 QLITE_SOUNDEX.
4360: 22 53 4f 55 4e 44 45 58 22 2c 0a 23 65 6e 64 69 "SOUNDEX",.#endi
4370: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f f.#ifdef SQLITE_
4380: 53 54 41 54 34 5f 53 41 4d 50 4c 45 53 0a 20 20 STAT4_SAMPLES.
4390: 22 53 54 41 54 34 5f 53 41 4d 50 4c 45 53 3d 22 "STAT4_SAMPLES="
43a0: 20 43 54 49 4d 45 4f 50 54 5f 56 41 4c 28 53 51 CTIMEOPT_VAL(SQ
43b0: 4c 49 54 45 5f 53 54 41 54 34 5f 53 41 4d 50 4c LITE_STAT4_SAMPL
43c0: 45 53 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 ES),.#endif.#ifd
43d0: 65 66 20 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 ef SQLITE_STMTJR
43e0: 4e 4c 5f 53 50 49 4c 4c 0a 20 20 22 53 54 4d 54 NL_SPILL. "STMT
43f0: 4a 52 4e 4c 5f 53 50 49 4c 4c 3d 22 20 43 54 49 JRNL_SPILL=" CTI
4400: 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 MEOPT_VAL(SQLITE
4410: 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 29 _STMTJRNL_SPILL)
4420: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
4430: 49 54 45 5f 53 55 42 53 54 52 5f 43 4f 4d 50 41 ITE_SUBSTR_COMPA
4440: 54 49 42 49 4c 49 54 59 0a 20 20 22 53 55 42 53 TIBILITY. "SUBS
4450: 54 52 5f 43 4f 4d 50 41 54 49 42 49 4c 49 54 59 TR_COMPATIBILITY
4460: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
4470: 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c LITE_SYSTEM_MALL
4480: 4f 43 0a 20 20 22 53 59 53 54 45 4d 5f 4d 41 4c OC. "SYSTEM_MAL
4490: 4c 4f 43 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 LOC",.#endif.#if
44a0: 20 53 51 4c 49 54 45 5f 54 43 4c 0a 20 20 22 54 SQLITE_TCL. "T
44b0: 43 4c 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 64 CL",.#endif.#ifd
44c0: 65 66 20 53 51 4c 49 54 45 5f 54 45 4d 50 5f 53 ef SQLITE_TEMP_S
44d0: 54 4f 52 45 0a 20 20 22 54 45 4d 50 5f 53 54 4f TORE. "TEMP_STO
44e0: 52 45 3d 22 20 43 54 49 4d 45 4f 50 54 5f 56 41 RE=" CTIMEOPT_VA
44f0: 4c 28 53 51 4c 49 54 45 5f 54 45 4d 50 5f 53 54 L(SQLITE_TEMP_ST
4500: 4f 52 45 29 2c 0a 23 65 6e 64 69 66 0a 23 69 66 ORE),.#endif.#if
4510: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 20 20 22 SQLITE_TEST. "
4520: 54 45 53 54 22 2c 0a 23 65 6e 64 69 66 0a 23 69 TEST",.#endif.#i
4530: 66 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 f defined(SQLITE
4540: 5f 54 48 52 45 41 44 53 41 46 45 29 0a 20 20 22 _THREADSAFE). "
4550: 54 48 52 45 41 44 53 41 46 45 3d 22 20 43 54 49 THREADSAFE=" CTI
4560: 4d 45 4f 50 54 5f 56 41 4c 28 53 51 4c 49 54 45 MEOPT_VAL(SQLITE
4570: 5f 54 48 52 45 41 44 53 41 46 45 29 2c 0a 23 65 _THREADSAFE),.#e
4580: 6c 69 66 20 64 65 66 69 6e 65 64 28 54 48 52 45 lif defined(THRE
4590: 41 44 53 41 46 45 29 0a 20 20 22 54 48 52 45 41 ADSAFE). "THREA
45a0: 44 53 41 46 45 3d 22 20 43 54 49 4d 45 4f 50 54 DSAFE=" CTIMEOPT
45b0: 5f 56 41 4c 28 54 48 52 45 41 44 53 41 46 45 29 _VAL(THREADSAFE)
45c0: 2c 0a 23 65 6c 73 65 0a 20 20 22 54 48 52 45 41 ,.#else. "THREA
45d0: 44 53 41 46 45 3d 31 22 2c 0a 23 65 6e 64 69 66 DSAFE=1",.#endif
45e0: 0a 23 69 66 20 53 51 4c 49 54 45 5f 55 4e 4c 49 .#if SQLITE_UNLI
45f0: 4e 4b 5f 41 46 54 45 52 5f 43 4c 4f 53 45 0a 20 NK_AFTER_CLOSE.
4600: 20 22 55 4e 4c 49 4e 4b 5f 41 46 54 45 52 5f 43 "UNLINK_AFTER_C
4610: 4c 4f 53 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 LOSE",.#endif.#i
4620: 66 20 53 51 4c 49 54 45 5f 55 4e 54 45 53 54 41 f SQLITE_UNTESTA
4630: 42 4c 45 0a 20 20 22 55 4e 54 45 53 54 41 42 4c BLE. "UNTESTABL
4640: 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 E",.#endif.#if S
4650: 51 4c 49 54 45 5f 55 53 45 52 5f 41 55 54 48 45 QLITE_USER_AUTHE
4660: 4e 54 49 43 41 54 49 4f 4e 0a 20 20 22 55 53 45 NTICATION. "USE
4670: 52 5f 41 55 54 48 45 4e 54 49 43 41 54 49 4f 4e R_AUTHENTICATION
4680: 22 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 ",.#endif.#if SQ
4690: 4c 49 54 45 5f 55 53 45 5f 41 4c 4c 4f 43 41 0a LITE_USE_ALLOCA.
46a0: 20 20 22 55 53 45 5f 41 4c 4c 4f 43 41 22 2c 0a "USE_ALLOCA",.
46b0: 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 #endif.#if SQLIT
46c0: 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 E_USE_FCNTL_TRAC
46d0: 45 0a 20 20 22 55 53 45 5f 46 43 4e 54 4c 5f 54 E. "USE_FCNTL_T
46e0: 52 41 43 45 22 2c 0a 23 65 6e 64 69 66 0a 23 69 RACE",.#endif.#i
46f0: 66 20 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 f SQLITE_USE_URI
4700: 0a 20 20 22 55 53 45 5f 55 52 49 22 2c 0a 23 65 . "USE_URI",.#e
4710: 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 54 45 5f ndif.#if SQLITE_
4720: 56 44 42 45 5f 43 4f 56 45 52 41 47 45 0a 20 20 VDBE_COVERAGE.
4730: 22 56 44 42 45 5f 43 4f 56 45 52 41 47 45 22 2c "VDBE_COVERAGE",
4740: 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c 49 .#endif.#if SQLI
4750: 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 0a TE_WIN32_MALLOC.
4760: 20 20 22 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 22 "WIN32_MALLOC"
4770: 2c 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51 4c ,.#endif.#if SQL
4780: 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 0a ITE_ZERO_MALLOC.
4790: 20 20 22 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 22 2c "ZERO_MALLOC",
47a0: 0a 23 65 6e 64 69 66 0a 2f 2a 20 0a 2a 2a 20 45 .#endif./* .** E
47b0: 4e 44 20 43 4f 44 45 20 47 45 4e 45 52 41 54 45 ND CODE GENERATE
47c0: 44 20 42 59 20 74 6f 6f 6c 2f 6d 6b 63 74 69 6d D BY tool/mkctim
47d0: 65 2e 74 63 6c 20 0a 2a 2f 0a 7d 3b 0a 0a 53 51 e.tcl .*/.};..SQ
47e0: 4c 49 54 45 5f 50 52 49 56 41 54 45 20 63 6f 6e LITE_PRIVATE con
47f0: 73 74 20 63 68 61 72 20 2a 2a 73 71 6c 69 74 65 st char **sqlite
4800: 33 43 6f 6d 70 69 6c 65 4f 70 74 69 6f 6e 73 28 3CompileOptions(
4810: 69 6e 74 20 2a 70 6e 4f 70 74 29 7b 0a 20 20 2a int *pnOpt){. *
4820: 70 6e 4f 70 74 20 3d 20 73 69 7a 65 6f 66 28 73 pnOpt = sizeof(s
4830: 71 6c 69 74 65 33 61 7a 43 6f 6d 70 69 6c 65 4f qlite3azCompileO
4840: 70 74 29 20 2f 20 73 69 7a 65 6f 66 28 73 71 6c pt) / sizeof(sql
4850: 69 74 65 33 61 7a 43 6f 6d 70 69 6c 65 4f 70 74 ite3azCompileOpt
4860: 5b 30 5d 29 3b 0a 20 20 72 65 74 75 72 6e 20 28 [0]);. return (
4870: 63 6f 6e 73 74 20 63 68 61 72 2a 2a 29 73 71 6c const char**)sql
4880: 69 74 65 33 61 7a 43 6f 6d 70 69 6c 65 4f 70 74 ite3azCompileOpt
4890: 3b 0a 7d 0a 0a 23 65 6e 64 69 66 20 2f 2a 20 53 ;.}..#endif /* S
48a0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 QLITE_OMIT_COMPI
48b0: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 20 2a LEOPTION_DIAGS *
48c0: 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a /../************
48d0: 2a 2a 20 45 6e 64 20 6f 66 20 63 74 69 6d 65 2e ** End of ctime.
48e0: 63 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a c **************
48f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4910: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */./************
4920: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71 ** Begin file sq
4930: 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a liteInt.h ******
4940: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4950: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4960: 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 */./*.** 2001 Se
4970: 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a ptember 15.**.**
4980: 20 54 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 The author disc
4990: 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 laims copyright
49a0: 74 6f 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 to this source c
49b0: 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f ode. In place o
49c0: 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 f.** a legal not
49d0: 69 63 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 ice, here is a b
49e0: 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 lessing:.**.**
49f0: 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f May you do goo
4a00: 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a d and not evil..
4a10: 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 ** May you fi
4a20: 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 nd forgiveness f
4a30: 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 or yourself and
4a40: 66 6f 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a forgive others..
4a50: 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 ** May you sh
4a60: 61 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 are freely, neve
4a70: 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 r taking more th
4a80: 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a an you give..**.
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 2a 2a 2a 2a 2a ****************
4ab0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4ac0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
4ad0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 49 6e 74 *********.** Int
4ae0: 65 72 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 20 ernal interface
4af0: 64 65 66 69 6e 69 74 69 6f 6e 73 20 66 6f 72 20 definitions for
4b00: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2f 0a 23 69 SQLite..**.*/.#i
4b10: 66 6e 64 65 66 20 53 51 4c 49 54 45 49 4e 54 5f fndef SQLITEINT_
4b20: 48 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 H.#define SQLITE
4b30: 49 4e 54 5f 48 0a 0a 2f 2a 20 53 70 65 63 69 61 INT_H../* Specia
4b40: 6c 20 43 6f 6d 6d 65 6e 74 73 3a 0a 2a 2a 0a 2a l Comments:.**.*
4b50: 2a 20 53 6f 6d 65 20 63 6f 6d 6d 65 6e 74 73 20 * Some comments
4b60: 68 61 76 65 20 73 70 65 63 69 61 6c 20 6d 65 61 have special mea
4b70: 6e 69 6e 67 20 74 6f 20 74 68 65 20 74 6f 6f 6c ning to the tool
4b80: 73 20 74 68 61 74 20 6d 65 61 73 75 72 65 20 74 s that measure t
4b90: 65 73 74 0a 2a 2a 20 63 6f 76 65 72 61 67 65 3a est.** coverage:
4ba0: 0a 2a 2a 0a 2a 2a 20 20 20 20 4e 4f 5f 54 45 53 .**.** NO_TES
4bb0: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 T
4bc0: 20 20 20 20 20 20 2d 20 54 68 65 20 62 72 61 6e - The bran
4bd0: 63 68 65 73 20 6f 6e 20 74 68 69 73 20 6c 69 6e ches on this lin
4be0: 65 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 20 20 20 e are not.**
4bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4c00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 6d 65 me
4c10: 61 73 75 72 65 64 20 62 79 20 62 72 61 6e 63 68 asured by branch
4c20: 20 63 6f 76 65 72 61 67 65 2e 20 20 54 68 69 73 coverage. This
4c30: 20 69 73 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 is.**
4c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4c50: 20 20 20 20 20 20 20 20 75 73 65 64 20 6f 6e 20 used on
4c60: 6c 69 6e 65 73 20 6f 66 20 63 6f 64 65 20 74 68 lines of code th
4c70: 61 74 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 20 at actually.**
4c80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4ca0: 69 6d 70 6c 65 6d 65 6e 74 20 70 61 72 74 73 20 implement parts
4cb0: 6f 66 20 63 6f 76 65 72 61 67 65 20 74 65 73 74 of coverage test
4cc0: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 20 20 20 4f 50 ing..**.** OP
4cd0: 54 49 4d 49 5a 41 54 49 4f 4e 2d 49 46 2d 54 52 TIMIZATION-IF-TR
4ce0: 55 45 20 20 20 20 20 20 20 20 2d 20 54 68 69 73 UE - This
4cf0: 20 62 72 61 6e 63 68 20 69 73 20 61 6c 6c 6f 77 branch is allow
4d00: 65 64 20 74 6f 20 61 6c 77 61 79 20 62 65 20 66 ed to alway be f
4d10: 61 6c 73 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 alse.**
4d20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4d30: 20 20 20 20 20 20 20 20 20 61 6e 64 20 74 68 65 and the
4d40: 20 63 6f 72 72 65 63 74 20 61 6e 73 77 65 72 20 correct answer
4d50: 69 73 20 73 74 69 6c 6c 20 6f 62 74 61 69 6e 65 is still obtaine
4d60: 64 2c 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 d,.**
4d70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4d80: 20 20 20 20 20 20 20 74 68 6f 75 67 68 20 70 65 though pe
4d90: 72 68 61 70 73 20 6d 6f 72 65 20 73 6c 6f 77 6c rhaps more slowl
4da0: 79 2e 0a 2a 2a 0a 2a 2a 20 20 20 20 4f 50 54 49 y..**.** OPTI
4db0: 4d 49 5a 41 54 49 4f 4e 2d 49 46 2d 46 41 4c 53 MIZATION-IF-FALS
4dc0: 45 20 20 20 20 20 20 20 2d 20 54 68 69 73 20 62 E - This b
4dd0: 72 61 6e 63 68 20 69 73 20 61 6c 6c 6f 77 65 64 ranch is allowed
4de0: 20 74 6f 20 61 6c 77 61 79 20 62 65 20 74 72 75 to alway be tru
4df0: 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 e.**
4e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4e10: 20 20 20 20 20 20 61 6e 64 20 74 68 65 20 63 6f and the co
4e20: 72 72 65 63 74 20 61 6e 73 77 65 72 20 69 73 20 rrect answer is
4e30: 73 74 69 6c 6c 20 6f 62 74 61 69 6e 65 64 2c 0a still obtained,.
4e40: 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 **
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4e60: 20 20 20 20 74 68 6f 75 67 68 20 70 65 72 68 61 though perha
4e70: 70 73 20 6d 6f 72 65 20 73 6c 6f 77 6c 79 2e 0a ps more slowly..
4e80: 2a 2a 0a 2a 2a 20 20 20 20 50 52 45 56 45 4e 54 **.** PREVENT
4e90: 53 2d 48 41 52 4d 4c 45 53 53 2d 4f 56 45 52 52 S-HARMLESS-OVERR
4ea0: 45 41 44 20 20 2d 20 54 68 69 73 20 62 72 61 6e EAD - This bran
4eb0: 63 68 20 70 72 65 76 65 6e 74 73 20 61 20 62 75 ch prevents a bu
4ec0: 66 66 65 72 20 6f 76 65 72 72 65 61 64 0a 2a 2a ffer overread.**
4ed0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4ef0: 20 20 74 68 61 74 20 77 6f 75 6c 64 20 62 65 20 that would be
4f00: 68 61 72 6d 6c 65 73 73 20 61 6e 64 20 75 6e 64 harmless and und
4f10: 65 74 65 63 74 61 62 6c 65 0a 2a 2a 20 20 20 20 etectable.**
4f20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
4f30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 66 if
4f40: 20 69 74 20 64 69 64 20 6f 63 63 75 72 2e 20 20 it did occur.
4f50: 0a 2a 2a 0a 2a 2a 20 49 6e 20 61 6c 6c 20 63 61 .**.** In all ca
4f60: 73 65 73 2c 20 74 68 65 20 73 70 65 63 69 61 6c ses, the special
4f70: 20 63 6f 6d 6d 65 6e 74 20 6d 75 73 74 20 62 65 comment must be
4f80: 20 65 6e 63 6c 6f 73 65 64 20 69 6e 20 74 68 65 enclosed in the
4f90: 20 75 73 75 61 6c 0a 2a 2a 20 73 6c 61 73 68 2d usual.** slash-
4fa0: 61 73 74 65 72 69 73 6b 2e 2e 2e 61 73 74 65 72 asterisk...aster
4fb0: 69 73 6b 2d 73 6c 61 73 68 20 63 6f 6d 6d 65 6e isk-slash commen
4fc0: 74 20 6d 61 72 6b 73 2c 20 77 69 74 68 20 6e 6f t marks, with no
4fd0: 20 73 70 61 63 65 73 20 62 65 74 77 65 65 6e 20 spaces between
4fe0: 74 68 65 20 0a 2a 2a 20 61 73 74 65 72 69 73 6b the .** asterisk
4ff0: 73 20 61 6e 64 20 74 68 65 20 63 6f 6d 6d 65 6e s and the commen
5000: 74 20 74 65 78 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a t text..*/../*.*
5010: 2a 20 4d 61 6b 65 20 73 75 72 65 20 74 68 65 20 * Make sure the
5020: 54 63 6c 20 63 61 6c 6c 69 6e 67 20 63 6f 6e 76 Tcl calling conv
5030: 65 6e 74 69 6f 6e 20 6d 61 63 72 6f 20 69 73 20 ention macro is
5040: 64 65 66 69 6e 65 64 2e 20 20 54 68 69 73 20 6d defined. This m
5050: 61 63 72 6f 20 69 73 0a 2a 2a 20 6f 6e 6c 79 20 acro is.** only
5060: 75 73 65 64 20 62 79 20 74 65 73 74 20 63 6f 64 used by test cod
5070: 65 20 61 6e 64 20 54 63 6c 20 69 6e 74 65 67 72 e and Tcl integr
5080: 61 74 69 6f 6e 20 63 6f 64 65 2e 0a 2a 2f 0a 23 ation code..*/.#
5090: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 43 ifndef SQLITE_TC
50a0: 4c 41 50 49 0a 23 20 20 64 65 66 69 6e 65 20 53 LAPI.# define S
50b0: 51 4c 49 54 45 5f 54 43 4c 41 50 49 0a 23 65 6e QLITE_TCLAPI.#en
50c0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 dif../*.** Inclu
50d0: 64 65 20 74 68 65 20 68 65 61 64 65 72 20 66 69 de the header fi
50e0: 6c 65 20 75 73 65 64 20 74 6f 20 63 75 73 74 6f le used to custo
50f0: 6d 69 7a 65 20 74 68 65 20 63 6f 6d 70 69 6c 65 mize the compile
5100: 72 20 6f 70 74 69 6f 6e 73 20 66 6f 72 20 4d 53 r options for MS
5110: 56 43 2e 0a 2a 2a 20 54 68 69 73 20 73 68 6f 75 VC..** This shou
5120: 6c 64 20 62 65 20 64 6f 6e 65 20 66 69 72 73 74 ld be done first
5130: 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 so that it can
5140: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 70 72 65 successfully pre
5150: 76 65 6e 74 20 73 70 75 72 69 6f 75 73 0a 2a 2a vent spurious.**
5160: 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e compiler warnin
5170: 67 73 20 64 75 65 20 74 6f 20 73 75 62 73 65 71 gs due to subseq
5180: 75 65 6e 74 20 63 6f 6e 74 65 6e 74 20 69 6e 20 uent content in
5190: 74 68 69 73 20 66 69 6c 65 20 61 6e 64 20 6f 74 this file and ot
51a0: 68 65 72 20 66 69 6c 65 73 0a 2a 2a 20 74 68 61 her files.** tha
51b0: 74 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 62 t are included b
51c0: 79 20 74 68 69 73 20 66 69 6c 65 2e 0a 2a 2f 0a y this file..*/.
51d0: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 /**************
51e0: 49 6e 63 6c 75 64 65 20 6d 73 76 63 2e 68 20 69 Include msvc.h i
51f0: 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 n the middle of
5200: 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a sqliteInt.h ****
5210: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a **************/.
5220: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 /**************
5230: 42 65 67 69 6e 20 66 69 6c 65 20 6d 73 76 63 2e Begin file msvc.
5240: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a h **************
5250: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5260: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a **************/.
5270: 2f 2a 0a 2a 2a 20 32 30 31 35 20 4a 61 6e 75 61 /*.** 2015 Janua
5280: 72 79 20 31 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 ry 12.**.** The
5290: 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 author disclaims
52a0: 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 copyright to th
52b0: 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 is source code.
52c0: 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 In place of.**
52d0: 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 a legal notice,
52e0: 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 here is a blessi
52f0: 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 ng:.**.** May
5300: 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 you do good and
5310: 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 not evil..**
5320: 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f May you find fo
5330: 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f rgiveness for yo
5340: 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 urself and forgi
5350: 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 ve others..**
5360: 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 May you share f
5370: 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b reely, never tak
5380: 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f ing more than yo
5390: 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a u give..**.*****
53a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
53b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
53c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
53d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
53e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 *********.**.**
53f0: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 This file contai
5400: 6e 73 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 ns code that is
5410: 73 70 65 63 69 66 69 63 20 74 6f 20 4d 53 56 43 specific to MSVC
5420: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c ..*/.#ifndef SQL
5430: 49 54 45 5f 4d 53 56 43 5f 48 0a 23 64 65 66 69 ITE_MSVC_H.#defi
5440: 6e 65 20 53 51 4c 49 54 45 5f 4d 53 56 43 5f 48 ne SQLITE_MSVC_H
5450: 0a 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 4d ..#if defined(_M
5460: 53 43 5f 56 45 52 29 0a 23 70 72 61 67 6d 61 20 SC_VER).#pragma
5470: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
5480: 3a 20 34 30 35 34 29 0a 23 70 72 61 67 6d 61 20 : 4054).#pragma
5490: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
54a0: 3a 20 34 30 35 35 29 0a 23 70 72 61 67 6d 61 20 : 4055).#pragma
54b0: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
54c0: 3a 20 34 31 30 30 29 0a 23 70 72 61 67 6d 61 20 : 4100).#pragma
54d0: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
54e0: 3a 20 34 31 32 37 29 0a 23 70 72 61 67 6d 61 20 : 4127).#pragma
54f0: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
5500: 3a 20 34 31 33 30 29 0a 23 70 72 61 67 6d 61 20 : 4130).#pragma
5510: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
5520: 3a 20 34 31 35 32 29 0a 23 70 72 61 67 6d 61 20 : 4152).#pragma
5530: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
5540: 3a 20 34 31 38 39 29 0a 23 70 72 61 67 6d 61 20 : 4189).#pragma
5550: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
5560: 3a 20 34 32 30 36 29 0a 23 70 72 61 67 6d 61 20 : 4206).#pragma
5570: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
5580: 3a 20 34 32 31 30 29 0a 23 70 72 61 67 6d 61 20 : 4210).#pragma
5590: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
55a0: 3a 20 34 32 33 32 29 0a 23 70 72 61 67 6d 61 20 : 4232).#pragma
55b0: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
55c0: 3a 20 34 32 34 34 29 0a 23 70 72 61 67 6d 61 20 : 4244).#pragma
55d0: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
55e0: 3a 20 34 33 30 35 29 0a 23 70 72 61 67 6d 61 20 : 4305).#pragma
55f0: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
5600: 3a 20 34 33 30 36 29 0a 23 70 72 61 67 6d 61 20 : 4306).#pragma
5610: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
5620: 3a 20 34 37 30 32 29 0a 23 70 72 61 67 6d 61 20 : 4702).#pragma
5630: 77 61 72 6e 69 6e 67 28 64 69 73 61 62 6c 65 20 warning(disable
5640: 3a 20 34 37 30 36 29 0a 23 65 6e 64 69 66 20 2f : 4706).#endif /
5650: 2a 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 * defined(_MSC_V
5660: 45 52 29 20 2a 2f 0a 0a 23 65 6e 64 69 66 20 2f ER) */..#endif /
5670: 2a 20 53 51 4c 49 54 45 5f 4d 53 56 43 5f 48 20 * SQLITE_MSVC_H
5680: 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a */../***********
5690: 2a 2a 2a 20 45 6e 64 20 6f 66 20 6d 73 76 63 2e *** End of msvc.
56a0: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a h **************
56b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
56c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
56d0: 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a **/./***********
56e0: 2a 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 *** Continuing w
56f0: 68 65 72 65 20 77 65 20 6c 65 66 74 20 6f 66 66 here we left off
5700: 20 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 in sqliteInt.h
5710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5720: 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 **/../*.** Speci
5730: 61 6c 20 73 65 74 75 70 20 66 6f 72 20 56 78 57 al setup for VxW
5740: 6f 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a orks.*/./*******
5750: 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 ******* Include
5760: 76 78 77 6f 72 6b 73 2e 68 20 69 6e 20 74 68 65 vxworks.h in the
5770: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 middle of sqlit
5780: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a eInt.h *********
5790: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a ******/./*******
57a0: 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 ******* Begin fi
57b0: 6c 65 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a le vxworks.h ***
57c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
57d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
57e0: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 ******/./*.** 20
57f0: 31 35 2d 30 33 2d 30 32 0a 2a 2a 0a 2a 2a 20 54 15-03-02.**.** T
5800: 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 he author discla
5810: 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f ims copyright to
5820: 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 this source cod
5830: 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a e. In place of.
5840: 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 ** a legal notic
5850: 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 e, here is a ble
5860: 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 ssing:.**.**
5870: 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 May you do good
5880: 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a and not evil..**
5890: 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 May you find
58a0: 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 forgiveness for
58b0: 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f yourself and fo
58c0: 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a rgive others..**
58d0: 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 May you shar
58e0: 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 e freely, never
58f0: 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e taking more than
5900: 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a you give..**.**
5910: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5920: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5930: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5940: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5950: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a ************.**.
5960: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e ** This file con
5970: 74 61 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20 tains code that
5980: 69 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 57 is specific to W
5990: 69 6e 64 20 52 69 76 65 72 27 73 20 56 78 57 6f ind River's VxWo
59a0: 72 6b 73 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e rks.*/.#if defin
59b0: 65 64 28 5f 5f 52 54 50 5f 5f 29 20 7c 7c 20 64 ed(__RTP__) || d
59c0: 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52 4e efined(_WRS_KERN
59d0: 45 4c 29 0a 2f 2a 20 54 68 69 73 20 69 73 20 56 EL)./* This is V
59e0: 78 57 6f 72 6b 73 2e 20 20 53 65 74 20 75 70 20 xWorks. Set up
59f0: 74 68 69 6e 67 73 20 73 70 65 63 69 61 6c 6c 79 things specially
5a00: 20 66 6f 72 20 74 68 61 74 20 4f 53 0a 2a 2f 0a for that OS.*/.
5a10: 23 69 6e 63 6c 75 64 65 20 3c 76 78 57 6f 72 6b #include <vxWork
5a20: 73 2e 68 3e 0a 23 69 6e 63 6c 75 64 65 20 3c 70 s.h>.#include <p
5a30: 74 68 72 65 61 64 2e 68 3e 20 20 2f 2a 20 61 6d thread.h> /* am
5a40: 61 6c 67 61 6d 61 74 6f 72 3a 20 64 6f 6e 74 63 algamator: dontc
5a50: 61 63 68 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 ache */.#define
5a60: 4f 53 5f 56 58 57 4f 52 4b 53 20 31 0a 23 64 65 OS_VXWORKS 1.#de
5a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 53 5f 4f fine SQLITE_OS_O
5a80: 54 48 45 52 20 30 0a 23 64 65 66 69 6e 65 20 53 THER 0.#define S
5a90: 51 4c 49 54 45 5f 48 4f 4d 45 47 52 4f 57 4e 5f QLITE_HOMEGROWN_
5aa0: 52 45 43 55 52 53 49 56 45 5f 4d 55 54 45 58 20 RECURSIVE_MUTEX
5ab0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 1.#define SQLITE
5ac0: 5f 4f 4d 49 54 5f 4c 4f 41 44 5f 45 58 54 45 4e _OMIT_LOAD_EXTEN
5ad0: 53 49 4f 4e 20 31 0a 23 64 65 66 69 6e 65 20 53 SION 1.#define S
5ae0: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c 4f 43 QLITE_ENABLE_LOC
5af0: 4b 49 4e 47 5f 53 54 59 4c 45 20 30 0a 23 64 65 KING_STYLE 0.#de
5b00: 66 69 6e 65 20 48 41 56 45 5f 55 54 49 4d 45 20 fine HAVE_UTIME
5b10: 31 0a 23 65 6c 73 65 0a 2f 2a 20 54 68 69 73 20 1.#else./* This
5b20: 69 73 20 6e 6f 74 20 56 78 57 6f 72 6b 73 2e 20 is not VxWorks.
5b30: 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58 */.#define OS_VX
5b40: 57 4f 52 4b 53 20 30 0a 23 64 65 66 69 6e 65 20 WORKS 0.#define
5b50: 48 41 56 45 5f 46 43 48 4f 57 4e 20 31 0a 23 64 HAVE_FCHOWN 1.#d
5b60: 65 66 69 6e 65 20 48 41 56 45 5f 52 45 41 44 4c efine HAVE_READL
5b70: 49 4e 4b 20 31 0a 23 64 65 66 69 6e 65 20 48 41 INK 1.#define HA
5b80: 56 45 5f 4c 53 54 41 54 20 31 0a 23 65 6e 64 69 VE_LSTAT 1.#endi
5b90: 66 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f 57 52 f /* defined(_WR
5ba0: 53 5f 4b 45 52 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a S_KERNEL) */../*
5bb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e ************* En
5bc0: 64 20 6f 66 20 76 78 77 6f 72 6b 73 2e 68 20 2a d of vxworks.h *
5bd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5be0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
5bf0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a ************/./*
5c00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f ************* Co
5c10: 6e 74 69 6e 75 69 6e 67 20 77 68 65 72 65 20 77 ntinuing where w
5c20: 65 20 6c 65 66 74 20 6f 66 66 20 69 6e 20 73 71 e left off in sq
5c30: 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a liteInt.h ******
5c40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f ************/../
5c50: 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64 65 66 69 *.** These #defi
5c60: 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e 61 62 6c nes should enabl
5c70: 65 20 3e 32 47 42 20 66 69 6c 65 20 73 75 70 70 e >2GB file supp
5c80: 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20 69 66 20 ort on POSIX if
5c90: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e the.** underlyin
5ca0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 g operating syst
5cb0: 65 6d 20 73 75 70 70 6f 72 74 73 20 69 74 2e 20 em supports it.
5cc0: 20 49 66 20 74 68 65 20 4f 53 20 6c 61 63 6b 73 If the OS lacks
5cd0: 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c 65 20 73 .** large file s
5ce0: 75 70 70 6f 72 74 2c 20 6f 72 20 69 66 20 74 68 upport, or if th
5cf0: 65 20 4f 53 20 69 73 20 77 69 6e 64 6f 77 73 2c e OS is windows,
5d00: 20 74 68 65 73 65 20 73 68 6f 75 6c 64 20 62 65 these should be
5d10: 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 no-ops..**.** T
5d20: 69 63 6b 65 74 20 23 32 37 33 39 3a 20 20 54 68 icket #2739: Th
5d30: 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 e _LARGEFILE_SOU
5d40: 52 43 45 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 RCE macro must a
5d50: 70 70 65 61 72 20 62 65 66 6f 72 65 20 61 6e 79 ppear before any
5d60: 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69 6e 63 6c .** system #incl
5d70: 75 64 65 73 2e 20 20 48 65 6e 63 65 2c 20 74 68 udes. Hence, th
5d80: 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 is block of code
5d90: 20 6d 75 73 74 20 62 65 20 74 68 65 20 76 65 72 must be the ver
5da0: 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f 64 65 20 y first.** code
5db0: 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65 20 66 69 in all source fi
5dc0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72 67 65 les..**.** Large
5dd0: 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20 63 61 file support ca
5de0: 6e 20 62 65 20 64 69 73 61 62 6c 65 64 20 75 73 n be disabled us
5df0: 69 6e 67 20 74 68 65 20 2d 44 53 51 4c 49 54 45 ing the -DSQLITE
5e00: 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20 73 77 69 _DISABLE_LFS swi
5e10: 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f tch.** on the co
5e20: 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e 64 20 6c mpiler command l
5e30: 69 6e 65 2e 20 20 54 68 69 73 20 69 73 20 6e 65 ine. This is ne
5e40: 63 65 73 73 61 72 79 20 69 66 20 79 6f 75 20 61 cessary if you a
5e50: 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a 2a 2a 20 re compiling.**
5e60: 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d 61 63 68 on a recent mach
5e70: 69 6e 65 20 28 65 78 3a 20 52 65 64 20 48 61 74 ine (ex: Red Hat
5e80: 20 37 2e 32 29 20 62 75 74 20 79 6f 75 20 77 61 7.2) but you wa
5e90: 6e 74 20 79 6f 75 72 20 63 6f 64 65 20 74 6f 20 nt your code to
5ea0: 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e 20 6f 6c work.** on an ol
5eb0: 64 65 72 20 6d 61 63 68 69 6e 65 20 28 65 78 3a der machine (ex:
5ec0: 20 52 65 64 20 48 61 74 20 36 2e 30 29 2e 20 20 Red Hat 6.0).
5ed0: 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65 20 6f If you compile o
5ee0: 6e 20 52 65 64 20 48 61 74 20 37 2e 32 0a 2a 2a n Red Hat 7.2.**
5ef0: 20 77 69 74 68 6f 75 74 20 74 68 69 73 20 6f 70 without this op
5f00: 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20 65 6e 61 tion, LFS is ena
5f10: 62 6c 65 2e 20 20 42 75 74 20 4c 46 53 20 64 6f ble. But LFS do
5f20: 65 73 20 6e 6f 74 20 65 78 69 73 74 20 69 6e 20 es not exist in
5f30: 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a 20 69 6e the kernel.** in
5f40: 20 52 65 64 20 48 61 74 20 36 2e 30 2c 20 73 6f Red Hat 6.0, so
5f50: 20 74 68 65 20 63 6f 64 65 20 77 6f 6e 27 74 20 the code won't
5f60: 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c 20 66 6f work. Hence, fo
5f70: 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e 61 72 79 r maximum binary
5f80: 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69 74 79 20 .** portability
5f90: 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d 69 74 20 you should omit
5fa0: 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 LFS..**.** The p
5fb0: 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 revious paragrap
5fc0: 68 20 77 61 73 20 77 72 69 74 74 65 6e 20 69 6e h was written in
5fd0: 20 32 30 30 35 2e 20 20 28 54 68 69 73 20 70 61 2005. (This pa
5fe0: 72 61 67 72 61 70 68 20 69 73 20 77 72 69 74 74 ragraph is writt
5ff0: 65 6e 0a 2a 2a 20 6f 6e 20 32 30 30 38 2d 31 31 en.** on 2008-11
6000: 2d 32 38 2e 29 20 54 68 65 73 65 20 64 61 79 73 -28.) These days
6010: 2c 20 61 6c 6c 20 4c 69 6e 75 78 20 6b 65 72 6e , all Linux kern
6020: 65 6c 73 20 73 75 70 70 6f 72 74 20 6c 61 72 67 els support larg
6030: 65 20 66 69 6c 65 73 2c 20 73 6f 0a 2a 2a 20 79 e files, so.** y
6040: 6f 75 20 73 68 6f 75 6c 64 20 70 72 6f 62 61 62 ou should probab
6050: 6c 79 20 6c 65 61 76 65 20 4c 46 53 20 65 6e 61 ly leave LFS ena
6060: 62 6c 65 64 2e 20 20 42 75 74 20 73 6f 6d 65 20 bled. But some
6070: 65 6d 62 65 64 64 65 64 20 70 6c 61 74 66 6f 72 embedded platfor
6080: 6d 73 20 6d 69 67 68 74 0a 2a 2a 20 6c 61 63 6b ms might.** lack
6090: 20 4c 46 53 20 69 6e 20 77 68 69 63 68 20 63 61 LFS in which ca
60a0: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 44 49 se the SQLITE_DI
60b0: 53 41 42 4c 45 5f 4c 46 53 20 6d 61 63 72 6f 20 SABLE_LFS macro
60c0: 6d 69 67 68 74 20 73 74 69 6c 6c 20 62 65 20 75 might still be u
60d0: 73 65 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d seful..**.** Sim
60e0: 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f 72 ilar is true for
60f0: 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53 20 Mac OS X. LFS
6100: 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65 is only supporte
6110: 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39 20 d on Mac OS X 9
6120: 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69 and later..*/.#i
6130: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49 53 fndef SQLITE_DIS
6140: 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e ABLE_LFS.# defin
6150: 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20 20 e _LARGE_FILE
6160: 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20 5f 1.# ifndef _
6170: 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 FILE_OFFSET_BITS
6180: 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49 4c .# define _FIL
6190: 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36 34 E_OFFSET_BITS 64
61a0: 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69 6e .# endif.# defin
61b0: 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 e _LARGEFILE_SOU
61c0: 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a RCE 1.#endif../*
61d0: 20 54 68 65 20 47 43 43 5f 56 45 52 53 49 4f 4e The GCC_VERSION
61e0: 20 61 6e 64 20 4d 53 56 43 5f 56 45 52 53 49 4f and MSVC_VERSIO
61f0: 4e 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 N macros are use
6200: 64 20 74 6f 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f d to.** conditio
6210: 6e 61 6c 6c 79 20 69 6e 63 6c 75 64 65 20 6f 70 nally include op
6220: 74 69 6d 69 7a 61 74 69 6f 6e 73 20 66 6f 72 20 timizations for
6230: 65 61 63 68 20 6f 66 20 74 68 65 73 65 20 63 6f each of these co
6240: 6d 70 69 6c 65 72 73 2e 20 20 41 0a 2a 2a 20 76 mpilers. A.** v
6250: 61 6c 75 65 20 6f 66 20 30 20 6d 65 61 6e 73 20 alue of 0 means
6260: 74 68 61 74 20 63 6f 6d 70 69 6c 65 72 20 69 73 that compiler is
6270: 20 6e 6f 74 20 62 65 69 6e 67 20 75 73 65 64 2e not being used.
6280: 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f The.** SQLITE_
6290: 44 49 53 41 42 4c 45 5f 49 4e 54 52 49 4e 53 49 DISABLE_INTRINSI
62a0: 43 20 6d 61 63 72 6f 20 6d 65 61 6e 73 20 64 6f C macro means do
62b0: 20 6e 6f 74 20 75 73 65 20 61 6e 79 20 63 6f 6d not use any com
62c0: 70 69 6c 65 72 2d 73 70 65 63 69 66 69 63 0a 2a piler-specific.*
62d0: 2a 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 2c * optimizations,
62e0: 20 61 6e 64 20 68 65 6e 63 65 20 73 65 74 20 61 and hence set a
62f0: 6c 6c 20 63 6f 6d 70 69 6c 65 72 20 6d 61 63 72 ll compiler macr
6300: 6f 73 20 74 6f 20 30 0a 2a 2a 0a 2a 2a 20 54 68 os to 0.**.** Th
6310: 65 72 65 20 77 61 73 20 6f 6e 63 65 20 61 6c 73 ere was once als
6320: 6f 20 61 20 43 4c 41 4e 47 5f 56 45 52 53 49 4f o a CLANG_VERSIO
6330: 4e 20 6d 61 63 72 6f 2e 20 20 48 6f 77 65 76 65 N macro. Howeve
6340: 72 2c 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74 r, we learn that
6350: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 the.** version
6360: 6e 75 6d 62 65 72 73 20 69 6e 20 63 6c 61 6e 67 numbers in clang
6370: 20 61 72 65 20 66 6f 72 20 22 6d 61 72 6b 65 74 are for "market
6380: 69 6e 67 22 20 6f 6e 6c 79 20 61 6e 64 20 61 72 ing" only and ar
6390: 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 0a 2a e inconsistent.*
63a0: 2a 20 61 6e 64 20 75 6e 72 65 6c 69 61 62 6c 65 * and unreliable
63b0: 2e 20 20 46 6f 72 74 75 6e 61 74 65 6c 79 2c 20 . Fortunately,
63c0: 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 all versions of
63d0: 63 6c 61 6e 67 20 61 6c 73 6f 20 72 65 63 6f 67 clang also recog
63e0: 6e 69 7a 65 20 74 68 65 0a 2a 2a 20 67 63 63 20 nize the.** gcc
63f0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 73 20 version numbers
6400: 61 6e 64 20 68 61 76 65 20 72 65 61 73 6f 6e 61 and have reasona
6410: 62 6c 65 20 73 65 74 74 69 6e 67 73 20 66 6f 72 ble settings for
6420: 20 67 63 63 20 76 65 72 73 69 6f 6e 20 6e 75 6d gcc version num
6430: 62 65 72 73 2c 0a 2a 2a 20 73 6f 20 74 68 65 20 bers,.** so the
6440: 47 43 43 5f 56 45 52 53 49 4f 4e 20 6d 61 63 72 GCC_VERSION macr
6450: 6f 20 77 69 6c 6c 20 62 65 20 73 65 74 20 74 6f o will be set to
6460: 20 61 20 63 6f 72 72 65 63 74 20 6e 6f 6e 2d 7a a correct non-z
6470: 65 72 6f 20 76 61 6c 75 65 20 65 76 65 6e 0a 2a ero value even.*
6480: 2a 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67 * when compiling
6490: 20 77 69 74 68 20 63 6c 61 6e 67 2e 0a 2a 2f 0a with clang..*/.
64a0: 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e #if defined(__GN
64b0: 55 43 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 UC__) && !define
64c0: 64 28 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 d(SQLITE_DISABLE
64d0: 5f 49 4e 54 52 49 4e 53 49 43 29 0a 23 20 64 65 _INTRINSIC).# de
64e0: 66 69 6e 65 20 47 43 43 5f 56 45 52 53 49 4f 4e fine GCC_VERSION
64f0: 20 28 5f 5f 47 4e 55 43 5f 5f 2a 31 30 30 30 30 (__GNUC__*10000
6500: 30 30 2b 5f 5f 47 4e 55 43 5f 4d 49 4e 4f 52 5f 00+__GNUC_MINOR_
6510: 5f 2a 31 30 30 30 2b 5f 5f 47 4e 55 43 5f 50 41 _*1000+__GNUC_PA
6520: 54 43 48 4c 45 56 45 4c 5f 5f 29 0a 23 65 6c 73 TCHLEVEL__).#els
6530: 65 0a 23 20 64 65 66 69 6e 65 20 47 43 43 5f 56 e.# define GCC_V
6540: 45 52 53 49 4f 4e 20 30 0a 23 65 6e 64 69 66 0a ERSION 0.#endif.
6550: 23 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 #if defined(_MSC
6560: 5f 56 45 52 29 20 26 26 20 21 64 65 66 69 6e 65 _VER) && !define
6570: 64 28 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 d(SQLITE_DISABLE
6580: 5f 49 4e 54 52 49 4e 53 49 43 29 0a 23 20 64 65 _INTRINSIC).# de
6590: 66 69 6e 65 20 4d 53 56 43 5f 56 45 52 53 49 4f fine MSVC_VERSIO
65a0: 4e 20 5f 4d 53 43 5f 56 45 52 0a 23 65 6c 73 65 N _MSC_VER.#else
65b0: 0a 23 20 64 65 66 69 6e 65 20 4d 53 56 43 5f 56 .# define MSVC_V
65c0: 45 52 53 49 4f 4e 20 30 0a 23 65 6e 64 69 66 0a ERSION 0.#endif.
65d0: 0a 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 76 ./* Needed for v
65e0: 61 72 69 6f 75 73 20 64 65 66 69 6e 69 74 69 6f arious definitio
65f0: 6e 73 2e 2e 2e 20 2a 2f 0a 23 69 66 20 64 65 66 ns... */.#if def
6600: 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26 ined(__GNUC__) &
6610: 26 20 21 64 65 66 69 6e 65 64 28 5f 47 4e 55 5f & !defined(_GNU_
6620: 53 4f 55 52 43 45 29 0a 23 20 64 65 66 69 6e 65 SOURCE).# define
6630: 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65 6e _GNU_SOURCE.#en
6640: 64 69 66 0a 0a 23 69 66 20 64 65 66 69 6e 65 64 dif..#if defined
6650: 28 5f 5f 4f 70 65 6e 42 53 44 5f 5f 29 20 26 26 (__OpenBSD__) &&
6660: 20 21 64 65 66 69 6e 65 64 28 5f 42 53 44 5f 53 !defined(_BSD_S
6670: 4f 55 52 43 45 29 0a 23 20 64 65 66 69 6e 65 20 OURCE).# define
6680: 5f 42 53 44 5f 53 4f 55 52 43 45 0a 23 65 6e 64 _BSD_SOURCE.#end
6690: 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 if../*.** For Mi
66a0: 6e 47 57 2c 20 63 68 65 63 6b 20 74 6f 20 73 65 nGW, check to se
66b0: 65 20 69 66 20 77 65 20 63 61 6e 20 69 6e 63 6c e if we can incl
66c0: 75 64 65 20 74 68 65 20 68 65 61 64 65 72 20 66 ude the header f
66d0: 69 6c 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 ile containing i
66e0: 74 73 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 69 6e ts.** version in
66f0: 66 6f 72 6d 61 74 69 6f 6e 2c 20 61 6d 6f 6e 67 formation, among
6700: 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2e 20 20 other things.
6710: 4e 6f 72 6d 61 6c 6c 79 2c 20 74 68 69 73 20 69 Normally, this i
6720: 6e 74 65 72 6e 61 6c 20 4d 69 6e 47 57 0a 2a 2a nternal MinGW.**
6730: 20 68 65 61 64 65 72 20 66 69 6c 65 20 77 6f 75 header file wou
6740: 6c 64 20 5b 6f 6e 6c 79 5d 20 62 65 20 69 6e 63 ld [only] be inc
6750: 6c 75 64 65 64 20 61 75 74 6f 6d 61 74 69 63 61 luded automatica
6760: 6c 6c 79 20 62 79 20 6f 74 68 65 72 20 4d 69 6e lly by other Min
6770: 47 57 20 68 65 61 64 65 72 0a 2a 2a 20 66 69 6c GW header.** fil
6780: 65 73 3b 20 68 6f 77 65 76 65 72 2c 20 74 68 65 es; however, the
6790: 20 63 6f 6e 74 61 69 6e 65 64 20 76 65 72 73 69 contained versi
67a0: 6f 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 on information i
67b0: 73 20 6e 6f 77 20 72 65 71 75 69 72 65 64 20 62 s now required b
67c0: 79 20 74 68 69 73 0a 2a 2a 20 68 65 61 64 65 72 y this.** header
67d0: 20 66 69 6c 65 20 74 6f 20 77 6f 72 6b 20 61 72 file to work ar
67e0: 6f 75 6e 64 20 62 69 6e 61 72 79 20 63 6f 6d 70 ound binary comp
67f0: 61 74 69 62 69 6c 69 74 79 20 69 73 73 75 65 73 atibility issues
6800: 20 28 73 65 65 20 62 65 6c 6f 77 29 20 61 6e 64 (see below) and
6810: 0a 2a 2a 20 74 68 69 73 20 69 73 20 74 68 65 20 .** this is the
6820: 6f 6e 6c 79 20 6b 6e 6f 77 6e 20 77 61 79 20 74 only known way t
6830: 6f 20 72 65 6c 69 61 62 6c 79 20 6f 62 74 61 69 o reliably obtai
6840: 6e 20 69 74 2e 20 20 54 68 69 73 20 65 6e 74 69 n it. This enti
6850: 72 65 20 23 69 66 20 62 6c 6f 63 6b 0a 2a 2a 20 re #if block.**
6860: 77 6f 75 6c 64 20 62 65 20 63 6f 6d 70 6c 65 74 would be complet
6870: 65 6c 79 20 75 6e 6e 65 63 65 73 73 61 72 79 20 ely unnecessary
6880: 69 66 20 74 68 65 72 65 20 77 61 73 20 61 6e 79 if there was any
6890: 20 6f 74 68 65 72 20 77 61 79 20 6f 66 20 64 65 other way of de
68a0: 74 65 63 74 69 6e 67 0a 2a 2a 20 4d 69 6e 47 57 tecting.** MinGW
68b0: 20 76 69 61 20 74 68 65 69 72 20 70 72 65 70 72 via their prepr
68c0: 6f 63 65 73 73 6f 72 20 28 65 2e 67 2e 20 69 66 ocessor (e.g. if
68d0: 20 74 68 65 79 20 63 75 73 74 6f 6d 69 7a 65 64 they customized
68e0: 20 74 68 65 69 72 20 47 43 43 20 74 6f 20 64 65 their GCC to de
68f0: 66 69 6e 65 0a 2a 2a 20 73 6f 6d 65 20 4d 69 6e fine.** some Min
6900: 47 57 2d 73 70 65 63 69 66 69 63 20 6d 61 63 72 GW-specific macr
6910: 6f 73 29 2e 20 20 57 68 65 6e 20 63 6f 6d 70 69 os). When compi
6920: 6c 69 6e 67 20 66 6f 72 20 4d 69 6e 47 57 2c 20 ling for MinGW,
6930: 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 5f 48 either the.** _H
6940: 41 56 45 5f 4d 49 4e 47 57 5f 48 20 6f 72 20 5f AVE_MINGW_H or _
6950: 48 41 56 45 5f 5f 4d 49 4e 47 57 5f 48 20 28 6e HAVE__MINGW_H (n
6960: 6f 74 65 20 74 68 65 20 65 78 74 72 61 20 75 6e ote the extra un
6970: 64 65 72 73 63 6f 72 65 29 20 6d 61 63 72 6f 20 derscore) macro
6980: 6d 75 73 74 20 62 65 0a 2a 2a 20 64 65 66 69 6e must be.** defin
6990: 65 64 3b 20 6f 74 68 65 72 77 69 73 65 2c 20 64 ed; otherwise, d
69a0: 65 74 65 63 74 69 6f 6e 20 6f 66 20 63 6f 6e 64 etection of cond
69b0: 69 74 69 6f 6e 73 20 73 70 65 63 69 66 69 63 20 itions specific
69c0: 74 6f 20 4d 69 6e 47 57 20 77 69 6c 6c 20 62 65 to MinGW will be
69d0: 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2f .** disabled..*/
69e0: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 48 41 .#if defined(_HA
69f0: 56 45 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e VE_MINGW_H).# in
6a00: 63 6c 75 64 65 20 22 6d 69 6e 67 77 2e 68 22 0a clude "mingw.h".
6a10: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 48 #elif defined(_H
6a20: 41 56 45 5f 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 AVE__MINGW_H).#
6a30: 69 6e 63 6c 75 64 65 20 22 5f 6d 69 6e 67 77 2e include "_mingw.
6a40: 68 22 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a h".#endif../*.**
6a50: 20 46 6f 72 20 4d 69 6e 47 57 20 76 65 72 73 69 For MinGW versi
6a60: 6f 6e 20 34 2e 78 20 28 61 6e 64 20 68 69 67 68 on 4.x (and high
6a70: 65 72 29 2c 20 63 68 65 63 6b 20 74 6f 20 73 65 er), check to se
6a80: 65 20 69 66 20 74 68 65 20 5f 55 53 45 5f 33 32 e if the _USE_32
6a90: 42 49 54 5f 54 49 4d 45 5f 54 0a 2a 2a 20 64 65 BIT_TIME_T.** de
6aa0: 66 69 6e 65 20 69 73 20 72 65 71 75 69 72 65 64 fine is required
6ab0: 20 74 6f 20 6d 61 69 6e 74 61 69 6e 20 62 69 6e to maintain bin
6ac0: 61 72 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 ary compatibilit
6ad0: 79 20 77 69 74 68 20 74 68 65 20 4d 53 56 43 20 y with the MSVC
6ae0: 72 75 6e 74 69 6d 65 0a 2a 2a 20 6c 69 62 72 61 runtime.** libra
6af0: 72 79 20 69 6e 20 75 73 65 20 28 65 2e 67 2e 20 ry in use (e.g.
6b00: 66 6f 72 20 57 69 6e 64 6f 77 73 20 58 50 29 2e for Windows XP).
6b10: 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e 65 64 .*/.#if !defined
6b20: 28 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 (_USE_32BIT_TIME
6b30: 5f 54 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 _T) && !defined(
6b40: 5f 55 53 45 5f 36 34 42 49 54 5f 54 49 4d 45 5f _USE_64BIT_TIME_
6b50: 54 29 20 26 26 20 5c 0a 20 20 20 20 64 65 66 69 T) && \. defi
6b60: 6e 65 64 28 5f 57 49 4e 33 32 29 20 26 26 20 21 ned(_WIN32) && !
6b70: 64 65 66 69 6e 65 64 28 5f 57 49 4e 36 34 29 20 defined(_WIN64)
6b80: 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 && \. defined
6b90: 28 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56 (__MINGW_MAJOR_V
6ba0: 45 52 53 49 4f 4e 29 20 26 26 20 5f 5f 4d 49 4e ERSION) && __MIN
6bb0: 47 57 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e GW_MAJOR_VERSION
6bc0: 20 3e 3d 20 34 20 26 26 20 5c 0a 20 20 20 20 64 >= 4 && \. d
6bd0: 65 66 69 6e 65 64 28 5f 5f 4d 53 56 43 52 54 5f efined(__MSVCRT_
6be0: 5f 29 0a 23 20 64 65 66 69 6e 65 20 5f 55 53 45 _).# define _USE
6bf0: 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54 0a 23 65 _32BIT_TIME_T.#e
6c00: 6e 64 69 66 0a 0a 2f 2a 20 54 68 65 20 70 75 62 ndif../* The pub
6c10: 6c 69 63 20 53 51 4c 69 74 65 20 69 6e 74 65 72 lic SQLite inter
6c20: 66 61 63 65 2e 20 20 54 68 65 20 5f 46 49 4c 45 face. The _FILE
6c30: 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 6d 61 63 _OFFSET_BITS mac
6c40: 72 6f 20 6d 75 73 74 20 61 70 70 65 61 72 0a 2a ro must appear.*
6c50: 2a 20 66 69 72 73 74 20 69 6e 20 51 4e 58 2e 20 * first in QNX.
6c60: 20 41 6c 73 6f 2c 20 74 68 65 20 5f 55 53 45 5f Also, the _USE_
6c70: 33 32 42 49 54 5f 54 49 4d 45 5f 54 20 6d 61 63 32BIT_TIME_T mac
6c80: 72 6f 20 6d 75 73 74 20 61 70 70 65 61 72 20 66 ro must appear f
6c90: 69 72 73 74 20 66 6f 72 0a 2a 2a 20 4d 69 6e 47 irst for.** MinG
6ca0: 57 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a W..*/./*********
6cb0: 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 ***** Include sq
6cc0: 6c 69 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d lite3.h in the m
6cd0: 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 iddle of sqliteI
6ce0: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a nt.h ***********
6cf0: 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a ****/./*********
6d00: 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 ***** Begin file
6d10: 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a sqlite3.h *****
6d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
6d30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
6d40: 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 ****/./*.** 2001
6d50: 2d 30 39 2d 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 -09-15.**.** The
6d60: 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d author disclaim
6d70: 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 s copyright to t
6d80: 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e his source code.
6d90: 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a In place of.**
6da0: 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c a legal notice,
6db0: 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 here is a bless
6dc0: 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 ing:.**.** Ma
6dd0: 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e y you do good an
6de0: 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 d not evil..**
6df0: 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 May you find f
6e00: 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 orgiveness for y
6e10: 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 ourself and forg
6e20: 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 ive others..**
6e30: 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 May you share
6e40: 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 freely, never ta
6e50: 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 king more than y
6e60: 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a ou give..**.****
6e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
6e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
6e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
6ea0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
6eb0: 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 65 *****.** This he
6ec0: 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e 65 ader file define
6ed0: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 s the interface
6ee0: 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 20 that the SQLite
6ef0: 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 65 library.** prese
6f00: 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 72 nts to client pr
6f10: 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 2d ograms. If a C-
6f20: 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 74 function, struct
6f30: 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a 2a ure, datatype,.*
6f40: 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 65 * or constant de
6f50: 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e 6f finition does no
6f60: 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 73 t appear in this
6f70: 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 69 file, then it i
6f80: 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c 69 s.** not a publi
6f90: 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c 69 shed API of SQLi
6fa0: 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 74 te, is subject t
6fb0: 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74 o change without
6fc0: 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 20 .** notice, and
6fd0: 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 65 should not be re
6fe0: 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f 67 ferenced by prog
6ff0: 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 51 rams that use SQ
7000: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 Lite..**.** Some
7010: 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 69 of the definiti
7020: 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e 20 ons that are in
7030: 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d 61 this file are ma
7040: 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 65 rked as.** "expe
7050: 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 65 rimental". Expe
7060: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 rimental interfa
7070: 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 ces are normally
7080: 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 73 new.** features
7090: 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 20 recently added
70a0: 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 64 to SQLite. We d
70b0: 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 65 o not anticipate
70c0: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 changes.** to e
70d0: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 xperimental inte
70e0: 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 72 rfaces but reser
70f0: 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f 20 ve the right to
7100: 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 make minor chang
7110: 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 65 es.** if experie
7120: 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 6e nce from use "in
7130: 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 65 the wild" sugge
7140: 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 20 st such changes
7150: 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a are prudent..**.
7160: 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c 20 ** The official
7170: 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 64 C-language API d
7180: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 ocumentation for
7190: 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 76 SQLite is deriv
71a0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 ed.** from comme
71b0: 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c 65 nts in this file
71c0: 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 . This file is
71d0: 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 76 the authoritativ
71e0: 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 e source.** on h
71f0: 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 ow SQLite interf
7200: 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 65 aces are suppose
7210: 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a d to operate..**
7220: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 .** The name of
7230: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20 this file under
7240: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 configuration ma
7250: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c nagement is "sql
7260: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 ite.h.in"..** Th
7270: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 e makefile makes
7280: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e some minor chan
7290: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65 ges to this file
72a0: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74 (such as insert
72b0: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 ing.** the versi
72c0: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 on number) and c
72d0: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20 hanges its name
72e0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61 to "sqlite3.h" a
72f0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65 s.** part of the
7300: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a build process..
7310: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 */.#ifndef SQLIT
7320: 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51 4c E3_H.#define SQL
7330: 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65 20 ITE3_H.#include
7340: 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20 2f <stdarg.h> /
7350: 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68 65 * Needed for the
7360: 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 definition of v
7370: 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a a_list */../*.**
7380: 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63 61 Make sure we ca
7390: 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75 66 n call this stuf
73a0: 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 f from C++..*/.#
73b0: 69 66 20 30 0a 65 78 74 65 72 6e 20 22 43 22 20 if 0.extern "C"
73c0: 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a {.#endif.../*.**
73d0: 20 50 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 Provide the abi
73e0: 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 lity to override
73f0: 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 linkage feature
7400: 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 s of the interfa
7410: 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 ce..*/.#ifndef S
7420: 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 QLITE_EXTERN.# d
7430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 efine SQLITE_EXT
7440: 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 ERN extern.#endi
7450: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 f.#ifndef SQLITE
7460: 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 _API.# define SQ
7470: 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a LITE_API.#endif.
7480: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 #ifndef SQLITE_C
7490: 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 DECL.# define SQ
74a0: 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 LITE_CDECL.#endi
74b0: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 f.#ifndef SQLITE
74c0: 5f 41 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e _APICALL.# defin
74d0: 65 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c e SQLITE_APICALL
74e0: 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 .#endif.#ifndef
74f0: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 SQLITE_STDCALL.#
7500: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 define SQLITE_S
7510: 54 44 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 TDCALL SQLITE_AP
7520: 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 ICALL.#endif.#if
7530: 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c ndef SQLITE_CALL
7540: 42 41 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 BACK.# define SQ
7550: 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 LITE_CALLBACK.#e
7560: 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c ndif.#ifndef SQL
7570: 49 54 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 ITE_SYSAPI.# def
7580: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 ine SQLITE_SYSAP
7590: 49 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 I.#endif../*.**
75a0: 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 These no-op macr
75b0: 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 os are used in f
75c0: 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 ront of interfac
75d0: 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 es to mark those
75e0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 .** interfaces a
75f0: 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63 61 s either depreca
7600: 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e ted or experimen
7610: 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 tal. New applic
7620: 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 ations.** should
7630: 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 not use depreca
7640: 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d ted interfaces -
7650: 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 they are suppor
7660: 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ted for backward
7670: 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 s.** compatibili
7680: 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 ty only. Applic
7690: 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 ation writers sh
76a0: 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 ould be aware th
76b0: 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 at.** experiment
76c0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 al interfaces ar
76d0: 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 e subject to cha
76e0: 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c nge in point rel
76f0: 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 eases..**.** The
7700: 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 se macros used t
7710: 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 o resolve to var
7720: 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f ious kinds of co
7730: 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 mpiler magic tha
7740: 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 t.** would gener
7750: 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 ate warning mess
7760: 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 ages when they w
7770: 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 ere used. But t
7780: 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 hat.** compiler
7790: 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 magic ended up g
77a0: 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 enerating such a
77b0: 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 flurry of bug r
77c0: 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 eports.** that w
77d0: 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 e have taken it
77e0: 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 all out and gone
77f0: 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 back to using s
7800: 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 imple.** noop ma
7810: 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 cros..*/.#define
7820: 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 SQLITE_DEPRECAT
7830: 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 ED.#define SQLIT
7840: 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a E_EXPERIMENTAL..
7850: 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 /*.** Ensure the
7860: 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 se symbols were
7870: 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 not defined by s
7880: 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 ome previous hea
7890: 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 der file..*/.#if
78a0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 def SQLITE_VERSI
78b0: 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 ON.# undef SQLIT
78c0: 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 E_VERSION.#endif
78d0: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 .#ifdef SQLITE_V
78e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 ERSION_NUMBER.#
78f0: 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 undef SQLITE_VER
7900: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 SION_NUMBER.#end
7910: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 if../*.** CAPI3R
7920: 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 EF: Compile-Time
7930: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e Library Version
7940: 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e Numbers.**.** ^
7950: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 (The [SQLITE_VER
7960: 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 SION] C preproce
7970: 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 ssor macro in th
7980: 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 e sqlite3.h head
7990: 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 er.** evaluates
79a0: 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 to a string lite
79b0: 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 ral that is the
79c0: 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 SQLite version i
79d0: 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 n the.** format
79e0: 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 "X.Y.Z" where X
79f0: 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 is the major ver
7a00: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 sion number (alw
7a10: 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c ays 3 for.** SQL
7a20: 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 ite3) and Y is t
7a30: 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e he minor version
7a40: 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 number and Z is
7a50: 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d the release num
7a60: 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 ber.)^.** ^(The
7a70: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f [SQLITE_VERSION_
7a80: 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f NUMBER] C prepro
7a90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 cessor macro res
7aa0: 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 olves to an inte
7ab0: 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 ger.** with the
7ac0: 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 value (X*1000000
7ad0: 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 + Y*1000 + Z) w
7ae0: 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a here X, Y, and Z
7af0: 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a are the same.**
7b00: 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e numbers used in
7b10: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
7b20: 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 ].)^.** The SQLI
7b30: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 TE_VERSION_NUMBE
7b40: 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 R for any given
7b50: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 release of SQLit
7b60: 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 e will also.** b
7b70: 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 e larger than th
7b80: 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 e release from w
7b90: 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69 76 hich it is deriv
7ba0: 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 ed. Either Y wi
7bb0: 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f ll.** be held co
7bc0: 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c nstant and Z wil
7bd0: 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 l be incremented
7be0: 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 or else Y will
7bf0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a be incremented.*
7c00: 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 * and Z will be
7c10: 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a reset to zero..*
7c20: 2a 0a 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 *.** Since [vers
7c30: 69 6f 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 ion 3.6.18] ([da
7c40: 74 65 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a teof:3.6.18]), .
7c50: 2a 2a 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 ** SQLite source
7c60: 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 code has been s
7c70: 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 tored in the.**
7c80: 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f <a href="http://
7c90: 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f www.fossil-scm.o
7ca0: 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 rg/">Fossil conf
7cb0: 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 iguration manage
7cc0: 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f ment.** system</
7cd0: 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 a>. ^The SQLITE
7ce0: 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f _SOURCE_ID macro
7cf0: 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a evaluates to.**
7d00: 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 a string which
7d10: 69 64 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 identifies a par
7d20: 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e ticular check-in
7d30: 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 of SQLite.** wi
7d40: 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 thin its configu
7d50: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e ration managemen
7d60: 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 t system. ^The
7d70: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
7d80: 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 .** string conta
7d90: 69 6e 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 ins the date and
7da0: 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 time of the che
7db0: 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 ck-in (UTC) and
7dc0: 61 20 53 48 41 31 0a 2a 2a 20 6f 72 20 53 48 41 a SHA1.** or SHA
7dd0: 33 2d 32 35 36 20 68 61 73 68 20 6f 66 20 74 68 3-256 hash of th
7de0: 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 e entire source
7df0: 74 72 65 65 2e 20 20 49 66 20 74 68 65 20 73 6f tree. If the so
7e00: 75 72 63 65 20 63 6f 64 65 20 68 61 73 0a 2a 2a urce code has.**
7e10: 20 62 65 65 6e 20 65 64 69 74 65 64 20 69 6e 20 been edited in
7e20: 61 6e 79 20 77 61 79 20 73 69 6e 63 65 20 69 74 any way since it
7e30: 20 77 61 73 20 6c 61 73 74 20 63 68 65 63 6b 65 was last checke
7e40: 64 20 69 6e 2c 20 74 68 65 6e 20 74 68 65 20 6c d in, then the l
7e50: 61 73 74 0a 2a 2a 20 66 6f 75 72 20 68 65 78 61 ast.** four hexa
7e60: 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 6f decimal digits o
7e70: 66 20 74 68 65 20 68 61 73 68 20 6d 61 79 20 62 f the hash may b
7e80: 65 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a e modified..**.*
7e90: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c * See also: [sql
7ea0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
7eb0: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
7ec0: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 libversion_numbe
7ed0: 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 r()], [sqlite3_s
7ee0: 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b ourceid()],.** [
7ef0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 sqlite_version()
7f00: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f ] and [sqlite_so
7f10: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 urce_id()]..*/.#
7f20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 define SQLITE_VE
7f30: 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33 2e RSION "3.
7f40: 32 33 2e 30 22 0a 23 64 65 66 69 6e 65 20 53 51 23.0".#define SQ
7f50: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d LITE_VERSION_NUM
7f60: 42 45 52 20 33 30 32 33 30 30 30 0a 23 64 65 66 BER 3023000.#def
7f70: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 ine SQLITE_SOURC
7f80: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 38 2d E_ID "2018-
7f90: 30 32 2d 30 38 20 30 31 3a 30 30 3a 31 31 20 61 02-08 01:00:11 a
7fa0: 64 35 64 33 62 64 63 37 33 39 61 30 39 39 37 37 d5d3bdc739a09977
7fb0: 38 36 66 39 34 66 62 35 37 38 39 62 37 32 36 62 86f94fb5789b726b
7fc0: 39 66 35 33 66 66 38 38 33 32 32 36 30 39 33 39 9f53ff8832260939
7fd0: 32 34 33 33 38 66 65 35 30 30 30 39 32 32 62 22 24338fe5000922b"
7fe0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
7ff0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 : Run-Time Libra
8000: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 ry Version Numbe
8010: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 rs.** KEYWORDS:
8020: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 20 sqlite3_version
8030: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 sqlite3_sourceid
8040: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 .**.** These int
8050: 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 erfaces provide
8060: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 the same informa
8070: 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c tion as the [SQL
8080: 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a ITE_VERSION],.**
8090: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e [SQLITE_VERSION
80a0: 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 _NUMBER], and [S
80b0: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d QLITE_SOURCE_ID]
80c0: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 C preprocessor
80d0: 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 macros.** but ar
80e0: 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 e associated wit
80f0: 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e h the library in
8100: 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 stead of the hea
8110: 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 der file. ^(Cau
8120: 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d tious.** program
8130: 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 mers might inclu
8140: 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 de assert() stat
8150: 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 ements in their
8160: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a application to.*
8170: 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 * verify that va
8180: 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 lues returned by
8190: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 these interface
81a0: 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 s match the macr
81b0: 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 os in.** the hea
81c0: 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e der, and thus en
81d0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 sure that the ap
81e0: 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 plication is.**
81f0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 compiled with ma
8200: 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 tching library a
8210: 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e nd header files.
8220: 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
8230: 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 te><pre>.** asse
8240: 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 rt( sqlite3_libv
8250: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d ersion_number()=
8260: 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f =SQLITE_VERSION_
8270: 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 NUMBER );.** ass
8280: 65 72 74 28 20 73 74 72 6e 63 6d 70 28 73 71 6c ert( strncmp(sql
8290: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c ite3_sourceid(),
82a0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 SQLITE_SOURCE_ID
82b0: 2c 38 30 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 ,80)==0 );.** as
82c0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c sert( strcmp(sql
82d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
82e0: 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e ),SQLITE_VERSION
82f0: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 )==0 );.** </pre
8300: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e ></blockquote>)^
8310: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
8320: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 te3_version[] st
8330: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f ring constant co
8340: 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 ntains the text
8350: 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 of [SQLITE_VERSI
8360: 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e ON].** macro. ^
8370: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 The sqlite3_libv
8380: 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f ersion() functio
8390: 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e n returns a poin
83a0: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f ter to the.** to
83b0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 the sqlite3_ver
83c0: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f sion[] string co
83d0: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c nstant. The sql
83e0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 ite3_libversion(
83f0: 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 ).** function is
8400: 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 provided for us
8410: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 e in DLLs since
8420: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c DLL users usuall
8430: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a y do not have.**
8440: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 direct access t
8450: 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e o string constan
8460: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c ts within the DL
8470: 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 L. ^The.** sqli
8480: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e te3_libversion_n
8490: 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e umber() function
84a0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 returns an inte
84b0: 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 ger equal to.**
84c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f [SQLITE_VERSION_
84d0: 4e 55 4d 42 45 52 5d 2e 20 20 5e 28 54 68 65 20 NUMBER]. ^(The
84e0: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 sqlite3_sourceid
84f0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 () function retu
8500: 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 rns .** a pointe
8510: 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f r to a string co
8520: 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c nstant whose val
8530: 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 ue is the same a
8540: 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 s the .** [SQLIT
8550: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 E_SOURCE_ID] C p
8560: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 reprocessor macr
8570: 6f 2e 20 20 45 78 63 65 70 74 20 69 66 20 53 51 o. Except if SQ
8580: 4c 69 74 65 20 69 73 20 62 75 69 6c 74 0a 2a 2a Lite is built.**
8590: 20 75 73 69 6e 67 20 61 6e 20 65 64 69 74 65 64 using an edited
85a0: 20 63 6f 70 79 20 6f 66 20 5b 74 68 65 20 61 6d copy of [the am
85b0: 61 6c 67 61 6d 61 74 69 6f 6e 5d 2c 20 74 68 65 algamation], the
85c0: 6e 20 74 68 65 20 6c 61 73 74 20 66 6f 75 72 20 n the last four
85d0: 63 68 61 72 61 63 74 65 72 73 0a 2a 2a 20 6f 66 characters.** of
85e0: 20 74 68 65 20 68 61 73 68 20 6d 69 67 68 74 20 the hash might
85f0: 62 65 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f be different fro
8600: 6d 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 m [SQLITE_SOURCE
8610: 5f 49 44 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 _ID].)^.**.** Se
8620: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f e also: [sqlite_
8630: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b version()] and [
8640: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 sqlite_source_id
8650: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
8660: 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 PI const char sq
8670: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 lite3_version[]
8680: 3d 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e = SQLITE_VERSION
8690: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e ;.SQLITE_API con
86a0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 st char *sqlite3
86b0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 _libversion(void
86c0: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f );.SQLITE_API co
86d0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
86e0: 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3_sourceid(void)
86f0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
8700: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 sqlite3_libvers
8710: 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 ion_number(void)
8720: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
8730: 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 F: Run-Time Libr
8740: 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 ary Compilation
8750: 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 Options Diagnost
8760: 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ics.**.** ^The s
8770: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 qlite3_compileop
8780: 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 tion_used() func
8790: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f tion returns 0 o
87a0: 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 r 1 .** indicati
87b0: 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 ng whether the s
87c0: 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 pecified option
87d0: 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a was defined at .
87e0: 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e ** compile time.
87f0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 ^The SQLITE_ p
8800: 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 refix may be omi
8810: 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a tted from the .*
8820: 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 * option name pa
8830: 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f ssed to sqlite3_
8840: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 compileoption_us
8850: 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 ed(). .**.** ^T
8860: 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 he sqlite3_compi
8870: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 leoption_get() f
8880: 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 unction allows i
8890: 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 terating.** over
88a0: 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 the list of opt
88b0: 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 ions that were d
88c0: 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c efined at compil
88d0: 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 e time by.** ret
88e0: 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 urning the N-th
88f0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 compile time opt
8900: 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 ion string. ^If
8910: 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e N is out of ran
8920: 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 ge,.** sqlite3_c
8930: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 ompileoption_get
8940: 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c () returns a NUL
8950: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 L pointer. ^The
8960: 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 SQLITE_ .** pre
8970: 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 fix is omitted f
8980: 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 rom any strings
8990: 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 returned by .**
89a0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f sqlite3_compileo
89b0: 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a ption_get()..**.
89c0: 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 ** ^Support for
89d0: 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 the diagnostic f
89e0: 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 unctions sqlite3
89f0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 _compileoption_u
8a00: 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c sed().** and sql
8a10: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
8a20: 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 on_get() may be
8a30: 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 omitted by speci
8a40: 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 fying the .** [S
8a50: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 QLITE_OMIT_COMPI
8a60: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 LEOPTION_DIAGS]
8a70: 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c option at compil
8a80: 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 e time..**.** Se
8a90: 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 e also: SQL func
8aa0: 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f tions [sqlite_co
8ab0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 mpileoption_used
8ac0: 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 ()] and.** [sqli
8ad0: 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e te_compileoption
8ae0: 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 _get()] and the
8af0: 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 [compile_options
8b00: 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 pragma]..*/.#if
8b10: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 ndef SQLITE_OMIT
8b20: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 _COMPILEOPTION_D
8b30: 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 IAGS.SQLITE_API
8b40: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 int sqlite3_comp
8b50: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 ileoption_used(c
8b60: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e onst char *zOptN
8b70: 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ame);.SQLITE_API
8b80: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c const char *sql
8b90: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 ite3_compileopti
8ba0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 on_get(int N);.#
8bb0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 endif../*.** CAP
8bc0: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 I3REF: Test To S
8bd0: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 ee If The Librar
8be0: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a y Is Threadsafe.
8bf0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
8c00: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 e3_threadsafe()
8c10: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 function returns
8c20: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c zero if and onl
8c30: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 y if.** SQLite w
8c40: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 as compiled with
8c50: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f mutexing code o
8c60: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 mitted due to th
8c70: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 e.** [SQLITE_THR
8c80: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 EADSAFE] compile
8c90: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 -time option bei
8ca0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a ng set to 0..**.
8cb0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 ** SQLite can be
8cc0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f compiled with o
8cd0: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 r without mutexe
8ce0: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 s. When.** the
8cf0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
8d00: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 FE] C preprocess
8d10: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 or macro is 1 or
8d20: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 2, mutexes.** a
8d30: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 re enabled and S
8d40: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 QLite is threads
8d50: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a afe. When the.*
8d60: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 * [SQLITE_THREAD
8d70: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 SAFE] macro is 0
8d80: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 , .** the mutexe
8d90: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 s are omitted.
8da0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 Without the mute
8db0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 xes, it is not s
8dc0: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 afe.** to use SQ
8dd0: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c Lite concurrentl
8de0: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e y from more than
8df0: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a one thread..**.
8e00: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 ** Enabling mute
8e10: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 xes incurs a mea
8e20: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 surable performa
8e30: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 nce penalty..**
8e40: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f So if speed is o
8e50: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 f utmost importa
8e60: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 nce, it makes se
8e70: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a nse to disable.*
8e80: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 * the mutexes.
8e90: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 But for maximum
8ea0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 safety, mutexes
8eb0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 should be enable
8ec0: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 d..** ^The defau
8ed0: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 lt behavior is f
8ee0: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 or mutexes to be
8ef0: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 enabled..**.**
8f00: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 This interface c
8f10: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e an be used by an
8f20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 application to
8f30: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 make sure that t
8f40: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 he.** version of
8f50: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 SQLite that it
8f60: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e is linking again
8f70: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 st was compiled
8f80: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 with.** the desi
8f90: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 red setting of t
8fa0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
8fb0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a DSAFE] macro..**
8fc0: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 .** This interfa
8fd0: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 ce only reports
8fe0: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 on the compile-t
8ff0: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e ime mutex settin
9000: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c g.** of the [SQL
9010: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 ITE_THREADSAFE]
9020: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 flag. If SQLite
9030: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 is compiled wit
9040: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 h.** SQLITE_THRE
9050: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 ADSAFE=1 or =2 t
9060: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 hen mutexes are
9070: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 enabled by defau
9080: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 lt but.** can be
9090: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 fully or partia
90a0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 lly disabled usi
90b0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 ng a call to [sq
90c0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a lite3_config()].
90d0: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 ** with the verb
90e0: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 s [SQLITE_CONFIG
90f0: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 _SINGLETHREAD],
9100: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d [SQLITE_CONFIG_M
9110: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 ULTITHREAD],.**
9120: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 or [SQLITE_CONFI
9130: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 G_SERIALIZED].
9140: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c ^(The return val
9150: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c ue of the.** sql
9160: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 ite3_threadsafe(
9170: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 ) function shows
9180: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c only the compil
9190: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f e-time setting o
91a0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 f.** thread safe
91b0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d ty, not any run-
91c0: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 time changes to
91d0: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 that setting mad
91e0: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f e by.** sqlite3_
91f0: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 config(). In oth
9200: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 er words, the re
9210: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 turn value from
9220: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 sqlite3_threadsa
9230: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 fe().** is uncha
9240: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f nged by calls to
9250: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
9260: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 ).)^.**.** See t
9270: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f he [threading mo
9280: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f de] documentatio
9290: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c n for additional
92a0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f information..*/
92b0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
92c0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 sqlite3_threadsa
92d0: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a fe(void);../*.**
92e0: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 CAPI3REF: Datab
92f0: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 ase Connection H
9300: 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 andle.** KEYWORD
9310: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e S: {database con
9320: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 nection} {databa
9330: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a se connections}.
9340: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 **.** Each open
9350: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 SQLite database
9360: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 is represented b
9370: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 y a pointer to a
9380: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a n instance of.**
9390: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 the opaque stru
93a0: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c cture named "sql
93b0: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 ite3". It is us
93c0: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 eful to think of
93d0: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 an sqlite3.** p
93e0: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a ointer as an obj
93f0: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 ect. The [sqlit
9400: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c e3_open()], [sql
9410: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 ite3_open16()],
9420: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
9430: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 open_v2()] inter
9440: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f faces are its co
9450: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 nstructors, and
9460: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 [sqlite3_close()
9470: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 ].** and [sqlite
9480: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 3_close_v2()] ar
9490: 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 e its destructor
94a0: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 s. There are ma
94b0: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 ny other.** inte
94c0: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a rfaces (such as.
94d0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 ** [sqlite3_prep
94e0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 are_v2()], [sqli
94f0: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 te3_create_funct
9500: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b ion()], and.** [
9510: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
9520: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 eout()] to name
9530: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20 but three) that
9540: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 are methods on a
9550: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a n.** sqlite3 obj
9560: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 ect..*/.typedef
9570: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 struct sqlite3 s
9580: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 qlite3;../*.** C
9590: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 API3REF: 64-Bit
95a0: 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a Integer Types.**
95b0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 KEYWORDS: sqlit
95c0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 e_int64 sqlite_u
95d0: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 int64.**.** Beca
95e0: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 use there is no
95f0: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 cross-platform w
9600: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 ay to specify 64
9610: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 -bit integer typ
9620: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 es.** SQLite inc
9630: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66 ludes typedefs f
9640: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 or 64-bit signed
9650: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e and unsigned in
9660: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 tegers..**.** Th
9670: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 e sqlite3_int64
9680: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 and sqlite3_uint
9690: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65 64 are the prefe
96a0: 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 rred type defini
96b0: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 tions..** The sq
96c0: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 lite_int64 and s
96d0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 qlite_uint64 typ
96e0: 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 es are supported
96f0: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a for backwards.*
9700: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 * compatibility
9710: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 only..**.** ^The
9720: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 sqlite3_int64 a
9730: 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 nd sqlite_int64
9740: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 types can store
9750: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a integer values.*
9760: 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 * between -92233
9770: 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61 72036854775808 a
9780: 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 nd +922337203685
9790: 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 4775807 inclusiv
97a0: 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 e. ^The.** sqli
97b0: 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 te3_uint64 and s
97c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 qlite_uint64 typ
97d0: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 es can store int
97e0: 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 eger values .**
97f0: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 between 0 and +1
9800: 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31 8446744073709551
9810: 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 615 inclusive..*
9820: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f /.#ifdef SQLITE_
9830: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 INT64_TYPE. typ
9840: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 edef SQLITE_INT6
9850: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 4_TYPE sqlite_in
9860: 74 36 34 3b 0a 23 20 69 66 64 65 66 20 53 51 4c t64;.# ifdef SQL
9870: 49 54 45 5f 55 49 4e 54 36 34 5f 54 59 50 45 0a ITE_UINT64_TYPE.
9880: 20 20 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 typedef SQLI
9890: 54 45 5f 55 49 4e 54 36 34 5f 54 59 50 45 20 73 TE_UINT64_TYPE s
98a0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 qlite_uint64;.#
98b0: 65 6c 73 65 20 20 0a 20 20 20 20 74 79 70 65 64 else . typed
98c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 ef unsigned SQLI
98d0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 TE_INT64_TYPE sq
98e0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 20 65 lite_uint64;.# e
98f0: 6e 64 69 66 0a 23 65 6c 69 66 20 64 65 66 69 6e ndif.#elif defin
9900: 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 ed(_MSC_VER) ||
9910: 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e defined(__BORLAN
9920: 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 DC__). typedef
9930: 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 __int64 sqlite_i
9940: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 nt64;. typedef
9950: 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 unsigned __int64
9960: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a sqlite_uint64;.
9970: 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 #else. typedef
9980: 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 long long int sq
9990: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 lite_int64;. ty
99a0: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c pedef unsigned l
99b0: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c ong long int sql
99c0: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 ite_uint64;.#end
99d0: 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 if.typedef sqlit
99e0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f e_int64 sqlite3_
99f0: 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 int64;.typedef s
9a00: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c qlite_uint64 sql
9a10: 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a ite3_uint64;../*
9a20: 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 .** If compiling
9a30: 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 for a processor
9a40: 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 that lacks floa
9a50: 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f ting point suppo
9a60: 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 rt,.** substitut
9a70: 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c e integer for fl
9a80: 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f oating-point..*/
9a90: 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f .#ifdef SQLITE_O
9aa0: 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 MIT_FLOATING_POI
9ab0: 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 NT.# define doub
9ac0: 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 le sqlite3_int64
9ad0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 .#endif../*.** C
9ae0: 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 API3REF: Closing
9af0: 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e A Database Conn
9b00: 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 ection.** DESTRU
9b10: 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a CTOR: sqlite3.**
9b20: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
9b30: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c _close() and sql
9b40: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 ite3_close_v2()
9b50: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 routines are des
9b60: 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 tructors.** for
9b70: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 the [sqlite3] ob
9b80: 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 ject..** ^Calls
9b90: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 to sqlite3_close
9ba0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 () and sqlite3_c
9bb0: 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e lose_v2() return
9bc0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a [SQLITE_OK] if.
9bd0: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d ** the [sqlite3]
9be0: 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 object is succe
9bf0: 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 ssfully destroye
9c00: 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 d and all associ
9c10: 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 ated.** resource
9c20: 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 s are deallocate
9c30: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 d..**.** ^If the
9c40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
9c50: 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 tion is associat
9c60: 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 ed with unfinali
9c70: 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 zed prepared.**
9c80: 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e statements or un
9c90: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 finished sqlite3
9ca0: 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 _backup objects
9cb0: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f then sqlite3_clo
9cc0: 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 se().** will lea
9cd0: 76 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ve the database
9ce0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 connection open
9cf0: 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 and return [SQLI
9d00: 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 TE_BUSY]..** ^If
9d10: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 sqlite3_close_v
9d20: 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 2() is called wi
9d30: 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 th unfinalized p
9d40: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
9d50: 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 ts.** and/or unf
9d60: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f inished sqlite3_
9d70: 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 backups, then th
9d80: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
9d90: 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a ction becomes.**
9da0: 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f an unusable "zo
9db0: 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c mbie" which will
9dc0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 automatically b
9dd0: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 e deallocated wh
9de0: 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 en the.** last p
9df0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
9e00: 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f t is finalized o
9e10: 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 r the last sqlit
9e20: 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 e3_backup is.**
9e30: 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 finished. The s
9e40: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 qlite3_close_v2(
9e50: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 ) interface is i
9e60: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 ntended for use
9e70: 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e with.** host lan
9e80: 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20 guages that are
9e90: 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 garbage collecte
9ea0: 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 d, and where the
9eb0: 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a order in which.
9ec0: 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 ** destructors a
9ed0: 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 re called is arb
9ee0: 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 itrary..**.** Ap
9ef0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c plications shoul
9f00: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c d [sqlite3_final
9f10: 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 ize | finalize]
9f20: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 all [prepared st
9f30: 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 atements],.** [s
9f40: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 qlite3_blob_clos
9f50: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b e | close] all [
9f60: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 BLOB handles], a
9f70: 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nd .** [sqlite3_
9f80: 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 backup_finish |
9f90: 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c finish] all [sql
9fa0: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a ite3_backup] obj
9fb0: 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a ects associated.
9fc0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c ** with the [sql
9fd0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 ite3] object pri
9fe0: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 or to attempting
9ff0: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 to close the ob
a000: 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 ject. ^If.** sq
a010: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
a020: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 is called on a
a030: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
a040: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c tion] that still
a050: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 has.** outstand
a060: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 ing [prepared st
a070: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 atements], [BLOB
a080: 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f handles], and/o
a090: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 r.** [sqlite3_ba
a0a0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 ckup] objects th
a0b0: 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 en it returns [S
a0c0: 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 QLITE_OK] and th
a0d0: 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a e deallocation.*
a0e0: 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 * of resources i
a0f0: 73 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c s deferred until
a100: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 all [prepared s
a110: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f tatements], [BLO
a120: 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 B handles],.** a
a130: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b nd [sqlite3_back
a140: 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 up] objects are
a150: 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a also destroyed..
a160: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 **.** ^If an [sq
a170: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 lite3] object is
a180: 20 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 destroyed while
a190: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 a transaction i
a1a0: 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 s open,.** the t
a1b0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 ransaction is au
a1c0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c tomatically roll
a1d0: 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 ed back..**.** T
a1e0: 68 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 he C parameter t
a1f0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 o [sqlite3_close
a200: 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 (C)] and [sqlite
a210: 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 3_close_v2(C)].*
a220: 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 * must be either
a230: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 a NULL.** point
a240: 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 er or an [sqlite
a250: 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 3] object pointe
a260: 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 r obtained.** fr
a270: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e om [sqlite3_open
a280: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 ()], [sqlite3_op
a290: 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b en16()], or.** [
a2a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
a2b0: 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 )], and not prev
a2c0: 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a iously closed..*
a2d0: 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 * ^Calling sqlit
a2e0: 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 e3_close() or sq
a2f0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 lite3_close_v2()
a300: 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 with a NULL poi
a310: 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 nter.** argument
a320: 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e is a harmless n
a330: 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f o-op..*/.SQLITE_
a340: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
a350: 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b close(sqlite3*);
a360: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
a370: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 sqlite3_close_v2
a380: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
a390: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 ** The type for
a3a0: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 a callback funct
a3b0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 ion..** This is
a3c0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 legacy and depre
a3d0: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e cated. It is in
a3e0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f cluded for histo
a3f0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 rical.** compati
a400: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f bility and is no
a410: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f t documented..*/
a420: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 .typedef int (*s
a430: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 qlite3_callback)
a440: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a (void*,int,char*
a450: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a *, char**);../*.
a460: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 ** CAPI3REF: One
a470: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63 -Step Query Exec
a480: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a ution Interface.
a490: 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
a4a0: 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e3.**.** The sql
a4b0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 ite3_exec() inte
a4c0: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 rface is a conve
a4d0: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 nience wrapper a
a4e0: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 round.** [sqlite
a4f0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
a500: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 [sqlite3_step()
a510: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ], and [sqlite3_
a520: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 finalize()],.**
a530: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 that allows an a
a540: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 pplication to ru
a550: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 n multiple state
a560: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 ments of SQL.**
a570: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 without having t
a580: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 o use a lot of C
a590: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 code. .**.** ^T
a5a0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 he sqlite3_exec(
a5b0: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 ) interface runs
a5c0: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 zero or more UT
a5d0: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 F-8 encoded,.**
a5e0: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 semicolon-separa
a5f0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 te SQL statement
a600: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 s passed into it
a610: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a s 2nd argument,.
a620: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 ** in the contex
a630: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 t of the [databa
a640: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 se connection] p
a650: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 assed in as its
a660: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 1st.** argument.
a670: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 ^If the callba
a680: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 ck function of t
a690: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 he 3rd argument
a6a0: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 to.** sqlite3_ex
a6b0: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c ec() is not NULL
a6c0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 , then it is inv
a6d0: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 oked for each re
a6e0: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 sult row.** comi
a6f0: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 ng out of the ev
a700: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 aluated SQL stat
a710: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 ements. ^The 4t
a720: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a h argument to.**
a730: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
a740: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 is relayed throu
a750: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 gh to the 1st ar
a760: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a gument of each.*
a770: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 * callback invoc
a780: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 ation. ^If the
a790: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 callback pointer
a7a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 to sqlite3_exec
a7b0: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 ().** is NULL, t
a7c0: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 hen no callback
a7d0: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 is ever invoked
a7e0: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 and result rows
a7f0: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a are.** ignored..
a800: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 **.** ^If an err
a810: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 or occurs while
a820: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 evaluating the S
a830: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 QL statements pa
a840: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c ssed into.** sql
a850: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 ite3_exec(), the
a860: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 n execution of t
a870: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 he current state
a880: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a ment stops and.*
a890: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 * subsequent sta
a8a0: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 tements are skip
a8b0: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 ped. ^If the 5t
a8c0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 h parameter to s
a8d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a qlite3_exec().**
a8e0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 is not NULL the
a8f0: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 n any error mess
a900: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 age is written i
a910: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 nto memory obtai
a920: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c ned.** from [sql
a930: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 ite3_malloc()] a
a940: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 nd passed back t
a950: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 hrough the 5th p
a960: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 arameter..** To
a970: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 avoid memory lea
a980: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 ks, the applicat
a990: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b ion should invok
a9a0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 e [sqlite3_free(
a9b0: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d )].** on error m
a9c0: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 essage strings r
a9d0: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 eturned through
a9e0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 the 5th paramete
a9f0: 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f r of.** sqlite3_
aa00: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65 exec() after the
aa10: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 error message s
aa20: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 tring is no long
aa30: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 er needed..** ^I
aa40: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 f the 5th parame
aa50: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 ter to sqlite3_e
aa60: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c xec() is not NUL
aa70: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a L and no errors.
aa80: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 ** occur, then s
aa90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 qlite3_exec() se
aaa0: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 ts the pointer i
aab0: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 n its 5th parame
aac0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 ter to.** NULL b
aad0: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e efore returning.
aae0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 .**.** ^If an sq
aaf0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c lite3_exec() cal
ab00: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f lback returns no
ab10: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 n-zero, the sqli
ab20: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f te3_exec().** ro
ab30: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 utine returns SQ
ab40: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f LITE_ABORT witho
ab50: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 ut invoking the
ab60: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 callback again a
ab70: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 nd.** without ru
ab80: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 nning any subseq
ab90: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 uent SQL stateme
aba0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 nts..**.** ^The
abb0: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 2nd argument to
abc0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 the sqlite3_exec
abd0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 () callback func
abe0: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e tion is the.** n
abf0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
ac00: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 in the result.
ac10: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 ^The 3rd argume
ac20: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 nt to the sqlite
ac30: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 3_exec().** call
ac40: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 back is an array
ac50: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 of pointers to
ac60: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 strings obtained
ac70: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b as if from.** [
ac80: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 sqlite3_column_t
ac90: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 ext()], one for
aca0: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 each column. ^I
acb0: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 f an element of
acc0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 a.** result row
acd0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 is NULL then the
ace0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 corresponding s
acf0: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f tring pointer fo
ad00: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 r the.** sqlite3
ad10: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b _exec() callback
ad20: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 is a NULL point
ad30: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 er. ^The 4th ar
ad40: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a gument to the.**
ad50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
ad60: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 callback is an a
ad70: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 rray of pointers
ad80: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 to strings wher
ad90: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 e each.** entry
ada0: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e represents the n
adb0: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e ame of correspon
adc0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 ding result colu
add0: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a mn as obtained.*
ade0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f * from [sqlite3_
adf0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a column_name()]..
ae00: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e **.** ^If the 2n
ae10: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 d parameter to s
ae20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 qlite3_exec() is
ae30: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c a NULL pointer,
ae40: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f a pointer.** to
ae50: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 an empty string
ae60: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 , or a pointer t
ae70: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c hat contains onl
ae80: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 y whitespace and
ae90: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d /or .** SQL comm
aea0: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 ents, then no SQ
aeb0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 L statements are
aec0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 evaluated and t
aed0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 he database.** i
aee0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a s not changed..*
aef0: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e *.** Restriction
af00: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a s:.**.** <ul>.**
af10: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 <li> The applic
af20: 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 ation must ensur
af30: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70 e that the 1st p
af40: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
af50: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 te3_exec().**
af60: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e is a valid an
af70: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 d open [database
af80: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a connection]..**
af90: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 <li> The applic
afa0: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 ation must not c
afb0: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 lose the [databa
afc0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 se connection] s
afd0: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 pecified by.**
afe0: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61 the 1st para
aff0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 meter to sqlite3
b000: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 _exec() while sq
b010: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 lite3_exec() is
b020: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e running..** <li>
b030: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e The application
b040: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 must not modify
b050: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 the SQL stateme
b060: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69 nt text passed i
b070: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 nto.** the
b080: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 2nd parameter of
b090: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 sqlite3_exec()
b0a0: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 while sqlite3_ex
b0b0: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e ec() is running.
b0c0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c .** </ul>.*/.SQL
b0d0: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
b0e0: 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 te3_exec(. sqli
b0f0: 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 te3*,
b100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b110: 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 /* An ope
b120: 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 n database */.
b130: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c const char *sql,
b140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b150: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 /* SQ
b160: 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 L to be evaluate
b170: 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c d */. int (*cal
b180: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 lback)(void*,int
b190: 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c ,char**,char**),
b1a0: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 /* Callback fu
b1b0: 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 nction */. void
b1c0: 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 *,
b1d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b1e0: 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 /* 1st ar
b1f0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 gument to callba
b200: 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 ck */. char **e
b210: 72 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 rrmsg
b220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
b230: 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 /* Error msg
b240: 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a written here */.
b250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
b260: 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 EF: Result Codes
b270: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 .** KEYWORDS: {r
b280: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e esult code defin
b290: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 itions}.**.** Ma
b2a0: 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 ny SQLite functi
b2b0: 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e ons return an in
b2c0: 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 teger result cod
b2d0: 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 e from the set s
b2e0: 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 hown.** here in
b2f0: 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 order to indicat
b300: 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 e success or fai
b310: 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 lure..**.** New
b320: 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 error codes may
b330: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 be added in futu
b340: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
b350: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 QLite..**.** See
b360: 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 also: [extended
b370: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 result code def
b380: 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 initions].*/.#de
b390: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 fine SQLITE_OK
b3a0: 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 0 /*
b3b0: 53 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c Successful resul
b3c0: 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e t */./* beginnin
b3d0: 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 g-of-error-codes
b3e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
b3f0: 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 TE_ERROR
b400: 31 20 20 20 2f 2a 20 47 65 6e 65 72 69 63 20 65 1 /* Generic e
b410: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 rror */.#define
b420: 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 SQLITE_INTERNAL
b430: 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 2 /* Inter
b440: 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 nal logic error
b450: 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 in SQLite */.#de
b460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d fine SQLITE_PERM
b470: 20 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 3 /*
b480: 41 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f Access permissio
b490: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 n denied */.#def
b4a0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 ine SQLITE_ABORT
b4b0: 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 4 /* C
b4c0: 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 allback routine
b4d0: 72 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f requested an abo
b4e0: 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 rt */.#define SQ
b4f0: 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 LITE_BUSY
b500: 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 5 /* The dat
b510: 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f abase file is lo
b520: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 cked */.#define
b530: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 SQLITE_LOCKED
b540: 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6 /* A tab
b550: 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 le in the databa
b560: 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a se is locked */.
b570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e #define SQLITE_N
b580: 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 OMEM 7
b590: 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 /* A malloc() fa
b5a0: 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 iled */.#define
b5b0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 SQLITE_READONLY
b5c0: 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 8 /* Attem
b5d0: 70 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 pt to write a re
b5e0: 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 adonly database
b5f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
b600: 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 E_INTERRUPT 9
b610: 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 /* Operation
b620: 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 terminated by sq
b630: 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 lite3_interrupt(
b640: 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 )*/.#define SQLI
b650: 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 TE_IOERR 1
b660: 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 0 /* Some kind
b670: 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 of disk I/O err
b680: 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 or occurred */.#
b690: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
b6a0: 52 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f RRUPT 11 /
b6b0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 * The database d
b6c0: 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c isk image is mal
b6d0: 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e formed */.#defin
b6e0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e e SQLITE_NOTFOUN
b6f0: 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b D 12 /* Unk
b700: 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 nown opcode in s
b710: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
b720: 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 rol() */.#define
b730: 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 SQLITE_FULL
b740: 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 13 /* Inse
b750: 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 rtion failed bec
b760: 61 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 ause database is
b770: 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 full */.#define
b780: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
b790: 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 14 /* Unab
b7a0: 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 le to open the d
b7b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a atabase file */.
b7c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 #define SQLITE_P
b7d0: 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 ROTOCOL 15
b7e0: 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b /* Database lock
b7f0: 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 protocol error
b800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
b810: 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 E_EMPTY 16
b820: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 75 /* Internal u
b830: 73 65 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 se only */.#defi
b840: 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 ne SQLITE_SCHEMA
b850: 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 17 /* Th
b860: 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d e database schem
b870: 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 a changed */.#de
b880: 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 fine SQLITE_TOOB
b890: 49 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 IG 18 /*
b8a0: 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 String or BLOB e
b8b0: 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 xceeds size limi
b8c0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c t */.#define SQL
b8d0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 ITE_CONSTRAINT
b8e0: 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 19 /* Abort du
b8f0: 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 e to constraint
b900: 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 violation */.#de
b910: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d fine SQLITE_MISM
b920: 41 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 ATCH 20 /*
b930: 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 Data type mismat
b940: 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 ch */.#define SQ
b950: 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 LITE_MISUSE
b960: 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 21 /* Library
b970: 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c used incorrectl
b980: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
b990: 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 ITE_NOLFS
b9a0: 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 22 /* Uses OS
b9b0: 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 features not sup
b9c0: 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a ported on host *
b9d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
b9e0: 5f 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 _AUTH 23
b9f0: 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 /* Authorizati
ba00: 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 on denied */.#de
ba10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d fine SQLITE_FORM
ba20: 41 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 AT 24 /*
ba30: 4e 6f 74 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 Not used */.#def
ba40: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 ine SQLITE_RANGE
ba50: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 25 /* 2
ba60: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 nd parameter to
ba70: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 sqlite3_bind out
ba80: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 of range */.#de
ba90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 fine SQLITE_NOTA
baa0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 DB 26 /*
bab0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 File opened that
bac0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 is not a databa
bad0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 se file */.#defi
bae0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 ne SQLITE_NOTICE
baf0: 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 27 /* No
bb00: 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d tifications from
bb10: 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a sqlite3_log() *
bb20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
bb30: 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 _WARNING 28
bb40: 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 /* Warnings fr
bb50: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 om sqlite3_log()
bb60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
bb70: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 TE_ROW 1
bb80: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 00 /* sqlite3_s
bb90: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 tep() has anothe
bba0: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 r row ready */.#
bbb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f define SQLITE_DO
bbc0: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f NE 101 /
bbd0: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 * sqlite3_step()
bbe0: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 has finished ex
bbf0: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e ecuting */./* en
bc00: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 d-of-error-codes
bc10: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 */../*.** CAPI3
bc20: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 REF: Extended Re
bc30: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 sult Codes.** KE
bc40: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 YWORDS: {extende
bc50: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 d result code de
bc60: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a finitions}.**.**
bc70: 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 In its default
bc80: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 configuration, S
bc90: 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e QLite API routin
bca0: 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 es return one of
bcb0: 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 30 integer.** [
bcc0: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 result codes].
bcd0: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 However, experie
bce0: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 nce has shown th
bcf0: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 at many of.** th
bd00: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 ese result codes
bd10: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d are too coarse-
bd20: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 grained. They d
bd30: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 o not provide as
bd40: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 .** much informa
bd50: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c tion about probl
bd60: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 ems as programme
bd70: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 rs might like.
bd80: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a In an effort to.
bd90: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c ** address this,
bda0: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 newer versions
bdb0: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 of SQLite (versi
bdc0: 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 on 3.3.8 [dateof
bdd0: 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c :3.3.8].** and l
bde0: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a ater) include.**
bdf0: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 support for add
be00: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 itional result c
be10: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 odes that provid
be20: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 e more detailed
be30: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 information.** a
be40: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 bout errors. The
be50: 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 se [extended res
be60: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 ult codes] are e
be70: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c nabled or disabl
be80: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 ed.** on a per d
be90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
bea0: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 on basis using t
beb0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 he.** [sqlite3_e
bec0: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 xtended_result_c
bed0: 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 odes()] API. Or
bee0: 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 , the extended c
bef0: 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d ode for.** the m
bf00: 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 ost recent error
bf10: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 can be obtained
bf20: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
bf30: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 e3_extended_errc
bf40: 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 ode()]..*/.#defi
bf50: 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 5f ne SQLITE_ERROR_
bf60: 4d 49 53 53 49 4e 47 5f 43 4f 4c 4c 53 45 51 20 MISSING_COLLSEQ
bf70: 20 20 28 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 (SQLITE_ERROR
bf80: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e | (1<<8)).#defin
bf90: 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 5f 52 e SQLITE_ERROR_R
bfa0: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 20 20 ETRY
bfb0: 20 28 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 7c (SQLITE_ERROR |
bfc0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (2<<8)).#define
bfd0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 SQLITE_IOERR_RE
bfe0: 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 AD
bff0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 (SQLITE_IOERR |
c000: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (1<<8)).#define
c010: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f SQLITE_IOERR_SHO
c020: 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 RT_READ (
c030: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 SQLITE_IOERR | (
c040: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
c050: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 QLITE_IOERR_WRIT
c060: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 E (S
c070: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 QLITE_IOERR | (3
c080: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
c090: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 LITE_IOERR_FSYNC
c0a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 (SQ
c0b0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c LITE_IOERR | (4<
c0c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
c0d0: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 ITE_IOERR_DIR_FS
c0e0: 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c YNC (SQL
c0f0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c ITE_IOERR | (5<<
c100: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
c110: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 TE_IOERR_TRUNCAT
c120: 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 E (SQLI
c130: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 TE_IOERR | (6<<8
c140: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
c150: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 E_IOERR_FSTAT
c160: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 (SQLIT
c170: 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 E_IOERR | (7<<8)
c180: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
c190: 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 _IOERR_UNLOCK
c1a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
c1b0: 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 _IOERR | (8<<8))
c1c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c1d0: 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 IOERR_RDLOCK
c1e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
c1f0: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a IOERR | (9<<8)).
c200: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c210: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 OERR_DELETE
c220: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c230: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a OERR | (10<<8)).
c240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c250: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 OERR_BLOCKED
c260: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c270: 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a OERR | (11<<8)).
c280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c290: 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 OERR_NOMEM
c2a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c2b0: 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a OERR | (12<<8)).
c2c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c2d0: 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 OERR_ACCESS
c2e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c2f0: 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a OERR | (13<<8)).
c300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c310: 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 OERR_CHECKRESERV
c320: 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 EDLOCK (SQLITE_I
c330: 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a OERR | (14<<8)).
c340: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c350: 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 OERR_LOCK
c360: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c370: 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a OERR | (15<<8)).
c380: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c390: 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 OERR_CLOSE
c3a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c3b0: 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a OERR | (16<<8)).
c3c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c3d0: 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 OERR_DIR_CLOSE
c3e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c3f0: 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a OERR | (17<<8)).
c400: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c410: 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 OERR_SHMOPEN
c420: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c430: 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a OERR | (18<<8)).
c440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c450: 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 OERR_SHMSIZE
c460: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c470: 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a OERR | (19<<8)).
c480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c490: 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 OERR_SHMLOCK
c4a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c4b0: 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a OERR | (20<<8)).
c4c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c4d0: 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 OERR_SHMMAP
c4e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c4f0: 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a OERR | (21<<8)).
c500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c510: 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 OERR_SEEK
c520: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c530: 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a OERR | (22<<8)).
c540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c550: 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e OERR_DELETE_NOEN
c560: 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 T (SQLITE_I
c570: 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a OERR | (23<<8)).
c580: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c590: 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 OERR_MMAP
c5a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c5b0: 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a OERR | (24<<8)).
c5c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c5d0: 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 OERR_GETTEMPPATH
c5e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c5f0: 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a OERR | (25<<8)).
c600: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c610: 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 OERR_CONVPATH
c620: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c630: 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a OERR | (26<<8)).
c640: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c650: 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 OERR_VNODE
c660: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c670: 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a OERR | (27<<8)).
c680: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c690: 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 OERR_AUTH
c6a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 (SQLITE_I
c6b0: 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a OERR | (28<<8)).
c6c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c6d0: 4f 45 52 52 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 OERR_BEGIN_ATOMI
c6e0: 43 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 C (SQLITE_I
c6f0: 4f 45 52 52 20 7c 20 28 32 39 3c 3c 38 29 29 0a OERR | (29<<8)).
c700: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c710: 4f 45 52 52 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d OERR_COMMIT_ATOM
c720: 49 43 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 IC (SQLITE_I
c730: 4f 45 52 52 20 7c 20 28 33 30 3c 3c 38 29 29 0a OERR | (30<<8)).
c740: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
c750: 4f 45 52 52 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 OERR_ROLLBACK_AT
c760: 4f 4d 49 43 20 20 20 28 53 51 4c 49 54 45 5f 49 OMIC (SQLITE_I
c770: 4f 45 52 52 20 7c 20 28 33 31 3c 3c 38 29 29 0a OERR | (31<<8)).
c780: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
c790: 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 OCKED_SHAREDCACH
c7a0: 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c E (SQLITE_L
c7b0: 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 OCKED | (1<<8))
c7c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
c7d0: 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 BUSY_RECOVERY
c7e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f (SQLITE_
c7f0: 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 BUSY | (1<<8)
c800: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
c810: 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 _BUSY_SNAPSHOT
c820: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 (SQLITE
c830: 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 _BUSY | (2<<8
c840: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
c850: 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d E_CANTOPEN_NOTEM
c860: 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 PDIR (SQLIT
c870: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c E_CANTOPEN | (1<
c880: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c <8)).#define SQL
c890: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 ITE_CANTOPEN_ISD
c8a0: 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c IR (SQL
c8b0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 ITE_CANTOPEN | (
c8c0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
c8d0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 QLITE_CANTOPEN_F
c8e0: 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 ULLPATH (S
c8f0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c QLITE_CANTOPEN |
c900: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 (3<<8)).#define
c910: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e SQLITE_CANTOPEN
c920: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 _CONVPATH
c930: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e (SQLITE_CANTOPEN
c940: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 | (4<<8)).#defi
c950: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 ne SQLITE_CORRUP
c960: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20 T_VTAB
c970: 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 (SQLITE_CORRUP
c980: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 T | (1<<8)).#def
c990: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f ine SQLITE_READO
c9a0: 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 NLY_RECOVERY
c9b0: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f (SQLITE_READO
c9c0: 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 NLY | (1<<8)).#d
c9d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 efine SQLITE_REA
c9e0: 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 DONLY_CANTLOCK
c9f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 (SQLITE_REA
ca00: 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a DONLY | (2<<8)).
ca10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
ca20: 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b EADONLY_ROLLBACK
ca30: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 (SQLITE_R
ca40: 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 EADONLY | (3<<8)
ca50: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 ).#define SQLITE
ca60: 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 _READONLY_DBMOVE
ca70: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 D (SQLITE
ca80: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c _READONLY | (4<<
ca90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 8)).#define SQLI
caa0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 TE_READONLY_CANT
cab0: 49 4e 49 54 20 20 20 20 20 20 20 28 53 51 4c 49 INIT (SQLI
cac0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 35 TE_READONLY | (5
cad0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 <<8)).#define SQ
cae0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 49 LITE_READONLY_DI
caf0: 52 45 43 54 4f 52 59 20 20 20 20 20 20 28 53 51 RECTORY (SQ
cb00: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 LITE_READONLY |
cb10: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 (6<<8)).#define
cb20: 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c SQLITE_ABORT_ROL
cb30: 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 LBACK (
cb40: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 SQLITE_ABORT | (
cb50: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 2<<8)).#define S
cb60: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
cb70: 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 _CHECK (S
cb80: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
cb90: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 | (1<<8)).#defi
cba0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
cbb0: 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 AINT_COMMITHOOK
cbc0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
cbd0: 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 AINT | (2<<8)).#
cbe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
cbf0: 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e NSTRAINT_FOREIGN
cc00: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f KEY (SQLITE_CO
cc10: 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 NSTRAINT | (3<<8
cc20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
cc30: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e E_CONSTRAINT_FUN
cc40: 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 CTION (SQLIT
cc50: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
cc60: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 4<<8)).#define S
cc70: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
cc80: 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 _NOTNULL (S
cc90: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
cca0: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 | (5<<8)).#defi
ccb0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
ccc0: 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 AINT_PRIMARYKEY
ccd0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
cce0: 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 AINT | (6<<8)).#
ccf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
cd00: 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 NSTRAINT_TRIGGER
cd10: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f (SQLITE_CO
cd20: 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 NSTRAINT | (7<<8
cd30: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 )).#define SQLIT
cd40: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 E_CONSTRAINT_UNI
cd50: 51 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 QUE (SQLIT
cd60: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 E_CONSTRAINT | (
cd70: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 8<<8)).#define S
cd80: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
cd90: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 _VTAB (S
cda0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 QLITE_CONSTRAINT
cdb0: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 | (9<<8)).#defi
cdc0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 ne SQLITE_CONSTR
cdd0: 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 AINT_ROWID
cde0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 (SQLITE_CONSTR
cdf0: 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 AINT |(10<<8)).#
ce00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
ce10: 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c TICE_RECOVER_WAL
ce20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f (SQLITE_NO
ce30: 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 TICE | (1<<8)).#
ce40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f define SQLITE_NO
ce50: 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c TICE_RECOVER_ROL
ce60: 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f LBACK (SQLITE_NO
ce70: 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 TICE | (2<<8)).#
ce80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 define SQLITE_WA
ce90: 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 RNING_AUTOINDEX
cea0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 (SQLITE_WA
ceb0: 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a RNING | (1<<8)).
cec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 #define SQLITE_A
ced0: 55 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 UTH_USER
cee0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 (SQLITE_A
cef0: 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 UTH | (1<<8)).#d
cf00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f efine SQLITE_OK_
cf10: 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 LOAD_PERMANENTLY
cf20: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 (SQLITE_OK
cf30: 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a | (1<<8))../*.**
cf40: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 CAPI3REF: Flags
cf50: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f For File Open O
cf60: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 perations.**.**
cf70: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 These bit values
cf80: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f are intended fo
cf90: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 r use in the.**
cfa0: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 3rd parameter to
cfb0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 the [sqlite3_op
cfc0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 en_v2()] interfa
cfd0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 ce and.** in the
cfe0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 4th parameter t
cff0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 o the [sqlite3_v
d000: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 fs.xOpen] method
d010: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ..*/.#define SQL
d020: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c ITE_OPEN_READONL
d030: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 Y 0x0000
d040: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0001 /* Ok for
d050: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
d060: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
d070: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 ITE_OPEN_READWRI
d080: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 TE 0x0000
d090: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0002 /* Ok for
d0a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
d0b0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
d0c0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 ITE_OPEN_CREATE
d0d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
d0e0: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0004 /* Ok for
d0f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
d100: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
d110: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f ITE_OPEN_DELETEO
d120: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 NCLOSE 0x0000
d130: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0008 /* VFS onl
d140: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
d150: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 ITE_OPEN_EXCLUSI
d160: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 VE 0x0000
d170: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0010 /* VFS onl
d180: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
d190: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f ITE_OPEN_AUTOPRO
d1a0: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 XY 0x0000
d1b0: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0020 /* VFS onl
d1c0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
d1d0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 ITE_OPEN_URI
d1e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
d1f0: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0040 /* Ok for
d200: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
d210: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
d220: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 ITE_OPEN_MEMORY
d230: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
d240: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0080 /* Ok for
d250: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
d260: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
d270: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 ITE_OPEN_MAIN_DB
d280: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
d290: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0100 /* VFS onl
d2a0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
d2b0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 ITE_OPEN_TEMP_DB
d2c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
d2d0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0200 /* VFS onl
d2e0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
d2f0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 ITE_OPEN_TRANSIE
d300: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 NT_DB 0x0000
d310: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0400 /* VFS onl
d320: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
d330: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f ITE_OPEN_MAIN_JO
d340: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
d350: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0800 /* VFS onl
d360: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
d370: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f ITE_OPEN_TEMP_JO
d380: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 URNAL 0x0000
d390: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 1000 /* VFS onl
d3a0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
d3b0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 ITE_OPEN_SUBJOUR
d3c0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 NAL 0x0000
d3d0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 2000 /* VFS onl
d3e0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
d3f0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f ITE_OPEN_MASTER_
d400: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 JOURNAL 0x0000
d410: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 4000 /* VFS onl
d420: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c y */.#define SQL
d430: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 ITE_OPEN_NOMUTEX
d440: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 0x0000
d450: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 8000 /* Ok for
d460: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
d470: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
d480: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 ITE_OPEN_FULLMUT
d490: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 EX 0x0001
d4a0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
d4b0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
d4c0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
d4d0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 ITE_OPEN_SHAREDC
d4e0: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 ACHE 0x0002
d4f0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
d500: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
d510: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
d520: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
d530: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 CACHE 0x0004
d540: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 0000 /* Ok for
d550: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
d560: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c ) */.#define SQL
d570: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 ITE_OPEN_WAL
d580: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 0x0008
d590: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 0000 /* VFS onl
d5a0: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 y */../* Reserve
d5b0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 d:
d5c0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 0x00F
d5d0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 00000 */../*.**
d5e0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 CAPI3REF: Device
d5f0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 Characteristics
d600: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 .**.** The xDevi
d610: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 ceCharacteristic
d620: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 s method of the
d630: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 [sqlite3_io_meth
d640: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 ods].** object r
d650: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 eturns an intege
d660: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 r which is a vec
d670: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 tor of these.**
d680: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 bit values expre
d690: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 ssing I/O charac
d6a0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 teristics of the
d6b0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a mass storage.**
d6c0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c device that hol
d6d0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 ds the file that
d6e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f the [sqlite3_io
d6f0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 _methods].** ref
d700: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 ers to..**.** Th
d710: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 e SQLITE_IOCAP_A
d720: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d TOMIC property m
d730: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 eans that all wr
d740: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 ites of.** any s
d750: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 ize are atomic.
d760: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
d770: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 P_ATOMICnnn valu
d780: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 es.** mean that
d790: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 writes of blocks
d7a0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 that are nnn by
d7b0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a tes in size and.
d7c0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 ** are aligned t
d7d0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 o an address whi
d7e0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ch is an integer
d7f0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 multiple of.**
d800: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 nnn are atomic.
d810: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 The SQLITE_IOCA
d820: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 P_SAFE_APPEND va
d830: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 lue means.** tha
d840: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 t when data is a
d850: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c ppended to a fil
d860: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 e, the data is a
d870: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 ppended.** first
d880: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f then the size o
d890: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 f the file is ex
d8a0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 tended, never th
d8b0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 e other.** way a
d8c0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 round. The SQLI
d8d0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 TE_IOCAP_SEQUENT
d8e0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 IAL property mea
d8f0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 ns that.** infor
d900: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 mation is writte
d910: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 n to disk in the
d920: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 same order as c
d930: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 alls.** to xWrit
d940: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 e(). The SQLITE
d950: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 _IOCAP_POWERSAFE
d960: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 _OVERWRITE prope
d970: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a rty means that.*
d980: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 * after reboot f
d990: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 ollowing a crash
d9a0: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 or power loss,
d9b0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 the only bytes i
d9c0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 n a.** file that
d9d0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 were written at
d9e0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
d9f0: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 level might hav
da00: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 e changed.** and
da10: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 that adjacent b
da20: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 ytes, even bytes
da30: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 within the same
da40: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 sector are.** g
da50: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 uaranteed to be
da60: 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 unchanged. The
da70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 SQLITE_IOCAP_UND
da80: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 ELETABLE_WHEN_OP
da90: 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 EN.** flag indic
daa0: 61 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 ates that a file
dab0: 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 cannot be delet
dac0: 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 ed when open. T
dad0: 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 he.** SQLITE_IOC
dae0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 AP_IMMUTABLE fla
daf0: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 g indicates that
db00: 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a the file is on.
db10: 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 ** read-only med
db20: 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 ia and cannot be
db30: 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 changed even by
db40: 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a processes with.
db50: 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 ** elevated priv
db60: 69 6c 65 67 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 ileges..**.** Th
db70: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 e SQLITE_IOCAP_B
db80: 41 54 43 48 5f 41 54 4f 4d 49 43 20 70 72 6f 70 ATCH_ATOMIC prop
db90: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 erty means that
dba0: 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 0a 2a the underlying.*
dbb0: 2a 20 66 69 6c 65 73 79 73 74 65 6d 20 73 75 70 * filesystem sup
dbc0: 70 6f 72 74 73 20 64 6f 69 6e 67 20 6d 75 6c 74 ports doing mult
dbd0: 69 70 6c 65 20 77 72 69 74 65 20 6f 70 65 72 61 iple write opera
dbe0: 74 69 6f 6e 73 20 61 74 6f 6d 69 63 61 6c 6c 79 tions atomically
dbf0: 20 77 68 65 6e 20 74 68 6f 73 65 0a 2a 2a 20 77 when those.** w
dc00: 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 rite operations
dc10: 61 72 65 20 62 72 61 63 6b 65 74 65 64 20 62 79 are bracketed by
dc20: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 [SQLITE_FCNTL_B
dc30: 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 EGIN_ATOMIC_WRIT
dc40: 45 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 E] and.** [SQLIT
dc50: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 E_FCNTL_COMMIT_A
dc60: 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2f TOMIC_WRITE]..*/
dc70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
dc80: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 IOCAP_ATOMIC
dc90: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 0x0
dca0: 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 0000001.#define
dcb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
dcc0: 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 MIC512
dcd0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 0x00000002.#
dce0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f define SQLITE_IO
dcf0: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 CAP_ATOMIC1K
dd00: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 0x000
dd10: 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 00004.#define SQ
dd20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
dd30: 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 C2K
dd40: 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 0x00000008.#de
dd50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 fine SQLITE_IOCA
dd60: 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 P_ATOMIC4K
dd70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 0x00000
dd80: 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 010.#define SQLI
dd90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 TE_IOCAP_ATOMIC8
dda0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 K
ddb0: 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 0x00000020.#defi
ddc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f ne SQLITE_IOCAP_
ddd0: 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 ATOMIC16K
dde0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 0x0000004
ddf0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 0.#define SQLITE
de00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b _IOCAP_ATOMIC32K
de10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
de20: 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 00000080.#define
de30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 SQLITE_IOCAP_AT
de40: 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 OMIC64K
de50: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 0x00000100.
de60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 #define SQLITE_I
de70: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 OCAP_SAFE_APPEND
de80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 0x00
de90: 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 000200.#define S
dea0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 QLITE_IOCAP_SEQU
deb0: 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 ENTIAL
dec0: 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 0x00000400.#d
ded0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 efine SQLITE_IOC
dee0: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 AP_UNDELETABLE_W
def0: 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 HEN_OPEN 0x0000
df00: 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 0800.#define SQL
df10: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 ITE_IOCAP_POWERS
df20: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 AFE_OVERWRITE
df30: 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 0x00001000.#def
df40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 ine SQLITE_IOCAP
df50: 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 _IMMUTABLE
df60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 0x000020
df70: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 00.#define SQLIT
df80: 45 5f 49 4f 43 41 50 5f 42 41 54 43 48 5f 41 54 E_IOCAP_BATCH_AT
df90: 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 30 OMIC 0
dfa0: 78 30 30 30 30 34 30 30 30 0a 0a 2f 2a 0a 2a 2a x00004000../*.**
dfb0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 CAPI3REF: File
dfc0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a Locking Levels.*
dfd0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 *.** SQLite uses
dfe0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e one of these in
dff0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 teger values as
e000: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 the second.** ar
e010: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 gument to calls
e020: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 it makes to the
e030: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c xLock() and xUnl
e040: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a ock() methods.**
e050: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f of an [sqlite3_
e060: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 io_methods] obje
e070: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ct..*/.#define S
e080: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 QLITE_LOCK_NONE
e090: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 0.#defi
e0a0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 ne SQLITE_LOCK_S
e0b0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 HARED 1.#
e0c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f define SQLITE_LO
e0d0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 CK_RESERVED
e0e0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 2.#define SQLIT
e0f0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 E_LOCK_PENDING
e100: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
e110: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 QLITE_LOCK_EXCLU
e120: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a SIVE 4../*.*
e130: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 * CAPI3REF: Sync
e140: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 hronization Type
e150: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 Flags.**.** Whe
e160: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 n SQLite invokes
e170: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 the xSync() met
e180: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 hod of an.** [sq
e190: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 lite3_io_methods
e1a0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 ] object it uses
e1b0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f a combination o
e1c0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 f.** these integ
e1d0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 er values as the
e1e0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
e1f0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 ..**.** When the
e200: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 SQLITE_SYNC_DAT
e210: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 AONLY flag is us
e220: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 ed, it means tha
e230: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 t the.** sync op
e240: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 eration only nee
e250: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 ds to flush data
e260: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 to mass storage
e270: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f . Inode.** info
e280: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 rmation need not
e290: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 be flushed. If
e2a0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 the lower four b
e2b0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a its of the flag.
e2c0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ** equal SQLITE_
e2d0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 SYNC_NORMAL, tha
e2e0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e t means to use n
e2f0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 ormal fsync() se
e300: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 mantics..** If t
e310: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 he lower four bi
e320: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f ts equal SQLITE_
e330: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 SYNC_FULL, that
e340: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 means.** to use
e350: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 Mac OS X style f
e360: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 ullsync instead
e370: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a of fsync()..**.*
e380: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 * Do not confuse
e390: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 the SQLITE_SYNC
e3a0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 _NORMAL and SQLI
e3b0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 TE_SYNC_FULL fla
e3c0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b gs.** with the [
e3d0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f PRAGMA synchrono
e3e0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b us]=NORMAL and [
e3f0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f PRAGMA synchrono
e400: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 us]=FULL.** sett
e410: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 ings. The [sync
e420: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 hronous pragma]
e430: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 determines when
e440: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 calls to the.**
e450: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 xSync VFS method
e460: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 occur and appli
e470: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 es uniformly acr
e480: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d oss all platform
e490: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 s..** The SQLITE
e4a0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 _SYNC_NORMAL and
e4b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c SQLITE_SYNC_FUL
e4c0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e L flags determin
e4d0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 e how.** energet
e4e0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f ic or rigorous o
e4f0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 r forceful the s
e500: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 ync operations a
e510: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d re and.** only m
e520: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 ake a difference
e530: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 on Mac OSX for
e540: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 the default SQLi
e550: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 te code..** (Thi
e560: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 rd-party VFS imp
e570: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 lementations mig
e580: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 ht also make the
e590: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 distinction.**
e5a0: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 between SQLITE_S
e5b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 YNC_NORMAL and S
e5c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c QLITE_SYNC_FULL,
e5d0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a but among the.*
e5e0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 * operating syst
e5f0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 ems natively sup
e600: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 ported by SQLite
e610: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a , only Mac OSX.*
e620: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 * cares about th
e630: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a e difference.).*
e640: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
e650: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 _SYNC_NORMAL
e660: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 0x00002.#def
e670: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f ine SQLITE_SYNC_
e680: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 FULL 0x
e690: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 00003.#define SQ
e6a0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e LITE_SYNC_DATAON
e6b0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a LY 0x00010.
e6c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
e6d0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 OS Interface Op
e6e0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a en File Handle.*
e6f0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 *.** An [sqlite3
e700: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 _file] object re
e710: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e presents an open
e720: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a file in the .**
e730: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 [sqlite3_vfs |
e740: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 OS interface lay
e750: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c er]. Individual
e760: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a OS interface.**
e770: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 implementations
e780: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f will.** want to
e790: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f subclass this o
e7a0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 bject by appendi
e7b0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 ng additional fi
e7c0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 elds.** for thei
e7d0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 r own use. The
e7e0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 pMethods entry i
e7f0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
e800: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f n.** [sqlite3_io
e810: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 _methods] object
e820: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 that defines me
e830: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 thods for perfor
e840: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 ming.** I/O oper
e850: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 ations on the op
e860: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 en file..*/.type
e870: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 def struct sqlit
e880: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f e3_file sqlite3_
e890: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c file;.struct sql
e8a0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f ite3_file {. co
e8b0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 nst struct sqlit
e8c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 e3_io_methods *p
e8d0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 Methods; /* Met
e8e0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e hods for an open
e8f0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a file */.};../*.
e900: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 ** CAPI3REF: OS
e910: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 Interface File V
e920: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f irtual Methods O
e930: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 bject.**.** Ever
e940: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 y file opened by
e950: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 the [sqlite3_vf
e960: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 s.xOpen] method
e970: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 populates an.**
e980: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f [sqlite3_file] o
e990: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 bject (or, more
e9a0: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 commonly, a subc
e9b0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b lass of the.** [
e9c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
e9d0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 ject) with a poi
e9e0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
e9f0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 nce of this obje
ea00: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 ct..** This obje
ea10: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d ct defines the m
ea20: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 ethods used to p
ea30: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f erform various o
ea40: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 perations.** aga
ea50: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 inst the open fi
ea60: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 le represented b
ea70: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 y the [sqlite3_f
ea80: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a ile] object..**.
ea90: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 ** If the [sqlit
eaa0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 e3_vfs.xOpen] me
eab0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 thod sets the sq
eac0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 lite3_file.pMeth
ead0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 ods element .**
eae0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f to a non-NULL po
eaf0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 inter, then the
eb00: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f sqlite3_io_metho
eb10: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 ds.xClose method
eb20: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b .** may be invok
eb30: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b ed even if the [
eb40: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 sqlite3_vfs.xOpe
eb50: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 n] reported that
eb60: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 it failed. The
eb70: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 .** only way to
eb80: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 prevent a call t
eb90: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 o xClose followi
eba0: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c ng a failed [sql
ebb0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a ite3_vfs.xOpen].
ebc0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 ** is for the [s
ebd0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e qlite3_vfs.xOpen
ebe0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c ] to set the sql
ebf0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f ite3_file.pMetho
ec00: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f ds element.** to
ec10: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 NULL..**.** The
ec20: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 flags argument
ec30: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 to xSync may be
ec40: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 one of [SQLITE_S
ec50: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a YNC_NORMAL] or.*
ec60: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 * [SQLITE_SYNC_F
ec70: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 ULL]. The first
ec80: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e choice is the n
ec90: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a ormal fsync()..*
eca0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f * The second cho
ecb0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 ice is a Mac OS
ecc0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 X style fullsync
ecd0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 . The [SQLITE_S
ece0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a YNC_DATAONLY].**
ecf0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 flag may be ORe
ed00: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 d in to indicate
ed10: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 that only the d
ed20: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a ata of the file.
ed30: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 ** and not its i
ed40: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 node needs to be
ed50: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 synced..**.** T
ed60: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 he integer value
ed70: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 s to xLock() and
ed80: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f xUnlock() are o
ed90: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a ne of.** <ul>.**
eda0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f <li> [SQLITE_LO
edb0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 CK_NONE],.** <li
edc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 > [SQLITE_LOCK_S
edd0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 HARED],.** <li>
ede0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
edf0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 ERVED],.** <li>
ee00: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e [SQLITE_LOCK_PEN
ee10: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 DING], or.** <li
ee20: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 > [SQLITE_LOCK_E
ee30: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f XCLUSIVE]..** </
ee40: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 ul>.** xLock() i
ee50: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 ncreases the loc
ee60: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 k. xUnlock() dec
ee70: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e reases the lock.
ee80: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 .** The xCheckRe
ee90: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 servedLock() met
eea0: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 hod checks wheth
eeb0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 er any database
eec0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 connection,.** e
eed0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 ither in this pr
eee0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 ocess or in some
eef0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 other process,
ef00: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 is holding a RES
ef10: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e ERVED,.** PENDIN
ef20: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 G, or EXCLUSIVE
ef30: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 lock on the file
ef40: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 . It returns tr
ef50: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 ue.** if such a
ef60: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 lock exists and
ef70: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e false otherwise.
ef80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 .**.** The xFile
ef90: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 Control() method
efa0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e is a generic in
efb0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c terface that all
efc0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 ows custom.** VF
efd0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
efe0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f s to directly co
eff0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 ntrol an open fi
f000: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 le using the.**
f010: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
f020: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 ntrol()] interfa
f030: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 ce. The second
f040: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 "op" argument is
f050: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f an.** integer o
f060: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 pcode. The thir
f070: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 d argument is a
f080: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 generic pointer
f090: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 intended to.** p
f0a0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 oint to a struct
f0b0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e ure that may con
f0c0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f tain arguments o
f0d0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 r space in which
f0e0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 to.** write ret
f0f0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 urn values. Pot
f100: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 ential uses for
f110: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d xFileControl() m
f120: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 ight be.** funct
f130: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 ions to enable b
f140: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 locking locks wi
f150: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 th timeouts, to
f160: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f change the.** lo
f170: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 cking strategy (
f180: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 for example to u
f190: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b se dot-file lock
f1a0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a s), to inquire.*
f1b0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 * about the stat
f1c0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 us of a lock, or
f1d0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 to break stale
f1e0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 locks. The SQLi
f1f0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 te.** core reser
f200: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 ves all opcodes
f210: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f less than 100 fo
f220: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a r its own use..*
f230: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f * A [file contro
f240: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74 l opcodes | list
f250: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 of opcodes] les
f260: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 s than 100 is av
f270: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c ailable..** Appl
f280: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 ications that de
f290: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 fine a custom xF
f2a0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f ileControl metho
f2b0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 d should use opc
f2c0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 odes.** greater
f2d0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 than 100 to avoi
f2e0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 d conflicts. VF
f2f0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e S implementation
f300: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 s should.** retu
f310: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f rn [SQLITE_NOTFO
f320: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f UND] for file co
f330: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 ntrol opcodes th
f340: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a at they do not.*
f350: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a * recognize..**.
f360: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 ** The xSectorSi
f370: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 ze() method retu
f380: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 rns the sector s
f390: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 ize of the.** de
f3a0: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c vice that underl
f3b0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 ies the file. T
f3c0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 he sector size i
f3d0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d s the.** minimum
f3e0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 write that can
f3f0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 be performed wit
f400: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a hout disturbing.
f410: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 ** other bytes i
f420: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 n the file. The
f430: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 xDeviceCharacte
f440: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 ristics().** met
f450: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 hod returns a bi
f460: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 t vector describ
f470: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 ing behaviors of
f480: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 the.** underlyi
f490: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a ng device:.**.**
f4a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 <ul>.** <li> [S
f4b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
f4c0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c IC].** <li> [SQL
f4d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
f4e0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 512].** <li> [SQ
f4f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
f500: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C1K].** <li> [SQ
f510: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
f520: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C2K].** <li> [SQ
f530: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
f540: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C4K].** <li> [SQ
f550: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
f560: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 C8K].** <li> [SQ
f570: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 LITE_IOCAP_ATOMI
f580: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 C16K].** <li> [S
f590: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d QLITE_IOCAP_ATOM
f5a0: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b IC32K].** <li> [
f5b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
f5c0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 MIC64K].** <li>
f5d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 [SQLITE_IOCAP_SA
f5e0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c FE_APPEND].** <l
f5f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 i> [SQLITE_IOCAP
f600: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 _SEQUENTIAL].**
f610: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 <li> [SQLITE_IOC
f620: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 AP_UNDELETABLE_W
f630: 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69 HEN_OPEN].** <li
f640: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f > [SQLITE_IOCAP_
f650: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 POWERSAFE_OVERWR
f660: 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 ITE].** <li> [SQ
f670: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 LITE_IOCAP_IMMUT
f680: 41 42 4c 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 ABLE].** <li> [S
f690: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 42 41 54 43 QLITE_IOCAP_BATC
f6a0: 48 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 2f 75 H_ATOMIC].** </u
f6b0: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c l>.**.** The SQL
f6c0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 ITE_IOCAP_ATOMIC
f6d0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 property means
f6e0: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 that all writes
f6f0: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 of.** any size a
f700: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 re atomic. The
f710: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f SQLITE_IOCAP_ATO
f720: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a MICnnn values.**
f730: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 mean that write
f740: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 s of blocks that
f750: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 are nnn bytes i
f760: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 n size and.** ar
f770: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 e aligned to an
f780: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 address which is
f790: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 an integer mult
f7a0: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 iple of.** nnn a
f7b0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 re atomic. The
f7c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 SQLITE_IOCAP_SAF
f7d0: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d E_APPEND value m
f7e0: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 eans.** that whe
f7f0: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 n data is append
f800: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 ed to a file, th
f810: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 e data is append
f820: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e ed.** first then
f830: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 the size of the
f840: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 file is extende
f850: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 d, never the oth
f860: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 er.** way around
f870: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f . The SQLITE_IO
f880: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 CAP_SEQUENTIAL p
f890: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 roperty means th
f8a0: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f at.** informatio
f8b0: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 n is written to
f8c0: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 disk in the same
f8d0: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a order as calls.
f8e0: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a ** to xWrite()..
f8f0: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 **.** If xRead()
f900: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f returns SQLITE_
f910: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 IOERR_SHORT_READ
f920: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 it must also fi
f930: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 ll.** in the unr
f940: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 ead portions of
f950: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20 the buffer with
f960: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 zeros. A VFS th
f970: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a at.** fails to z
f980: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 ero-fill short r
f990: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 eads might seem
f9a0: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 to work. Howeve
f9b0: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f r,.** failure to
f9c0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 zero-fill short
f9d0: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e reads will even
f9e0: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a tually lead to.*
f9f0: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 * database corru
fa00: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 ption..*/.typede
fa10: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 f struct sqlite3
fa20: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 _io_methods sqli
fa30: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a te3_io_methods;.
fa40: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 struct sqlite3_i
fa50: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e o_methods {. in
fa60: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e t iVersion;. in
fa70: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 t (*xClose)(sqli
fa80: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e te3_file*);. in
fa90: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 t (*xRead)(sqlit
faa0: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c e3_file*, void*,
fab0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 int iAmt, sqlit
fac0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b e3_int64 iOfst);
fad0: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 . int (*xWrite)
fae0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
faf0: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 const void*, int
fb00: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 iAmt, sqlite3_i
fb10: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 nt64 iOfst);. i
fb20: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 nt (*xTruncate)(
fb30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 sqlite3_file*, s
fb40: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a qlite3_int64 siz
fb50: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e e);. int (*xSyn
fb60: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a c)(sqlite3_file*
fb70: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 , int flags);.
fb80: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 int (*xFileSize)
fb90: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
fba0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 sqlite3_int64 *p
fbb0: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 Size);. int (*x
fbc0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 Lock)(sqlite3_fi
fbd0: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 le*, int);. int
fbe0: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 (*xUnlock)(sqli
fbf0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b te3_file*, int);
fc00: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 . int (*xCheckR
fc10: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c eservedLock)(sql
fc20: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 ite3_file*, int
fc30: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 *pResOut);. int
fc40: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 (*xFileControl)
fc50: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 (sqlite3_file*,
fc60: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 int op, void *pA
fc70: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 rg);. int (*xSe
fc80: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 ctorSize)(sqlite
fc90: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 3_file*);. int
fca0: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74 (*xDeviceCharact
fcb0: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 eristics)(sqlite
fcc0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 3_file*);. /* M
fcd0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 ethods above are
fce0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 valid for versi
fcf0: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a on 1 */. int (*
fd00: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 xShmMap)(sqlite3
fd10: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c _file*, int iPg,
fd20: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 int pgsz, int,
fd30: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 void volatile**)
fd40: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f ;. int (*xShmLo
fd50: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 ck)(sqlite3_file
fd60: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 *, int offset, i
fd70: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 nt n, int flags)
fd80: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 ;. void (*xShmB
fd90: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f arrier)(sqlite3_
fda0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a file*);. int (*
fdb0: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 xShmUnmap)(sqlit
fdc0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 e3_file*, int de
fdd0: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 leteFlag);. /*
fde0: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 Methods above ar
fdf0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 e valid for vers
fe00: 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 ion 2 */. int (
fe10: 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 *xFetch)(sqlite3
fe20: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f _file*, sqlite3_
fe30: 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 int64 iOfst, int
fe40: 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 iAmt, void **pp
fe50: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 );. int (*xUnfe
fe60: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c tch)(sqlite3_fil
fe70: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 e*, sqlite3_int6
fe80: 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 4 iOfst, void *p
fe90: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 );. /* Methods
fea0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 above are valid
feb0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f for version 3 */
fec0: 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c . /* Additional
fed0: 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 methods may be
fee0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
fef0: 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a releases */.};..
ff00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
ff10: 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f Standard File Co
ff20: 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a ntrol Opcodes.**
ff30: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 KEYWORDS: {file
ff40: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 control opcodes
ff50: 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 } {file control
ff60: 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 opcode}.**.** Th
ff70: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 ese integer cons
ff80: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 tants are opcode
ff90: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 s for the xFileC
ffa0: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a ontrol method.**
ffb0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 of the [sqlite3
ffc0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a _io_methods] obj
ffd0: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 ect and for the
ffe0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f [sqlite3_file_co
fff0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 ntrol()].** inte
10000 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c rface..**.** <ul
10010 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 >.** <li>[[SQLIT
10020 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 E_FCNTL_LOCKSTAT
10030 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 E]].** The [SQLI
10040 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 TE_FCNTL_LOCKSTA
10050 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 TE] opcode is us
10060 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 ed for debugging
10070 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 . This.** opcod
10080 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 e causes the xFi
10090 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 leControl method
100a0 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 to write the cu
100b0 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a rrent state of.*
100c0 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 * the lock (one
100d0 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f of [SQLITE_LOCK_
100e0 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c NONE], [SQLITE_L
100f0 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 OCK_SHARED],.**
10100 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 [SQLITE_LOCK_RES
10110 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f ERVED], [SQLITE_
10120 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f LOCK_PENDING], o
10130 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 r [SQLITE_LOCK_E
10140 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e XCLUSIVE]).** in
10150 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 to an integer th
10160 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75 at the pArg argu
10170 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 ment points to.
10180 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a This capability.
10190 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e ** is used durin
101a0 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 g testing and is
101b0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 only available
101c0 77 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f when the SQLITE_
101d0 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d TEST.** compile-
101e0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 time option is u
101f0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b sed..**.** <li>[
10200 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 [SQLITE_FCNTL_SI
10210 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 ZE_HINT]].** The
10220 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 [SQLITE_FCNTL_S
10230 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 IZE_HINT] opcode
10240 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 is used by SQLi
10250 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 te to give the V
10260 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 FS.** layer a hi
10270 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 nt of how large
10280 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
10290 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 e will grow to b
102a0 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 e during the.**
102b0 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 current transact
102c0 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 ion. This hint
102d0 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 is not guarantee
102e0 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 d to be accurate
102f0 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 but it.** is of
10300 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 ten close. The
10310 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d underlying VFS m
10320 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 ight choose to p
10330 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 reallocate datab
10340 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 ase.** file spac
10350 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 e based on this
10360 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f hint in order to
10370 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 help writes to
10380 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 the database.**
10390 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e file run faster.
103a0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
103b0 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
103c0 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 SIZE]].** The [S
103d0 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e QLITE_FCNTL_CHUN
103e0 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 K_SIZE] opcode i
103f0 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 s used to reques
10400 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a t that the VFS.*
10410 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 * extends and tr
10420 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 uncates the data
10430 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 base file in chu
10440 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 nks of a size sp
10450 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 ecified.** by th
10460 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 e user. The four
10470 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b th argument to [
10480 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e sqlite3_file_con
10490 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a trol()] should .
104a0 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 ** point to an i
104b0 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 nteger (type int
104c0 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 ) containing the
104d0 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 new chunk-size
104e0 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 to use.** for th
104f0 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 e nominated data
10500 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 base. Allocating
10510 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 database file s
10520 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a pace in large.**
10530 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 chunks (say 1MB
10540 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 at a time), may
10550 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 reduce file-sys
10560 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f tem fragmentatio
10570 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 n and.** improve
10580 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 performance on
10590 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a some systems..**
105a0 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
105b0 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e _FCNTL_FILE_POIN
105c0 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 TER]].** The [SQ
105d0 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f LITE_FCNTL_FILE_
105e0 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 POINTER] opcode
105f0 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 is used to obtai
10600 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 n a pointer.** t
10610 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 o the [sqlite3_f
10620 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f ile] object asso
10630 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 ciated with a pa
10640 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 rticular databas
10650 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e e.** connection.
10660 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 See also [SQLI
10670 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c TE_FCNTL_JOURNAL
10680 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a _POINTER]..**.**
10690 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
106a0 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e NTL_JOURNAL_POIN
106b0 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 TER]].** The [SQ
106c0 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e LITE_FCNTL_JOURN
106d0 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f AL_POINTER] opco
106e0 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 de is used to ob
106f0 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a tain a pointer.*
10700 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 * to the [sqlite
10710 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 3_file] object a
10720 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 ssociated with t
10730 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 he journal file
10740 28 65 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b (either.** the [
10750 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c rollback journal
10760 5d 20 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d ] or the [write-
10770 61 68 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 ahead log]) for
10780 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 a particular dat
10790 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 abase.** connect
107a0 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b ion. See also [
107b0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c SQLITE_FCNTL_FIL
107c0 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a E_POINTER]..**.*
107d0 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
107e0 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 CNTL_SYNC_OMITTE
107f0 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 D]].** No longer
10800 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c in use..**.** <
10810 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 li>[[SQLITE_FCNT
10820 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 L_SYNC]].** The
10830 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 [SQLITE_FCNTL_SY
10840 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 NC] opcode is ge
10850 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c nerated internal
10860 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 ly by SQLite and
10870 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 .** sent to the
10880 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 VFS immediately
10890 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 before the xSync
108a0 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b method is invok
108b0 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 ed on a.** datab
108c0 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 ase file descrip
108d0 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 tor. Or, if the
108e0 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 xSync method is
108f0 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 not invoked .**
10900 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72 because the user
10910 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 has configured
10920 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 SQLite with .**
10930 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e [PRAGMA synchron
10940 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e ous | PRAGMA syn
10950 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 chronous=OFF] it
10960 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 is invoked in p
10970 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 lace .** of the
10980 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e xSync method. In
10990 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 most cases, the
109a0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e pointer argumen
109b0 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a t passed with.**
109c0 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 this file-contr
109d0 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 ol is NULL. Howe
109e0 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 ver, if the data
109f0 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 base file is bei
10a00 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 ng synced.** as
10a10 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d part of a multi-
10a20 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c database commit,
10a30 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f the argument po
10a40 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 ints to a nul-te
10a50 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 rminated.** stri
10a60 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 ng containing th
10a70 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d e transactions m
10a80 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 aster-journal fi
10a90 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 le name. VFSes t
10aa0 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e hat .** do not n
10ab0 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 eed this signal
10ac0 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 should silently
10ad0 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f ignore this opco
10ae0 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 de. Applications
10af0 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 .** should not
10b00 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 call [sqlite3_fi
10b10 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 le_control()] wi
10b20 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 th this opcode a
10b30 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a s doing so may .
10b40 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f ** disrupt the o
10b50 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 peration of the
10b60 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 specialized VFSe
10b70 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 s that do requir
10b80 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c e it. .**.** <l
10b90 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c i>[[SQLITE_FCNTL
10ba0 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f _COMMIT_PHASETWO
10bb0 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
10bc0 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 E_FCNTL_COMMIT_P
10bd0 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 HASETWO] opcode
10be0 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 is generated int
10bf0 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 ernally by SQLit
10c00 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f e.** and sent to
10c10 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61 the VFS after a
10c20 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 transaction has
10c30 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 been committed
10c40 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 immediately.** b
10c50 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 ut before the da
10c60 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b tabase is unlock
10c70 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 ed. VFSes that d
10c80 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 o not need this
10c90 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 signal.** should
10ca0 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 silently ignore
10cb0 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 this opcode. Ap
10cc0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c plications shoul
10cd0 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 d not call.** [s
10ce0 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 qlite3_file_cont
10cf0 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 rol()] with this
10d00 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 opcode as doing
10d10 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 so may disrupt
10d20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f the .** operatio
10d30 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c n of the special
10d40 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 ized VFSes that
10d50 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 do require it.
10d60 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c .**.** <li>[[SQL
10d70 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
10d80 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 AV_RETRY]].** ^T
10d90 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
10da0 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d _WIN32_AV_RETRY]
10db0 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
10dc0 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 to configure aut
10dd0 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 omatic.** retry
10de0 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 counts and inter
10df0 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e vals for certain
10e00 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 disk I/O operat
10e10 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 ions for the.**
10e20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e windows [VFS] in
10e30 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 order to provid
10e40 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 e robustness in
10e50 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a the presence of.
10e60 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 ** anti-virus pr
10e70 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 ograms. By defa
10e80 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 ult, the windows
10e90 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 VFS will retry
10ea0 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 file read,.** fi
10eb0 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 le write, and fi
10ec0 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 le delete operat
10ed0 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 ions up to 10 ti
10ee0 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 mes, with a dela
10ef0 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 y.** of 25 milli
10f00 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 seconds before t
10f10 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61 he first retry a
10f20 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 nd with the dela
10f30 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 y increasing.**
10f40 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c by an additional
10f50 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 25 milliseconds
10f60 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65 with each subse
10f70 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 quent retry. Th
10f80 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c is.** opcode all
10f90 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 ows these two va
10fa0 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73 lues (10 retries
10fb0 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 and 25 millisec
10fc0 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a onds of delay).*
10fd0 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 * to be adjusted
10fe0 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 . The values ar
10ff0 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c e changed for al
11000 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 l database conne
11010 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e ctions.** within
11020 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 the same proces
11030 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 s. The argument
11040 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
11050 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f an array of two
11060 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 .** integers whe
11070 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 re the first int
11080 65 67 65 72 20 69 73 20 74 68 65 20 6e 65 77 20 eger is the new
11090 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 retry count and
110a0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e the second.** in
110b0 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c teger is the del
110c0 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 ay. If either i
110d0 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 nteger is negati
110e0 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 ve, then the set
110f0 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 ting.** is not c
11100 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 hanged but inste
11110 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c ad the prior val
11120 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 ue of that setti
11130 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a ng is written.**
11140 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 into the array
11150 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 entry, allowing
11160 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 the current retr
11170 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 y settings to be
11180 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 .** interrogated
11190 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 . The zDbName p
111a0 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f arameter is igno
111b0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b red..**.** <li>[
111c0 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 [SQLITE_FCNTL_PE
111d0 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e RSIST_WAL]].** ^
111e0 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
111f0 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f L_PERSIST_WAL] o
11200 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f pcode is used to
11210 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 set or query th
11220 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 e.** persistent
11230 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 [WAL | Write Ahe
11240 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e ad Log] setting.
11250 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 By default, th
11260 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 e auxiliary.** w
11270 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 rite ahead log a
11280 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 nd shared memory
11290 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 files used for
112a0 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 transaction cont
112b0 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d rol.** are autom
112c0 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 atically deleted
112d0 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 when the latest
112e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 connection to t
112f0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 he database.** c
11300 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 loses. Setting
11310 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d persistent WAL m
11320 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 ode causes those
11330 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 files to persis
11340 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 t after.** close
11350 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 . Persisting th
11360 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 e files is usefu
11370 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f l when other pro
11380 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e cesses that do n
11390 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 ot.** have write
113a0 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 permission on t
113b0 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e he directory con
113c0 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 taining the data
113d0 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a base file want.*
113e0 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 * to read the da
113f0 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 tabase file, as
11400 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 the WAL and shar
11410 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 ed memory files
11420 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e must exist.** in
11430 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 order for the d
11440 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 atabase to be re
11450 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 adable. The fou
11460 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
11470 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c .** [sqlite3_fil
11480 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 e_control()] for
11490 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f this opcode sho
114a0 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 uld be a pointer
114b0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a to an integer..
114c0 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 ** That integer
114d0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 is 0 to disable
114e0 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d persistent WAL m
114f0 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 ode or 1 to enab
11500 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a le persistent.**
11510 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 WAL mode. If t
11520 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 he integer is -1
11530 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 , then it is ove
11540 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 rwritten with th
11550 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c e current.** WAL
11560 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 persistence set
11570 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e ting..**.** <li>
11580 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 [[SQLITE_FCNTL_P
11590 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 OWERSAFE_OVERWRI
115a0 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 TE]].** ^The [SQ
115b0 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 LITE_FCNTL_POWER
115c0 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 SAFE_OVERWRITE]
115d0 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 opcode is used t
115e0 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 o set or query t
115f0 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 he.** persistent
11600 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 "powersafe-over
11610 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 write" or "PSOW"
11620 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 setting. The P
11630 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 SOW setting.** d
11640 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 etermines the [S
11650 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 QLITE_IOCAP_POWE
11660 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d RSAFE_OVERWRITE]
11670 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 bit of the.** x
11680 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 DeviceCharacteri
11690 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 stics methods. T
116a0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 he fourth parame
116b0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 ter to.** [sqlit
116c0 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 e3_file_control(
116d0 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f )] for this opco
116e0 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 de should be a p
116f0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 ointer to an int
11700 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e eger..** That in
11710 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 teger is 0 to di
11720 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 sable zero-damag
11730 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 e mode or 1 to e
11740 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 nable zero-damag
11750 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 e.** mode. If t
11760 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 he integer is -1
11770 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 , then it is ove
11780 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 rwritten with th
11790 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 e current.** zer
117a0 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 o-damage mode se
117b0 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 tting..**.** <li
117c0 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f >[[SQLITE_FCNTL_
117d0 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e OVERWRITE]].** ^
117e0 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
117f0 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 L_OVERWRITE] opc
11800 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 ode is invoked b
11810 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f y SQLite after o
11820 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 pening.** a writ
11830 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f e transaction to
11840 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 indicate that,
11850 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c unless it is rol
11860 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d led back for som
11870 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 e.** reason, the
11880 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 entire database
11890 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 file will be ov
118a0 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 erwritten by the
118b0 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 current .** tra
118c0 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 nsaction. This i
118d0 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d s used by VACUUM
118e0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a operations..**.
118f0 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
11900 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a FCNTL_VFSNAME]].
11910 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
11920 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f FCNTL_VFSNAME] o
11930 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 pcode can be use
11940 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 d to obtain the
11950 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 names of.** all
11960 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 [VFSes] in the V
11970 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e FS stack. The n
11980 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 ames are of all
11990 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 VFS shims and th
119a0 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f e.** final botto
119b0 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 m-level VFS are
119c0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d written into mem
119d0 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f ory obtained fro
119e0 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d m .** [sqlite3_m
119f0 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 alloc()] and the
11a00 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 result is store
11a10 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 d in the char* v
11a20 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 ariable.** that
11a30 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
11a40 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 eter of [sqlite3
11a50 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d _file_control()]
11a60 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 points to..** T
11a70 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 he caller is res
11a80 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 ponsible for fre
11a90 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 eing the memory
11aa0 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 when done. As w
11ab0 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d ith.** all file-
11ac0 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c control actions,
11ad0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 there is no gua
11ae0 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 rantee that this
11af0 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a will actually.*
11b00 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 * do anything.
11b10 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 Callers should i
11b20 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 nitialize the ch
11b30 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 ar* variable to
11b40 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 a NULL.** pointe
11b50 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 r in case this f
11b60 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e ile-control is n
11b70 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 ot implemented.
11b80 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 This file-contr
11b90 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 ol.** is intende
11ba0 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 d for diagnostic
11bb0 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a use only..**.**
11bc0 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
11bd0 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d NTL_VFS_POINTER]
11be0 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 ].** ^The [SQLIT
11bf0 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e E_FCNTL_VFS_POIN
11c00 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 TER] opcode find
11c10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 s a pointer to t
11c20 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 he top-level.**
11c30 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74 6c [VFSes] currentl
11c40 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 y in use. ^(The
11c50 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a argument X in.*
11c60 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 * sqlite3_file_c
11c70 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 ontrol(db,SQLITE
11c80 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 _FCNTL_VFS_POINT
11c90 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a ER,X) must be.**
11ca0 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69 74 of type "[sqlit
11cb0 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 e3_vfs] **". Th
11cc0 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 is opcodes will
11cd0 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 set *X.** to a p
11ce0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f ointer to the to
11cf0 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a p-level VFS.)^.*
11d00 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61 72 * ^When there ar
11d10 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20 73 e multiple VFS s
11d20 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61 63 hims in the stac
11d30 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20 66 k, this opcode f
11d40 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 inds the.** uppe
11d50 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 r-most shim only
11d60 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
11d70 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
11d80 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 A]].** ^Whenever
11d90 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 a [PRAGMA] stat
11da0 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c ement is parsed,
11db0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 an [SQLITE_FCNT
11dc0 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 L_PRAGMA] .** fi
11dd0 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 le control is se
11de0 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b nt to the open [
11df0 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 sqlite3_file] ob
11e00 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 ject correspondi
11e10 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 ng.** to the dat
11e20 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 abase file to wh
11e30 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 ich the pragma s
11e40 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e tatement refers.
11e50 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a ^The argument.*
11e60 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 * to the [SQLITE
11e70 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 _FCNTL_PRAGMA] f
11e80 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 ile control is a
11e90 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f n array of.** po
11ea0 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 inters to string
11eb0 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 s (char**) in wh
11ec0 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 ich the second e
11ed0 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 lement of the ar
11ee0 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 ray.** is the na
11ef0 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 me of the pragma
11f00 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 and the third e
11f10 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 lement is the ar
11f20 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a gument to the.**
11f30 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 pragma or NULL
11f40 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 if the pragma ha
11f50 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 s no argument.
11f60 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 ^The handler for
11f70 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 an.** [SQLITE_F
11f80 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c CNTL_PRAGMA] fil
11f90 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 e control can op
11fa0 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 tionally make th
11fb0 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a e first element.
11fc0 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a ** of the char**
11fd0 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 argument point
11fe0 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 to a string obta
11ff0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 ined from [sqlit
12000 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a e3_mprintf()].**
12010 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 or the equivale
12020 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 nt and that stri
12030 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 ng will become t
12040 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 he result of the
12050 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 pragma or.** th
12060 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 e error message
12070 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 if the pragma fa
12080 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 ils. ^If the.**
12090 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 [SQLITE_FCNTL_PR
120a0 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 AGMA] file contr
120b0 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 ol returns [SQLI
120c0 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 TE_NOTFOUND], th
120d0 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 en normal .** [P
120e0 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e RAGMA] processin
120f0 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 g continues. ^I
12100 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 f the [SQLITE_FC
12110 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 NTL_PRAGMA].** f
12120 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 ile control retu
12130 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c rns [SQLITE_OK],
12140 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 then the parser
12150 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 assumes that th
12160 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e e.** VFS has han
12170 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 dled the PRAGMA
12180 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 itself and the p
12190 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 arser generates
121a0 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 a no-op.** prepa
121b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 66 red statement if
121c0 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 result string i
121d0 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 s NULL, or that
121e0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a returns a copy.*
121f0 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 * of the result
12200 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73 74 string if the st
12210 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c ring is non-NULL
12220 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 ..** ^If the [SQ
12230 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d LITE_FCNTL_PRAGM
12240 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 A] file control
12250 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 returns.** any r
12260 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 esult code other
12270 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b than [SQLITE_OK
12280 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 ] or [SQLITE_NOT
12290 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 FOUND], that mea
122a0 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 ns.** that the V
122b0 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 FS encountered a
122c0 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 n error while ha
122d0 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 ndling the [PRAG
122e0 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 MA] and the.** c
122f0 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 ompilation of th
12300 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 e PRAGMA fails w
12310 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e ith an error. ^
12320 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 The [SQLITE_FCNT
12330 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c L_PRAGMA].** fil
12340 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 e control occurs
12350 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e at the beginnin
12360 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 g of pragma stat
12370 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 ement analysis a
12380 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 nd so.** it is a
12390 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 ble to override
123a0 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 built-in [PRAGMA
123b0 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a ] statements..**
123c0 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
123d0 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c _FCNTL_BUSYHANDL
123e0 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 ER]].** ^The [SQ
123f0 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 LITE_FCNTL_BUSYH
12400 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d ANDLER].** file-
12410 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 control may be i
12420 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 nvoked by SQLite
12430 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 on the database
12440 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 file handle.**
12450 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 shortly after it
12460 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 is opened in or
12470 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 der to provide a
12480 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 custom VFS with
12490 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 access.** to th
124a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 e connections bu
124b0 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 sy-handler callb
124c0 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e ack. The argumen
124d0 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f t is of type (vo
124e0 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 id **).** - an a
124f0 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 rray of two (voi
12500 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 d *) values. The
12510 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 first (void *)
12520 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a actually points.
12530 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e ** to a function
12540 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a of type (int (*
12550 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f )(void *)). In o
12560 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 rder to invoke t
12570 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a he connections.*
12580 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 * busy-handler,
12590 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 this function sh
125a0 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 ould be invoked
125b0 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 with the second
125c0 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 (void *) in.** t
125d0 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20 he array as the
125e0 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 only argument. I
125f0 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e f it returns non
12600 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 -zero, then the
12610 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f operation.** sho
12620 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 uld be retried.
12630 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 If it returns ze
12640 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 ro, the custom V
12650 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f FS should abando
12660 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 n the.** current
12670 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a operation..**.*
12680 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 * <li>[[SQLITE_F
12690 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d CNTL_TEMPFILENAM
126a0 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 E]].** ^Applicat
126b0 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 ion can invoke t
126c0 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
126d0 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 _TEMPFILENAME] f
126e0 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 ile-control.** t
126f0 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 o have SQLite ge
12700 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 nerate a.** temp
12710 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 orary filename u
12720 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c sing the same al
12730 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 gorithm that is
12740 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 followed to gene
12750 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 rate.** temporar
12760 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 y filenames for
12770 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 TEMP tables and
12780 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 other internal u
12790 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 ses. The.** arg
127a0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 ument should be
127b0 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 a char** which w
127c0 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 ill be filled wi
127d0 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a th the filename.
127e0 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 ** written into
127f0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 memory obtained
12800 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 from [sqlite3_ma
12810 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 lloc()]. The ca
12820 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 ller should.** i
12830 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 nvoke [sqlite3_f
12840 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 ree()] on the re
12850 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 sult to avoid a
12860 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a memory leak..**.
12870 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
12880 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d FCNTL_MMAP_SIZE]
12890 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 ].** The [SQLITE
128a0 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 _FCNTL_MMAP_SIZE
128b0 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 ] file control i
128c0 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 s used to query
128d0 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 or set the.** ma
128e0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 ximum number of
128f0 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 bytes that will
12900 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f be used for memo
12910 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a ry-mapped I/O..*
12920 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 * The argument i
12930 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
12940 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 value of type s
12950 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 qlite3_int64 tha
12960 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 t.** is an advis
12970 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 ory maximum numb
12980 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 er of bytes in t
12990 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 he file to memor
129a0 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 y map. The.** p
129b0 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 ointer is overwr
129c0 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f itten with the o
129d0 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c ld value. The l
129e0 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e imit is not chan
129f0 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 ged if.** the va
12a00 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 lue originally p
12a10 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 ointed to is neg
12a20 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 ative, and so th
12a30 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 e current limit
12a40 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 .** can be queri
12a50 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e ed by passing in
12a60 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 a pointer to a
12a70 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e negative number.
12a80 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 This.** file-c
12a90 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 ontrol is used i
12aa0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 nternally to imp
12ab0 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d lement [PRAGMA m
12ac0 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a map_size]..**.**
12ad0 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 <li>[[SQLITE_FC
12ae0 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 NTL_TRACE]].** T
12af0 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c he [SQLITE_FCNTL
12b00 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e _TRACE] file con
12b10 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 trol provides ad
12b20 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 visory informati
12b30 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 on.** to the VFS
12b40 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 about what the
12b50 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 higher layers of
12b60 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 the SQLite stac
12b70 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 k are doing..**
12b80 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f This file contro
12b90 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d l is used by som
12ba0 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20 74 e VFS activity t
12bb0 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a racing [shims]..
12bc0 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 ** The argument
12bd0 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e is a zero-termin
12be0 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 ated string. Hi
12bf0 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 gher layers in t
12c00 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 he.** SQLite sta
12c10 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 ck may generate
12c20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 instances of thi
12c30 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 s file control i
12c40 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 f.** the [SQLITE
12c50 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 _USE_FCNTL_TRACE
12c60 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
12c70 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ption is enabled
12c80 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
12c90 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d LITE_FCNTL_HAS_M
12ca0 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 OVED]].** The [S
12cb0 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f QLITE_FCNTL_HAS_
12cc0 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 MOVED] file cont
12cd0 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 rol interprets i
12ce0 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 ts argument as a
12cf0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 .** pointer to a
12d00 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 n integer and it
12d10 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 writes a boolea
12d20 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 n into that inte
12d30 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a ger depending.**
12d40 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e on whether or n
12d50 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 ot the file has
12d60 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f been renamed, mo
12d70 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 ved, or deleted
12d80 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 since it.** was
12d90 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a first opened..**
12da0 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
12db0 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 _FCNTL_WIN32_GET
12dc0 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 _HANDLE]].** The
12dd0 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [SQLITE_FCNTL_W
12de0 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d IN32_GET_HANDLE]
12df0 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 opcode can be u
12e00 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 sed to obtain th
12e10 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 e.** underlying
12e20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 native file hand
12e30 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 le associated wi
12e40 74 68 20 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 th a file handle
12e50 2e 20 20 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 . This file.**
12e60 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 control interpre
12e70 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 ts its argument
12e80 61 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 as a pointer to
12e90 61 20 6e 61 74 69 76 65 20 66 69 6c 65 20 68 61 a native file ha
12ea0 6e 64 6c 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 ndle and.** writ
12eb0 65 73 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 es the resulting
12ec0 20 76 61 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a value there..**
12ed0 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
12ee0 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 _FCNTL_WIN32_SET
12ef0 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 _HANDLE]].** The
12f00 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 [SQLITE_FCNTL_W
12f10 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d IN32_SET_HANDLE]
12f20 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 opcode is used
12f30 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 for debugging.
12f40 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 This.** opcode c
12f50 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 auses the xFileC
12f60 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f ontrol method to
12f70 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 swap the file h
12f80 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f andle with the o
12f90 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f ne.** pointed to
12fa0 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72 67 by the pArg arg
12fb0 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 ument. This cap
12fc0 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 ability is used
12fd0 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a during testing.*
12fe0 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 * and only needs
12ff0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 to be supported
13000 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 when SQLITE_TES
13010 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a T is defined..**
13020 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 .** <li>[[SQLITE
13030 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b _FCNTL_WAL_BLOCK
13040 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 ]].** The [SQLIT
13050 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 E_FCNTL_WAL_BLOC
13060 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20 74 K] is a signal t
13070 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72 20 o the VFS layer
13080 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a that it might.**
13090 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75 73 be advantageous
130a0 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 to block on the
130b0 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 next WAL lock i
130c0 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f f the lock is no
130d0 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a t immediately.**
130e0 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 available. The
130f0 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20 69 WAL subsystem i
13100 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e 61 ssues this signa
13110 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a l during rare.**
13120 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 69 circumstances i
13130 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20 61 n order to fix a
13140 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 problem with pr
13150 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f 6e iority inversion
13160 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e ..** Application
13170 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 s should <em>not
13180 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20 66 </em> use this f
13190 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a ile-control..**.
131a0 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f ** <li>[[SQLITE_
131b0 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a FCNTL_ZIPVFS]].*
131c0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 * The [SQLITE_FC
131d0 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f NTL_ZIPVFS] opco
131e0 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 de is implemente
131f0 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 d by zipvfs only
13200 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 . All other.** V
13210 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e FS should return
13220 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 SQLITE_NOTFOUND
13230 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 for this opcode
13240 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 ..**.** <li>[[SQ
13250 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d LITE_FCNTL_RBU]]
13260 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f .** The [SQLITE_
13270 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 FCNTL_RBU] opcod
13280 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 e is implemented
13290 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c 20 by the special
132a0 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 VFS used by.** t
132b0 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f 6e he RBU extension
132c0 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 only. All othe
132d0 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 r VFS should ret
132e0 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f urn SQLITE_NOTFO
132f0 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 UND for.** this
13300 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 opcode. .**.**
13310 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e <li>[[SQLITE_FCN
13320 54 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f TL_BEGIN_ATOMIC_
13330 57 52 49 54 45 5d 5d 0a 2a 2a 20 49 66 20 74 68 WRITE]].** If th
13340 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f e [SQLITE_FCNTL_
13350 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 BEGIN_ATOMIC_WRI
13360 54 45 5d 20 6f 70 63 6f 64 65 20 72 65 74 75 72 TE] opcode retur
13370 6e 73 20 53 51 4c 49 54 45 5f 4f 4b 2c 20 74 68 ns SQLITE_OK, th
13380 65 6e 0a 2a 2a 20 74 68 65 20 66 69 6c 65 20 64 en.** the file d
13390 65 73 63 72 69 70 74 6f 72 20 69 73 20 70 6c 61 escriptor is pla
133a0 63 65 64 20 69 6e 20 22 62 61 74 63 68 20 77 72 ced in "batch wr
133b0 69 74 65 20 6d 6f 64 65 22 2c 20 77 68 69 63 68 ite mode", which
133c0 0a 2a 2a 20 6d 65 61 6e 73 20 61 6c 6c 20 73 75 .** means all su
133d0 62 73 65 71 75 65 6e 74 20 77 72 69 74 65 20 6f bsequent write o
133e0 70 65 72 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 perations will b
133f0 65 20 64 65 66 65 72 72 65 64 20 61 6e 64 20 64 e deferred and d
13400 6f 6e 65 0a 2a 2a 20 61 74 6f 6d 69 63 61 6c 6c one.** atomicall
13410 79 20 61 74 20 74 68 65 20 6e 65 78 74 20 5b 53 y at the next [S
13420 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d QLITE_FCNTL_COMM
13430 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d IT_ATOMIC_WRITE]
13440 2e 20 20 53 79 73 74 65 6d 73 0a 2a 2a 20 74 68 . Systems.** th
13450 61 74 20 64 6f 20 6e 6f 74 20 73 75 70 70 6f 72 at do not suppor
13460 74 20 62 61 74 63 68 20 61 74 6f 6d 69 63 20 77 t batch atomic w
13470 72 69 74 65 73 20 77 69 6c 6c 20 72 65 74 75 72 rites will retur
13480 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e n SQLITE_NOTFOUN
13490 44 2e 0a 2a 2a 20 5e 46 6f 6c 6c 6f 77 69 6e 67 D..** ^Following
134a0 20 61 20 73 75 63 63 65 73 73 66 75 6c 20 53 51 a successful SQ
134b0 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e LITE_FCNTL_BEGIN
134c0 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 20 61 6e _ATOMIC_WRITE an
134d0 64 20 70 72 69 6f 72 20 74 6f 0a 2a 2a 20 74 68 d prior to.** th
134e0 65 20 63 6c 6f 73 69 6e 67 20 5b 53 51 4c 49 54 e closing [SQLIT
134f0 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 41 E_FCNTL_COMMIT_A
13500 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 72 0a TOMIC_WRITE] or.
13510 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c ** [SQLITE_FCNTL
13520 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 _ROLLBACK_ATOMIC
13530 5f 57 52 49 54 45 5d 2c 20 53 51 4c 69 74 65 20 _WRITE], SQLite
13540 77 69 6c 6c 20 6d 61 6b 65 0a 2a 2a 20 6e 6f 20 will make.** no
13550 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 63 61 VFS interface ca
13560 6c 6c 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 lls on the same
13570 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 66 [sqlite3_file] f
13580 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 0a 2a ile descriptor.*
13590 2a 20 65 78 63 65 70 74 20 66 6f 72 20 63 61 6c * except for cal
135a0 6c 73 20 74 6f 20 74 68 65 20 78 57 72 69 74 65 ls to the xWrite
135b0 20 6d 65 74 68 6f 64 20 61 6e 64 20 74 68 65 20 method and the
135c0 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 xFileControl met
135d0 68 6f 64 0a 2a 2a 20 77 69 74 68 20 5b 53 51 4c hod.** with [SQL
135e0 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 ITE_FCNTL_SIZE_H
135f0 49 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e INT]..**.** <li>
13600 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 [[SQLITE_FCNTL_C
13610 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 52 49 OMMIT_ATOMIC_WRI
13620 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c TE]].** The [SQL
13630 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 ITE_FCNTL_COMMIT
13640 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f _ATOMIC_WRITE] o
13650 70 63 6f 64 65 20 63 61 75 73 65 73 20 61 6c 6c pcode causes all
13660 20 77 72 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 write.** operat
13670 69 6f 6e 73 20 73 69 6e 63 65 20 74 68 65 20 70 ions since the p
13680 72 65 76 69 6f 75 73 20 73 75 63 63 65 73 73 66 revious successf
13690 75 6c 20 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b ul call to .** [
136a0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 SQLITE_FCNTL_BEG
136b0 49 4e 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d IN_ATOMIC_WRITE]
136c0 20 74 6f 20 62 65 20 70 65 72 66 6f 72 6d 65 64 to be performed
136d0 20 61 74 6f 6d 69 63 61 6c 6c 79 2e 0a 2a 2a 20 atomically..**
136e0 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f This file contro
136f0 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 l returns [SQLIT
13700 45 5f 4f 4b 5d 20 69 66 20 61 6e 64 20 6f 6e 6c E_OK] if and onl
13710 79 20 69 66 20 74 68 65 20 77 72 69 74 65 73 20 y if the writes
13720 77 65 72 65 0a 2a 2a 20 61 6c 6c 20 70 65 72 66 were.** all perf
13730 6f 72 6d 65 64 20 73 75 63 63 65 73 73 66 75 6c ormed successful
13740 6c 79 20 61 6e 64 20 68 61 76 65 20 62 65 65 6e ly and have been
13750 20 63 6f 6d 6d 69 74 74 65 64 20 74 6f 20 70 65 committed to pe
13760 72 73 69 73 74 65 6e 74 20 73 74 6f 72 61 67 65 rsistent storage
13770 2e 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 ..** ^Regardless
13780 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e of whether or n
13790 6f 74 20 69 74 20 69 73 20 73 75 63 63 65 73 73 ot it is success
137a0 66 75 6c 2c 20 74 68 69 73 20 66 69 6c 65 20 63 ful, this file c
137b0 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 0a 2a 2a 20 ontrol takes.**
137c0 74 68 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 the file descrip
137d0 74 6f 72 20 6f 75 74 20 6f 66 20 62 61 74 63 68 tor out of batch
137e0 20 77 72 69 74 65 20 6d 6f 64 65 20 73 6f 20 74 write mode so t
137f0 68 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 hat all subseque
13800 6e 74 0a 2a 2a 20 77 72 69 74 65 20 6f 70 65 72 nt.** write oper
13810 61 74 69 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 ations are indep
13820 65 6e 64 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 endent..** ^SQLi
13830 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e te will never in
13840 76 6f 6b 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 voke SQLITE_FCNT
13850 4c 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f L_COMMIT_ATOMIC_
13860 57 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a WRITE without.**
13870 20 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 a prior success
13880 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c ful call to [SQL
13890 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f ITE_FCNTL_BEGIN_
138a0 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a ATOMIC_WRITE]..*
138b0 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 *.** <li>[[SQLIT
138c0 45 5f 46 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b E_FCNTL_ROLLBACK
138d0 5f 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 5d 0a _ATOMIC_WRITE]].
138e0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 ** The [SQLITE_F
138f0 43 4e 54 4c 5f 52 4f 4c 4c 42 41 43 4b 5f 41 54 CNTL_ROLLBACK_AT
13900 4f 4d 49 43 5f 57 52 49 54 45 5d 20 6f 70 63 6f OMIC_WRITE] opco
13910 64 65 20 63 61 75 73 65 73 20 61 6c 6c 20 77 72 de causes all wr
13920 69 74 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e ite.** operation
13930 73 20 73 69 6e 63 65 20 74 68 65 20 70 72 65 76 s since the prev
13940 69 6f 75 73 20 73 75 63 63 65 73 73 66 75 6c 20 ious successful
13950 63 61 6c 6c 20 74 6f 20 0a 2a 2a 20 5b 53 51 4c call to .** [SQL
13960 49 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f ITE_FCNTL_BEGIN_
13970 41 54 4f 4d 49 43 5f 57 52 49 54 45 5d 20 74 6f ATOMIC_WRITE] to
13980 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e be rolled back.
13990 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 20 63 .** ^This file c
139a0 6f 6e 74 72 6f 6c 20 74 61 6b 65 73 20 74 68 65 ontrol takes the
139b0 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 file descriptor
139c0 20 6f 75 74 20 6f 66 20 62 61 74 63 68 20 77 72 out of batch wr
139d0 69 74 65 20 6d 6f 64 65 0a 2a 2a 20 73 6f 20 74 ite mode.** so t
139e0 68 61 74 20 61 6c 6c 20 73 75 62 73 65 71 75 65 hat all subseque
139f0 6e 74 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 nt write operati
13a00 6f 6e 73 20 61 72 65 20 69 6e 64 65 70 65 6e 64 ons are independ
13a10 65 6e 74 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ent..** ^SQLite
13a20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b will never invok
13a30 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 e SQLITE_FCNTL_R
13a40 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f 57 OLLBACK_ATOMIC_W
13a50 52 49 54 45 20 77 69 74 68 6f 75 74 0a 2a 2a 20 RITE without.**
13a60 61 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 a prior successf
13a70 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 53 51 4c 49 ul call to [SQLI
13a80 54 45 5f 46 43 4e 54 4c 5f 42 45 47 49 4e 5f 41 TE_FCNTL_BEGIN_A
13a90 54 4f 4d 49 43 5f 57 52 49 54 45 5d 2e 0a 2a 2a TOMIC_WRITE]..**
13aa0 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e </ul>.*/.#defin
13ab0 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c e SQLITE_FCNTL_L
13ac0 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 OCKSTATE
13ad0 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
13ae0 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 SQLITE_FCNTL_GE
13af0 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 T_LOCKPROXYFILE
13b00 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 2.#define
13b10 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 SQLITE_FCNTL_SET
13b20 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 _LOCKPROXYFILE
13b30 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 3.#define S
13b40 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 QLITE_FCNTL_LAST
13b50 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 _ERRNO
13b60 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4.#define SQ
13b70 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f LITE_FCNTL_SIZE_
13b80 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 HINT
13b90 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 5.#define SQL
13ba0 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f ITE_FCNTL_CHUNK_
13bb0 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 SIZE
13bc0 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 6.#define SQLI
13bd0 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f TE_FCNTL_FILE_PO
13be0 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 INTER
13bf0 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 7.#define SQLIT
13c00 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 E_FCNTL_SYNC_OMI
13c10 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 TTED
13c20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 8.#define SQLITE
13c30 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f _FCNTL_WIN32_AV_
13c40 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 RETRY 9
13c50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
13c60 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 FCNTL_PERSIST_WA
13c70 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a L 10.
13c80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
13c90 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 CNTL_OVERWRITE
13ca0 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 11.#
13cb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
13cc0 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 NTL_VFSNAME
13cd0 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 12.#d
13ce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
13cf0 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 TL_POWERSAFE_OVE
13d00 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 RWRITE 13.#de
13d10 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
13d20 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 L_PRAGMA
13d30 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 14.#def
13d40 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
13d50 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 _BUSYHANDLER
13d60 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 15.#defi
13d70 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
13d80 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 TEMPFILENAME
13d90 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 16.#defin
13da0 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d e SQLITE_FCNTL_M
13db0 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 MAP_SIZE
13dc0 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 18.#define
13dd0 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 SQLITE_FCNTL_TR
13de0 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 ACE
13df0 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 19.#define
13e00 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 SQLITE_FCNTL_HAS
13e10 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 _MOVED
13e20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 20.#define S
13e30 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 QLITE_FCNTL_SYNC
13e40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
13e50 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 21.#define SQ
13e60 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 LITE_FCNTL_COMMI
13e70 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 T_PHASETWO
13e80 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 22.#define SQL
13e90 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f ITE_FCNTL_WIN32_
13ea0 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 SET_HANDLE
13eb0 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 23.#define SQLI
13ec0 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f TE_FCNTL_WAL_BLO
13ed0 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 CK
13ee0 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 24.#define SQLIT
13ef0 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 E_FCNTL_ZIPVFS
13f00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
13f10 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5.#define SQLITE
13f20 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 _FCNTL_RBU
13f30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 26
13f40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
13f50 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 FCNTL_VFS_POINTE
13f60 52 20 20 20 20 20 20 20 20 20 20 20 20 32 37 0a R 27.
13f70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 #define SQLITE_F
13f80 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 CNTL_JOURNAL_POI
13f90 4e 54 45 52 20 20 20 20 20 20 20 20 32 38 0a 23 NTER 28.#
13fa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 define SQLITE_FC
13fb0 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 NTL_WIN32_GET_HA
13fc0 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a 23 64 NDLE 29.#d
13fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e efine SQLITE_FCN
13fe0 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20 20 20 TL_PDB
13ff0 20 20 20 20 20 20 20 20 20 20 33 30 0a 23 64 65 30.#de
14000 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 fine SQLITE_FCNT
14010 4c 5f 42 45 47 49 4e 5f 41 54 4f 4d 49 43 5f 57 L_BEGIN_ATOMIC_W
14020 52 49 54 45 20 20 20 20 20 33 31 0a 23 64 65 66 RITE 31.#def
14030 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c ine SQLITE_FCNTL
14040 5f 43 4f 4d 4d 49 54 5f 41 54 4f 4d 49 43 5f 57 _COMMIT_ATOMIC_W
14050 52 49 54 45 20 20 20 20 33 32 0a 23 64 65 66 69 RITE 32.#defi
14060 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f ne SQLITE_FCNTL_
14070 52 4f 4c 4c 42 41 43 4b 5f 41 54 4f 4d 49 43 5f ROLLBACK_ATOMIC_
14080 57 52 49 54 45 20 20 33 33 0a 0a 2f 2a 20 64 65 WRITE 33../* de
14090 70 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a precated names *
140a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
140b0 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 _GET_LOCKPROXYFI
140c0 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 LE SQLITE_F
140d0 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f CNTL_GET_LOCKPRO
140e0 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 XYFILE.#define S
140f0 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 QLITE_SET_LOCKPR
14100 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c OXYFILE SQL
14110 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f ITE_FCNTL_SET_LO
14120 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 CKPROXYFILE.#def
14130 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f ine SQLITE_LAST_
14140 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 ERRNO
14150 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c SQLITE_FCNTL_L
14160 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a AST_ERRNO.../*.*
14170 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 * CAPI3REF: Mute
14180 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 x Handle.**.** T
14190 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 he mutex module
141a0 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 within SQLite de
141b0 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d fines [sqlite3_m
141c0 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a utex] to be an.*
141d0 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 * abstract type
141e0 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 for a mutex obje
141f0 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 ct. The SQLite
14200 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 core never looks
14210 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 .** at the inter
14220 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 nal representati
14230 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 on of an [sqlite
14240 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 3_mutex]. It on
14250 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 ly.** deals with
14260 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 pointers to the
14270 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d [sqlite3_mutex]
14280 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d object..**.** M
14290 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 utexes are creat
142a0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
142b0 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 3_mutex_alloc()]
142c0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 ..*/.typedef str
142d0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 uct sqlite3_mute
142e0 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b x sqlite3_mutex;
142f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
14300 3a 20 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e : Loadable Exten
14310 73 69 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a sion Thunk.**.**
14320 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 A pointer to th
14330 65 20 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 e opaque sqlite3
14340 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 _api_routines st
14350 72 75 63 74 75 72 65 20 69 73 20 70 61 73 73 65 ructure is passe
14360 64 20 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 d as.** the thir
14370 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 d parameter to e
14380 6e 74 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b ntry points of [
14390 6c 6f 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 loadable extensi
143a0 6f 6e 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 ons]. This.** s
143b0 74 72 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 tructure must be
143c0 20 74 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 typedefed in or
143d0 64 65 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 der to work arou
143e0 6e 64 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e nd compiler warn
143f0 69 6e 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 ings.** on some
14400 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 platforms..*/.ty
14410 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c pedef struct sql
14420 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 ite3_api_routine
14430 73 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f s sqlite3_api_ro
14440 75 74 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 utines;../*.** C
14450 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 API3REF: OS Inte
14460 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a rface Object.**.
14470 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f ** An instance o
14480 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 f the sqlite3_vf
14490 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 s object defines
144a0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 the interface b
144b0 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 etween.** the SQ
144c0 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 Lite core and th
144d0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 e underlying ope
144e0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 rating system.
144f0 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 The "vfs".** in
14500 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
14510 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f object stands fo
14520 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 r "virtual file
14530 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a system". See.**
14540 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 the [VFS | VFS
14550 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 documentation] f
14560 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 or further infor
14570 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 mation..**.** Th
14580 65 20 56 46 53 20 69 6e 74 65 72 66 61 63 65 20 e VFS interface
14590 69 73 20 73 6f 6d 65 74 69 6d 65 73 20 65 78 74 is sometimes ext
145a0 65 6e 64 65 64 20 62 79 20 61 64 64 69 6e 67 20 ended by adding
145b0 6e 65 77 20 6d 65 74 68 6f 64 73 20 6f 6e 74 6f new methods onto
145c0 0a 2a 2a 20 74 68 65 20 65 6e 64 2e 20 20 45 61 .** the end. Ea
145d0 63 68 20 74 69 6d 65 20 73 75 63 68 20 61 6e 20 ch time such an
145e0 65 78 74 65 6e 73 69 6f 6e 20 6f 63 63 75 72 73 extension occurs
145f0 2c 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 , the iVersion f
14600 69 65 6c 64 0a 2a 2a 20 69 73 20 69 6e 63 72 65 ield.** is incre
14610 6d 65 6e 74 65 64 2e 20 20 54 68 65 20 69 56 65 mented. The iVe
14620 72 73 69 6f 6e 20 76 61 6c 75 65 20 73 74 61 72 rsion value star
14630 74 65 64 20 6f 75 74 20 61 73 20 31 20 69 6e 0a ted out as 1 in.
14640 2a 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 ** SQLite [versi
14650 6f 6e 20 33 2e 35 2e 30 5d 20 6f 6e 20 5b 64 61 on 3.5.0] on [da
14660 74 65 6f 66 3a 33 2e 35 2e 30 5d 2c 20 74 68 65 teof:3.5.0], the
14670 6e 20 69 6e 63 72 65 61 73 65 64 20 74 6f 20 32 n increased to 2
14680 0a 2a 2a 20 77 69 74 68 20 53 51 4c 69 74 65 20 .** with SQLite
14690 5b 76 65 72 73 69 6f 6e 20 33 2e 37 2e 30 5d 20 [version 3.7.0]
146a0 6f 6e 20 5b 64 61 74 65 6f 66 3a 33 2e 37 2e 30 on [dateof:3.7.0
146b0 5d 2c 20 61 6e 64 20 74 68 65 6e 20 69 6e 63 72 ], and then incr
146c0 65 61 73 65 64 0a 2a 2a 20 74 6f 20 33 20 77 69 eased.** to 3 wi
146d0 74 68 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 th SQLite [versi
146e0 6f 6e 20 33 2e 37 2e 36 5d 20 6f 6e 20 5b 64 61 on 3.7.6] on [da
146f0 74 65 6f 66 3a 33 2e 37 2e 36 5d 2e 20 20 41 64 teof:3.7.6]. Ad
14700 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a ditional fields.
14710 2a 2a 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 ** may be append
14720 65 64 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 ed to the sqlite
14730 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 61 6e 64 3_vfs object and
14740 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 the iVersion va
14750 6c 75 65 0a 2a 2a 20 6d 61 79 20 69 6e 63 72 65 lue.** may incre
14760 61 73 65 20 61 67 61 69 6e 20 69 6e 20 66 75 74 ase again in fut
14770 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
14780 53 51 4c 69 74 65 2e 0a 2a 2a 20 4e 6f 74 65 20 SQLite..** Note
14790 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 that the structu
147a0 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c re.** of the sql
147b0 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 ite3_vfs object
147c0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 changes in the t
147d0 72 61 6e 73 69 74 69 6f 6e 20 66 72 6f 6d 0a 2a ransition from.*
147e0 2a 20 53 51 4c 69 74 65 20 5b 76 65 72 73 69 6f * SQLite [versio
147f0 6e 20 33 2e 35 2e 39 5d 20 74 6f 20 5b 76 65 72 n 3.5.9] to [ver
14800 73 69 6f 6e 20 33 2e 36 2e 30 5d 20 6f 6e 20 5b sion 3.6.0] on [
14810 64 61 74 65 6f 66 3a 33 2e 36 2e 30 5d 0a 2a 2a dateof:3.6.0].**
14820 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 and yet the iVe
14830 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 rsion field was
14840 6e 6f 74 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a not modified..**
14850 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 .** The szOsFile
14860 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 field is the si
14870 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 ze of the subcla
14880 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 ssed [sqlite3_fi
14890 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 le].** structure
148a0 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 used by this VF
148b0 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 S. mxPathname i
148c0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 s the maximum le
148d0 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 ngth of.** a pat
148e0 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 hname in this VF
148f0 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 S..**.** Registe
14900 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 red sqlite3_vfs
14910 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 objects are kept
14920 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 on a linked lis
14930 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 t formed by.** t
14940 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 he pNext pointer
14950 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f . The [sqlite3_
14960 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a vfs_register()].
14970 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f ** and [sqlite3_
14980 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 vfs_unregister()
14990 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e ] interfaces man
149a0 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a age this list.**
149b0 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 in a thread-saf
149c0 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c e way. The [sql
149d0 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d ite3_vfs_find()]
149e0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 interface.** se
149f0 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e arches the list.
14a00 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 Neither the ap
14a10 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e plication code n
14a20 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d or the VFS.** im
14a30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f plementation sho
14a40 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 uld use the pNex
14a50 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a t pointer..**.**
14a60 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 The pNext field
14a70 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 is the only fie
14a80 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 ld in the sqlite
14a90 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 3_vfs.** structu
14aa0 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 re that SQLite w
14ab0 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e ill ever modify.
14ac0 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e SQLite will on
14ad0 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 ly access.** or
14ae0 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c modify this fiel
14af0 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 d while holding
14b00 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 a particular sta
14b10 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 tic mutex..** Th
14b20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 e application sh
14b30 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 ould never modif
14b40 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 y anything withi
14b50 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 n the sqlite3_vf
14b60 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 s.** object once
14b70 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 the object has
14b80 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e been registered.
14b90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 .**.** The zName
14ba0 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 field holds the
14bb0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 name of the VFS
14bc0 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 module. The na
14bd0 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e me must.** be un
14be0 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 ique across all
14bf0 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a VFS modules..**.
14c00 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 ** [[sqlite3_vfs
14c10 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c .xOpen]].** ^SQL
14c20 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 ite guarantees t
14c30 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d hat the zFilenam
14c40 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 e parameter to x
14c50 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 Open.** is eithe
14c60 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
14c70 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 or string obtai
14c80 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c ned.** from xFul
14c90 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 lPathname() with
14ca0 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 an optional suf
14cb0 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 fix added..** ^I
14cc0 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 f a suffix is ad
14cd0 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 ded to the zFile
14ce0 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 name parameter,
14cf0 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 it will.** consi
14d00 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 st of a single "
14d10 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c -" character fol
14d20 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 lowed by no more
14d30 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 than.** 11 alph
14d40 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 anumeric and/or
14d50 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a "-" characters..
14d60 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 ** ^SQLite furth
14d70 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 er guarantees th
14d80 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 at.** the string
14d90 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 will be valid a
14da0 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 nd unchanged unt
14db0 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a il xClose() is.*
14dc0 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 * called. Becaus
14dd0 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 e of the previou
14de0 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 s sentence,.** t
14df0 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 he [sqlite3_file
14e00 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f ] can safely sto
14e10 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 re a pointer to
14e20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 the.** filename
14e30 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 if it needs to r
14e40 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 emember the file
14e50 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 name for some re
14e60 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 ason..** If the
14e70 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 zFilename parame
14e80 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 ter to xOpen is
14e90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 a NULL pointer t
14ea0 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 hen xOpen.** mus
14eb0 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e t invent its own
14ec0 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 temporary name
14ed0 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e for the file. ^
14ee0 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a Whenever the .**
14ef0 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d xFilename param
14f00 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 eter is NULL it
14f10 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 will also be the
14f20 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a case that the.*
14f30 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 * flags paramete
14f40 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b r will include [
14f50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 SQLITE_OPEN_DELE
14f60 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a TEONCLOSE]..**.*
14f70 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 * The flags argu
14f80 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 ment to xOpen()
14f90 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 includes all bit
14fa0 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 s set in.** the
14fb0 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 flags argument t
14fc0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f o [sqlite3_open_
14fd0 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 v2()]. Or if [s
14fe0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a qlite3_open()].*
14ff0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 * or [sqlite3_op
15000 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c en16()] is used,
15010 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c then flags incl
15020 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a udes at least.**
15030 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 [SQLITE_OPEN_RE
15040 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 ADWRITE] | [SQLI
15050 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e TE_OPEN_CREATE].
15060 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 .** If xOpen()
15070 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 opens a file rea
15080 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 d-only then it s
15090 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 ets *pOutFlags t
150a0 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 o.** include [SQ
150b0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e LITE_OPEN_READON
150c0 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 LY]. Other bits
150d0 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d in *pOutFlags m
150e0 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a ay be set..**.**
150f0 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 ^(SQLite will a
15100 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 lso add one of t
15110 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 he following fla
15120 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 gs to the xOpen(
15130 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e ).** call, depen
15140 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 ding on the obje
15150 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a ct being opened:
15160 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c .**.** <ul>.** <
15170 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 li> [SQLITE_OPE
15180 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c N_MAIN_DB].** <l
15190 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e i> [SQLITE_OPEN
151a0 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a _MAIN_JOURNAL].*
151b0 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f * <li> [SQLITE_
151c0 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a OPEN_TEMP_DB].**
151d0 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
151e0 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c PEN_TEMP_JOURNAL
151f0 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 ].** <li> [SQLI
15200 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e TE_OPEN_TRANSIEN
15210 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b T_DB].** <li> [
15220 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a SQLITE_OPEN_SUBJ
15230 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 OURNAL].** <li>
15240 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 [SQLITE_OPEN_MA
15250 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a STER_JOURNAL].**
15260 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f <li> [SQLITE_O
15270 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c PEN_WAL].** </ul
15280 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 >)^.**.** The fi
15290 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 le I/O implement
152a0 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 ation can use th
152b0 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c e object type fl
152c0 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 ags to.** change
152d0 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c the way it deal
152e0 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 s with files. F
152f0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 or example, an a
15300 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 pplication.** th
15310 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 at does not care
15320 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 about crash rec
15330 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 overy or rollbac
15340 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 k might make.**
15350 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f the open of a jo
15360 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d urnal file a no-
15370 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 op. Writes to t
15380 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c his journal woul
15390 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d d.** also be no-
153a0 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 ops, and any att
153b0 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 empt to read the
153c0 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 journal would r
153d0 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f eturn.** SQLITE_
153e0 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 IOERR. Or the i
153f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 mplementation mi
15400 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 ght recognize th
15410 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a at a database.**
15420 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f file will be do
15430 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 ing page-aligned
15440 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e sector reads an
15450 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 d writes in a ra
15460 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e ndom.** order an
15470 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f d set up its I/O
15480 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 subsystem accor
15490 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 dingly..**.** SQ
154a0 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 Lite might also
154b0 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 add one of the f
154c0 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 ollowing flags t
154d0 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 o the xOpen meth
154e0 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a od:.**.** <ul>.*
154f0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f * <li> [SQLITE_O
15500 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 PEN_DELETEONCLOS
15510 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 E].** <li> [SQLI
15520 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 TE_OPEN_EXCLUSIV
15530 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a E].** </ul>.**.*
15540 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 * The [SQLITE_OP
15550 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 EN_DELETEONCLOSE
15560 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 ] flag means the
15570 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a file should be.
15580 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 ** deleted when
15590 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e it is closed. ^
155a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e The [SQLITE_OPEN
155b0 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a _DELETEONCLOSE].
155c0 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 ** will be set f
155d0 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 or TEMP database
155e0 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 s and their jour
155f0 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a nals, transient.
15600 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e ** databases, an
15610 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a d subjournals..*
15620 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 *.** ^The [SQLIT
15630 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 E_OPEN_EXCLUSIVE
15640 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 ] flag is always
15650 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 used in conjunc
15660 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 tion.** with the
15670 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 [SQLITE_OPEN_CR
15680 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 EATE] flag, whic
15690 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 h are both direc
156a0 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 tly.** analogous
156b0 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 to the O_EXCL a
156c0 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 nd O_CREAT flags
156d0 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 of the POSIX op
156e0 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 en().** API. Th
156f0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 e SQLITE_OPEN_EX
15700 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 CLUSIVE flag, wh
15710 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 en paired with t
15720 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 he .** SQLITE_OP
15730 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 EN_CREATE, is us
15740 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 ed to indicate t
15750 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 hat file should
15760 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 always.** be cre
15770 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 ated, and that i
15780 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 t is an error if
15790 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 it already exis
157a0 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e ts..** It is <i>
157b0 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 not</i> used to
157c0 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c indicate the fil
157d0 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e e should be open
157e0 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 ed .** for exclu
157f0 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a sive access..**.
15800 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f ** ^At least szO
15810 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d sFile bytes of m
15820 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 emory are alloca
15830 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a ted by SQLite.**
15840 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 to hold the [s
15850 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 qlite3_file] str
15860 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 ucture passed as
15870 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 the third.** ar
15880 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e gument to xOpen.
15890 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 The xOpen meth
158a0 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 od does not have
158b0 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 to.** allocate
158c0 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 the structure; i
158d0 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 t should just fi
158e0 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 ll it in. Note
158f0 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 that.** the xOpe
15900 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 n method must se
15910 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 t the sqlite3_fi
15920 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 le.pMethods to e
15930 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 ither.** a valid
15940 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 [sqlite3_io_met
15950 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 hods] object or
15960 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 to NULL. xOpen
15970 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 must do.** this
15980 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e even if the open
15990 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 fails. SQLite
159a0 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 expects that the
159b0 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d sqlite3_file.pM
159c0 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e ethods.** elemen
159d0 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 t will be valid
159e0 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 after xOpen retu
159f0 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f rns regardless o
15a00 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a f the success.**
15a10 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 or failure of t
15a20 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a he xOpen call..*
15a30 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 *.** [[sqlite3_v
15a40 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 fs.xAccess]].**
15a50 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d ^The flags argum
15a60 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 ent to xAccess()
15a70 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f may be [SQLITE_
15a80 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a ACCESS_EXISTS].*
15a90 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 * to test for th
15aa0 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 e existence of a
15ab0 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 file, or [SQLIT
15ac0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 E_ACCESS_READWRI
15ad0 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 TE] to.** test w
15ae0 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 hether a file is
15af0 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 readable and wr
15b00 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 itable, or [SQLI
15b10 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a TE_ACCESS_READ].
15b20 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 ** to test wheth
15b30 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 er a file is at
15b40 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 least readable.
15b50 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 The file can b
15b60 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 e a.** directory
15b70 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 ..**.** ^SQLite
15b80 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f will always allo
15b90 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 cate at least mx
15ba0 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 Pathname+1 bytes
15bb0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 for the.** outp
15bc0 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 ut buffer xFullP
15bd0 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 athname. The ex
15be0 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 act size of the
15bf0 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a output buffer.**
15c00 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 is also passed
15c10 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 as a parameter t
15c20 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e o both methods.
15c30 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 If the output b
15c40 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 uffer.** is not
15c50 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 large enough, [S
15c60 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 QLITE_CANTOPEN]
15c70 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e should be return
15c80 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 ed. Since this i
15c90 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 s.** handled as
15ca0 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 a fatal error by
15cb0 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 SQLite, vfs imp
15cc0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f lementations sho
15cd0 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 uld endeavor.**
15ce0 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 to prevent this
15cf0 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 by setting mxPat
15d00 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 hname to a suffi
15d10 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 ciently large va
15d20 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 lue..**.** The x
15d30 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 Randomness(), xS
15d40 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 leep(), xCurrent
15d50 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 Time(), and xCur
15d60 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a rentTimeInt64().
15d70 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 ** interfaces ar
15d80 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 e not strictly a
15d90 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c part of the fil
15da0 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 esystem, but the
15db0 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 y are.** include
15dc0 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 d in the VFS str
15dd0 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c ucture for compl
15de0 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 eteness..** The
15df0 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 xRandomness() fu
15e00 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 nction attempts
15e10 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 to return nBytes
15e20 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f bytes.** of goo
15e30 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d d-quality random
15e40 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 ness into zOut.
15e50 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 The return valu
15e60 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 e is.** the actu
15e70 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 al number of byt
15e80 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 es of randomness
15e90 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 obtained..** Th
15ea0 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f e xSleep() metho
15eb0 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c d causes the cal
15ec0 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 ling thread to s
15ed0 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c leep for at.** l
15ee0 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 east the number
15ef0 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 of microseconds
15f00 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 given. ^The xCu
15f10 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d rrentTime().** m
15f20 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 ethod returns a
15f30 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 Julian Day Numbe
15f40 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e r for the curren
15f50 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 t date and time
15f60 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 as.** a floating
15f70 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a point value..**
15f80 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 ^The xCurrentTi
15f90 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 meInt64() method
15fa0 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 returns, as an
15fb0 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c integer, the Jul
15fc0 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 ian.** Day Numbe
15fd0 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 r multiplied by
15fe0 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 86400000 (the nu
15ff0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 mber of millisec
16000 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 onds in .** a 24
16010 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a -hour day). .**
16020 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 ^SQLite will us
16030 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 e the xCurrentTi
16040 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 meInt64() method
16050 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 to get the curr
16060 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 ent.** date and
16070 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 time if that met
16080 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 hod is available
16090 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 (if iVersion is
160a0 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 2 or .** greate
160b0 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 r and the functi
160c0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f on pointer is no
160d0 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c t NULL) and will
160e0 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f fall back.** to
160f0 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 xCurrentTime()
16100 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 if xCurrentTimeI
16110 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 nt64() is unavai
16120 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 lable..**.** ^Th
16130 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c e xSetSystemCall
16140 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 (), xGetSystemCa
16150 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 ll(), and xNestS
16160 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 ystemCall() inte
16170 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f rfaces.** are no
16180 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 t used by the SQ
16190 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 Lite core. Thes
161a0 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 e optional inter
161b0 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 faces are provid
161c0 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 ed.** by some VF
161d0 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 Ses to facilitat
161e0 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 e testing of the
161f0 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 VFS code. By ov
16200 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 erriding .** sys
16210 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 tem calls with f
16220 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 unctions under i
16230 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 ts control, a te
16240 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a st program can.*
16250 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 * simulate fault
16260 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 s and error cond
16270 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c itions that woul
16280 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 d otherwise be d
16290 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 ifficult.** or i
162a0 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 mpossible to ind
162b0 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 uce. The set of
162c0 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 system calls th
162d0 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 at can be overri
162e0 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 dden.** varies f
162f0 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 rom one VFS to a
16300 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d nother, and from
16310 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 one version of
16320 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 the same VFS to
16330 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 the.** next. Ap
16340 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 plications that
16350 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 use these interf
16360 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 aces must be pre
16370 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a pared for any.**
16380 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 or all of these
16390 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 interfaces to b
163a0 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 e NULL or for th
163b0 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 eir behavior to
163c0 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f change.** from o
163d0 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 ne release to th
163e0 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 e next. Applica
163f0 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 tions must not a
16400 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 ttempt to access
16410 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 .** any of these
16420 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 methods if the
16430 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 iVersion of the
16440 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e VFS is less than
16450 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 3..*/.typedef s
16460 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 truct sqlite3_vf
16470 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 s sqlite3_vfs;.t
16480 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 ypedef void (*sq
16490 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 lite3_syscall_pt
164a0 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 r)(void);.struct
164b0 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 sqlite3_vfs {.
164c0 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 int iVersion;
164d0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 /* Str
164e0 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e ucture version n
164f0 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 umber (currently
16500 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 3) */. int szO
16510 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 sFile;
16520 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 /* Size of sub
16530 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f classed sqlite3_
16540 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 file */. int mx
16550 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 Pathname;
16560 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 /* Maximum fi
16570 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 le pathname leng
16580 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f th */. sqlite3_
16590 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 vfs *pNext;
165a0 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 /* Next registe
165b0 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e red VFS */. con
165c0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 st char *zName;
165d0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 /* Name of
165e0 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 this virtual fi
165f0 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 le system */. v
16600 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 oid *pAppData;
16610 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 /* Point
16620 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f er to applicatio
16630 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 n-specific data
16640 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e */. int (*xOpen
16650 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 )(sqlite3_vfs*,
16660 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d const char *zNam
16670 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a e, sqlite3_file*
16680 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ,.
16690 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 int flags, int
166a0 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 *pOutFlags);. i
166b0 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 nt (*xDelete)(sq
166c0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
166d0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
166e0 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 nt syncDir);. i
166f0 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 nt (*xAccess)(sq
16700 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 lite3_vfs*, cons
16710 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 t char *zName, i
16720 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 nt flags, int *p
16730 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 ResOut);. int (
16740 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 *xFullPathname)(
16750 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f sqlite3_vfs*, co
16760 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c nst char *zName,
16770 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 int nOut, char
16780 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a *zOut);. void *
16790 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 (*xDlOpen)(sqlit
167a0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
167b0 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b har *zFilename);
167c0 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 . void (*xDlErr
167d0 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a or)(sqlite3_vfs*
167e0 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 , int nByte, cha
167f0 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 r *zErrMsg);. v
16800 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 oid (*(*xDlSym)(
16810 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 sqlite3_vfs*,voi
16820 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a d*, const char *
16830 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b zSymbol))(void);
16840 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f . void (*xDlClo
16850 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a se)(sqlite3_vfs*
16860 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 , void*);. int
16870 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 (*xRandomness)(s
16880 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 qlite3_vfs*, int
16890 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f nByte, char *zO
168a0 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c ut);. int (*xSl
168b0 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 eep)(sqlite3_vfs
168c0 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f *, int microseco
168d0 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 nds);. int (*xC
168e0 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 urrentTime)(sqli
168f0 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 te3_vfs*, double
16900 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 *);. int (*xGet
16910 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 LastError)(sqlit
16920 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 e3_vfs*, int, ch
16930 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a ar *);. /*. **
16940 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f The methods abo
16950 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f ve are in versio
16960 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 n 1 of the sqlit
16970 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a e_vfs object. *
16980 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 * definition. T
16990 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 hose that follow
169a0 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 are added in ve
169b0 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 rsion 2 or later
169c0 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 . */. int (*xC
169d0 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 urrentTimeInt64)
169e0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 (sqlite3_vfs*, s
169f0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a qlite3_int64*);.
16a00 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 /*. ** The me
16a10 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 thods above are
16a20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e in versions 1 an
16a30 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 d 2 of the sqlit
16a40 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 e_vfs object..
16a50 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 ** Those below a
16a60 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 re for version 3
16a70 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 and greater..
16a80 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 */. int (*xSetS
16a90 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 ystemCall)(sqlit
16aa0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 e3_vfs*, const c
16ab0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 har *zName, sqli
16ac0 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 te3_syscall_ptr)
16ad0 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 ;. sqlite3_sysc
16ae0 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 all_ptr (*xGetSy
16af0 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 stemCall)(sqlite
16b00 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 3_vfs*, const ch
16b10 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f ar *zName);. co
16b20 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 nst char *(*xNex
16b30 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c tSystemCall)(sql
16b40 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 ite3_vfs*, const
16b50 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 char *zName);.
16b60 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 /*. ** The met
16b70 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 hods above are i
16b80 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 n versions 1 thr
16b90 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 ough 3 of the sq
16ba0 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e lite_vfs object.
16bb0 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 . ** New fields
16bc0 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 may be appended
16bd0 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 in future versi
16be0 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 ons. The iVersi
16bf0 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 on. ** value wi
16c00 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 ll increment whe
16c10 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 never this happe
16c20 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a ns. . */.};../*
16c30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c .** CAPI3REF: Fl
16c40 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 ags for the xAcc
16c50 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a ess VFS method.*
16c60 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 *.** These integ
16c70 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e er constants can
16c80 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 be used as the
16c90 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 third parameter
16ca0 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 to.** the xAcces
16cb0 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b s method of an [
16cc0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a sqlite3_vfs] obj
16cd0 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 ect. They deter
16ce0 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e mine.** what kin
16cf0 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 d of permissions
16d00 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 the xAccess met
16d10 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 hod is looking f
16d20 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 or..** With SQLI
16d30 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 TE_ACCESS_EXISTS
16d40 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 , the xAccess me
16d50 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 thod.** simply c
16d60 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 hecks whether th
16d70 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a e file exists..*
16d80 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 * With SQLITE_AC
16d90 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 CESS_READWRITE,
16da0 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
16db0 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 od.** checks whe
16dc0 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 ther the named d
16dd0 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 irectory is both
16de0 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 readable and wr
16df0 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 itable.** (in ot
16e00 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 her words, if fi
16e10 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 les can be added
16e20 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 , removed, and r
16e30 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a enamed within.**
16e40 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e the directory).
16e50 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 .** The SQLITE_A
16e60 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 CCESS_READWRITE
16e70 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 constant is curr
16e80 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 ently used only
16e90 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f by the.** [temp_
16ea0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 store_directory
16eb0 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 pragma], though
16ec0 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 this could chang
16ed0 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a e in a future.**
16ee0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
16ef0 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 te..** With SQLI
16f00 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 TE_ACCESS_READ,
16f10 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 the xAccess meth
16f20 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 od.** checks whe
16f30 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 ther the file is
16f40 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 readable. The
16f50 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 SQLITE_ACCESS_RE
16f60 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a AD constant is.*
16f70 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 * currently unus
16f80 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 ed, though it mi
16f90 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 ght be used in a
16fa0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 future release
16fb0 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f of.** SQLite..*/
16fc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
16fd0 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 ACCESS_EXISTS
16fe0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 0.#define SQLIT
16ff0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 E_ACCESS_READWRI
17000 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 TE 1 /* Used b
17010 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 y PRAGMA temp_st
17020 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f ore_directory */
17030 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
17040 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 ACCESS_READ
17050 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2 /* Unused *
17060 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 /../*.** CAPI3RE
17070 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 F: Flags for the
17080 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 xShmLock VFS me
17090 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 thod.**.** These
170a0 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e integer constan
170b0 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 ts define the va
170c0 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 rious locking op
170d0 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f erations.** allo
170e0 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c wed by the xShmL
170f0 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 ock method of [s
17100 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 qlite3_io_method
17110 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c s]. The.** foll
17120 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e owing are the on
17130 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 ly legal combina
17140 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 tions of flags t
17150 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 o the.** xShmLoc
17160 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 k method:.**.**
17170 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 <ul>.** <li> SQ
17180 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 LITE_SHM_LOCK |
17190 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 SQLITE_SHM_SHARE
171a0 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 D.** <li> SQLIT
171b0 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c E_SHM_LOCK | SQL
171c0 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 ITE_SHM_EXCLUSIV
171d0 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 E.** <li> SQLIT
171e0 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 E_SHM_UNLOCK | S
171f0 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 QLITE_SHM_SHARED
17200 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 .** <li> SQLITE
17210 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 _SHM_UNLOCK | SQ
17220 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 LITE_SHM_EXCLUSI
17230 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a VE.** </ul>.**.*
17240 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 * When unlocking
17250 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 , the same SHARE
17260 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 D or EXCLUSIVE f
17270 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 lag must be supp
17280 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 lied as.** was g
17290 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 iven on the corr
172a0 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 esponding lock.
172b0 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d .**.** The xShm
172c0 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 Lock method can
172d0 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 transition betwe
172e0 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 en unlocked and
172f0 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 SHARED or.** bet
17300 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e ween unlocked an
17310 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 d EXCLUSIVE. It
17320 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 cannot transiti
17330 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 on between SHARE
17340 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 D.** and EXCLUSI
17350 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 VE..*/.#define S
17360 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b QLITE_SHM_UNLOCK
17370 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 1.#define
17380 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b SQLITE_SHM_LOCK
17390 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 2.#defi
173a0 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 ne SQLITE_SHM_SH
173b0 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 ARED 4.#de
173c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f fine SQLITE_SHM_
173d0 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a EXCLUSIVE 8..
173e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
173f0 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b Maximum xShmLock
17400 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 index.**.** The
17410 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 xShmLock method
17420 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f on [sqlite3_io_
17430 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 methods] may use
17440 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 values.** betwe
17450 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 en 0 and this up
17460 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 per bound as its
17470 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 "offset" argume
17480 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 nt..** The SQLit
17490 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 e core will neve
174a0 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 r attempt to acq
174b0 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 uire or release
174c0 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 a.** lock outsid
174d0 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a e of this range.
174e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
174f0 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 E_SHM_NLOCK
17500 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 8.../*.** CAP
17510 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a I3REF: Initializ
17520 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 e The SQLite Lib
17530 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 rary.**.** ^The
17540 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
17550 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 ze() routine ini
17560 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 tializes the.**
17570 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 SQLite library.
17580 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 ^The sqlite3_sh
17590 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 utdown() routine
175a0 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 .** deallocates
175b0 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 any resources th
175c0 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 at were allocate
175d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 d by sqlite3_ini
175e0 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 tialize()..** Th
175f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 ese routines are
17600 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 designed to aid
17610 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 in process init
17620 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a ialization and.*
17630 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d * shutdown on em
17640 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 bedded systems.
17650 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 Workstation app
17660 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a lications using.
17670 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c ** SQLite normal
17680 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 ly do not need t
17690 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 o invoke either
176a0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 of these routine
176b0 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 s..**.** A call
176c0 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 to sqlite3_initi
176d0 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 alize() is an "e
176e0 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 ffective" call i
176f0 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 f it is.** the f
17700 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 irst time sqlite
17710 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 3_initialize() i
17720 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 s invoked during
17730 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 the lifetime of
17740 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c .** the process,
17750 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 or if it is the
17760 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 first time sqli
17770 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 te3_initialize()
17780 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 is invoked.** f
17790 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 ollowing a call
177a0 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 to sqlite3_shutd
177b0 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 own(). ^(Only a
177c0 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c n effective call
177d0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 .** of sqlite3_i
177e0 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 nitialize() does
177f0 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 any initializat
17800 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 ion. All other
17810 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 calls.** are har
17820 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a mless no-ops.)^.
17830 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 **.** A call to
17840 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
17850 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 () is an "effect
17860 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 ive" call if it
17870 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 is the first.**
17880 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
17890 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 shutdown() since
178a0 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 the last sqlite
178b0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 3_initialize().
178c0 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 ^(Only.** an ef
178d0 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 fective call to
178e0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
178f0 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e () does any dein
17900 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a itialization..**
17910 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 All other valid
17920 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
17930 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 3_shutdown() are
17940 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 harmless no-ops
17950 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 .)^.**.** The sq
17960 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
17970 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
17980 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 threadsafe, but
17990 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
179a0 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 ().** is not. T
179b0 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 he sqlite3_shutd
179c0 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 own() interface
179d0 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c must only be cal
179e0 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 led from a.** si
179f0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c ngle thread. Al
17a00 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 l open [database
17a10 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 connections] mu
17a20 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 st be closed and
17a30 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 all.** other SQ
17a40 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d Lite resources m
17a50 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 ust be deallocat
17a60 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f ed prior to invo
17a70 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f king.** sqlite3_
17a80 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a shutdown()..**.*
17a90 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 * Among other th
17aa0 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 ings, ^sqlite3_i
17ab0 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c nitialize() will
17ac0 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 invoke.** sqlit
17ad0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 e3_os_init(). S
17ae0 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 imilarly, ^sqlit
17af0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a e3_shutdown().**
17b00 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c will invoke sql
17b10 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a ite3_os_end()..*
17b20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
17b30 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 3_initialize() r
17b40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b outine returns [
17b50 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 SQLITE_OK] on su
17b60 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f ccess..** ^If fo
17b70 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 r some reason, s
17b80 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
17b90 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f e() is unable to
17ba0 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 initialize.** t
17bb0 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 he library (perh
17bc0 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 aps it is unable
17bd0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e to allocate a n
17be0 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 eeded resource s
17bf0 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 uch.** as a mute
17c00 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e x) it returns an
17c10 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 [error code] ot
17c20 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 her than [SQLITE
17c30 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 _OK]..**.** ^The
17c40 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c sqlite3_initial
17c50 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ize() routine is
17c60 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c called internal
17c70 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 ly by many other
17c80 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 .** SQLite inter
17c90 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e faces so that an
17ca0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 application usu
17cb0 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 ally does not ne
17cc0 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 ed to.** invoke
17cd0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 sqlite3_initiali
17ce0 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 ze() directly.
17cf0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 For example, [sq
17d00 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a lite3_open()].**
17d10 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 calls sqlite3_i
17d20 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 nitialize() so t
17d30 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 he SQLite librar
17d40 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 y will be automa
17d50 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 tically.** initi
17d60 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c alized when [sql
17d70 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 ite3_open()] is
17d80 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 called if it has
17d90 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 not be initiali
17da0 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 zed.** already.
17db0 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 ^However, if SQ
17dc0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
17dd0 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 with the [SQLIT
17de0 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d E_OMIT_AUTOINIT]
17df0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 .** compile-time
17e00 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 option, then th
17e10 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c e automatic call
17e20 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 s to sqlite3_ini
17e30 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 tialize().** are
17e40 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 omitted and the
17e50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 application mus
17e60 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 t call sqlite3_i
17e70 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 nitialize() dire
17e80 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f ctly.** prior to
17e90 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 using any other
17ea0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 SQLite interfac
17eb0 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 e. For maximum
17ec0 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 portability,.**
17ed0 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 it is recommende
17ee0 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 d that applicati
17ef0 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b ons always invok
17f00 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 e sqlite3_initia
17f10 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 lize().** direct
17f20 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e ly prior to usin
17f30 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 g any other SQLi
17f40 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 te interface. F
17f50 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a uture releases.*
17f60 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 * of SQLite may
17f70 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 require this. I
17f80 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 n other words, t
17f90 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 he behavior exhi
17fa0 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 bited.** when SQ
17fb0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
17fc0 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d with [SQLITE_OM
17fd0 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 IT_AUTOINIT] mig
17fe0 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a ht become the.**
17ff0 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f default behavio
18000 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 r in some future
18010 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 release of SQLi
18020 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 te..**.** The sq
18030 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 lite3_os_init()
18040 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 routine does ope
18050 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 rating-system sp
18060 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 ecific.** initia
18070 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 lization of the
18080 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 SQLite library.
18090 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f The sqlite3_os_
180a0 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 end().** routine
180b0 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 undoes the effe
180c0 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 ct of sqlite3_os
180d0 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 _init(). Typica
180e0 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f l tasks.** perfo
180f0 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f rmed by these ro
18100 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 utines include a
18110 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 llocation or dea
18120 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 llocation.** of
18130 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 static resources
18140 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e , initialization
18150 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 of global varia
18160 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 bles,.** setting
18170 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 up a default [s
18180 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 qlite3_vfs] modu
18190 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 le, or setting u
181a0 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 p.** a default c
181b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 onfiguration usi
181c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ng [sqlite3_conf
181d0 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 ig()]..**.** The
181e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f application sho
181f0 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 uld never invoke
18200 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f either sqlite3_
18210 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 os_init().** or
18220 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 sqlite3_os_end()
18230 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 directly. The
18240 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 application shou
18250 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a ld only invoke.*
18260 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 * sqlite3_initia
18270 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 lize() and sqlit
18280 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 e3_shutdown().
18290 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 The sqlite3_os_i
182a0 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 nit().** interfa
182b0 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 ce is called aut
182c0 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 omatically by sq
182d0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 lite3_initialize
182e0 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 () and.** sqlite
182f0 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 3_os_end() is ca
18300 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f lled by sqlite3_
18310 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 shutdown(). App
18320 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c ropriate.** impl
18330 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 ementations for
18340 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 sqlite3_os_init(
18350 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 ) and sqlite3_os
18360 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 _end().** are bu
18370 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 ilt into SQLite
18380 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 when it is compi
18390 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 led for Unix, Wi
183a0 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a ndows, or OS/2..
183b0 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 ** When [custom
183c0 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 builds | built f
183d0 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 or other platfor
183e0 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 ms].** (using th
183f0 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 e [SQLITE_OS_OTH
18400 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 ER=1] compile-ti
18410 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 me.** option) th
18420 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
18430 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 st supply a suit
18440 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 able implementat
18450 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 ion for.** sqlit
18460 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 e3_os_init() and
18470 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 sqlite3_os_end(
18480 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 ). An applicati
18490 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 on-supplied.** i
184a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 mplementation of
184b0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 sqlite3_os_init
184c0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 () or sqlite3_os
184d0 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 _end().** must r
184e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b eturn [SQLITE_OK
184f0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 ] on success and
18500 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 some other [err
18510 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a or code] upon.**
18520 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c failure..*/.SQL
18530 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
18540 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 te3_initialize(v
18550 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 oid);.SQLITE_API
18560 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 int sqlite3_shu
18570 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c tdown(void);.SQL
18580 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
18590 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 te3_os_init(void
185a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e );.SQLITE_API in
185b0 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 t sqlite3_os_end
185c0 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 (void);../*.** C
185d0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
185e0 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 ring The SQLite
185f0 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 Library.**.** Th
18600 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 e sqlite3_config
18610 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 () interface is
18620 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f used to make glo
18630 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f bal configuratio
18640 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 n.** changes to
18650 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
18660 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 to tune SQLite t
18670 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e o the specific n
18680 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 eeds of.** the a
18690 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 pplication. The
186a0 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 default configu
186b0 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d ration is recomm
186c0 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a ended for most.*
186d0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 * applications a
186e0 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 nd so this routi
186f0 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f ne is usually no
18700 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 t necessary. It
18710 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 is.** provided
18720 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 to support rare
18730 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 applications wit
18740 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e h unusual needs.
18750 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 .**.** <b>The sq
18760 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 lite3_config() i
18770 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 nterface is not
18780 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65 20 threadsafe. The
18790 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d application.** m
187a0 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 ust ensure that
187b0 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 no other SQLite
187c0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 interfaces are i
187d0 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a nvoked by other.
187e0 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 ** threads while
187f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
18800 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 ) is running.</b
18810 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 >.**.** The sqli
18820 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 te3_config() int
18830 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e erface.** may on
18840 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 ly be invoked pr
18850 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 ior to library i
18860 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 nitialization us
18870 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f ing.** [sqlite3_
18880 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 initialize()] or
18890 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 after shutdown
188a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 by [sqlite3_shut
188b0 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 down()]..** ^If
188c0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
188d0 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 is called after
188e0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 [sqlite3_initia
188f0 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f lize()] and befo
18900 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 re.** [sqlite3_s
18910 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 hutdown()] then
18920 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 it will return S
18930 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a QLITE_MISUSE..**
18940 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 Note, however,
18950 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f that ^sqlite3_co
18960 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 nfig() can be ca
18970 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 lled as part of
18980 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 the.** implement
18990 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c ation of an appl
189a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
189b0 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 [sqlite3_os_init
189c0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 ()]..**.** The f
189d0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
189e0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 sqlite3_config(
189f0 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a ) is an integer.
18a00 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f ** [configuratio
18a10 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 n option] that d
18a20 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 etermines.** wha
18a30 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 t property of SQ
18a40 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f Lite is to be co
18a50 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 nfigured. Subse
18a60 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a quent arguments.
18a70 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e ** vary dependin
18a80 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 g on the [config
18a90 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a uration option].
18aa0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 ** in the first
18ab0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 argument..**.**
18ac0 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 ^When a configur
18ad0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 ation option is
18ae0 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e set, sqlite3_con
18af0 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 fig() returns [S
18b00 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 QLITE_OK]..** ^I
18b10 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 f the option is
18b20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 unknown or SQLit
18b30 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 e is unable to s
18b40 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a et the option.**
18b50 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 then this routi
18b60 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e ne returns a non
18b70 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
18b80 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 e]..*/.SQLITE_AP
18b90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f I int sqlite3_co
18ba0 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a nfig(int, ...);.
18bb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a ./*.** CAPI3REF:
18bc0 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 Configure datab
18bd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a ase connections.
18be0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 ** METHOD: sqlit
18bf0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c e3.**.** The sql
18c00 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 ite3_db_config()
18c10 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 interface is us
18c20 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 ed to make confi
18c30 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e guration.** chan
18c40 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 ges to a [databa
18c50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 se connection].
18c60 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 The interface i
18c70 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 s similar to.**
18c80 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 [sqlite3_config(
18c90 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 )] except that t
18ca0 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 he changes apply
18cb0 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 to a single.**
18cc0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
18cd0 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 tion] (specified
18ce0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
18cf0 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 gument)..**.** T
18d00 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 he second argume
18d10 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 nt to sqlite3_db
18d20 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 _config(D,V,...)
18d30 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c is the.** [SQL
18d40 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f ITE_DBCONFIG_LOO
18d50 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 KASIDE | configu
18d60 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 ration verb] - a
18d70 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a n integer code .
18d80 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 ** that indicate
18d90 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 s what aspect of
18da0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 the [database c
18db0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 onnection] is be
18dc0 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a ing configured..
18dd0 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 ** Subsequent ar
18de0 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 guments vary dep
18df0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f ending on the co
18e00 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 nfiguration verb
18e10 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 ..**.** ^Calls t
18e20 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e o sqlite3_db_con
18e30 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c fig() return SQL
18e40 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e ITE_OK if and on
18e50 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c ly if.** the cal
18e60 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 l is considered
18e70 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 successful..*/.S
18e80 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 QLITE_API int sq
18e90 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 lite3_db_config(
18ea0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 sqlite3*, int op
18eb0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 , ...);../*.** C
18ec0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 API3REF: Memory
18ed0 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 Allocation Routi
18ee0 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 nes.**.** An ins
18ef0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
18f00 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 ject defines the
18f10 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 interface betwe
18f20 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 en SQLite.** and
18f30 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 low-level memor
18f40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 y allocation rou
18f50 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 tines..**.** Thi
18f60 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 s object is used
18f70 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 in only one pla
18f80 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 ce in the SQLite
18f90 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 interface..** A
18fa0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 pointer to an i
18fb0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 nstance of this
18fc0 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 object is the ar
18fd0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 gument to.** [sq
18fe0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
18ff0 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 when the configu
19000 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
19010 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 .** [SQLITE_CONF
19020 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 IG_MALLOC] or [S
19030 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
19040 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 MALLOC]. .** By
19050 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 creating an ins
19060 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 tance of this ob
19070 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 ject.** and pass
19080 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 ing it to [sqlit
19090 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 e3_config]([SQLI
190a0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 TE_CONFIG_MALLOC
190b0 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e ]).** during con
190c0 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 figuration, an a
190d0 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 pplication can s
190e0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e pecify an altern
190f0 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 ative.** memory
19100 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 allocation subsy
19110 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 stem for SQLite
19120 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f to use for all o
19130 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 f its.** dynamic
19140 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a memory needs..*
19150 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 *.** Note that S
19160 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 QLite comes with
19170 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d several [built-
19180 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
19190 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 tors].** that ar
191a0 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 e perfectly adeq
191b0 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 uate for the ove
191c0 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 rwhelming majori
191d0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f ty of applicatio
191e0 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 ns.** and that t
191f0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e his object is on
19200 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 ly useful to a t
19210 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 iny minority of
19220 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 applications.**
19230 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 with specialized
19240 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 memory allocati
19250 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e on requirements.
19260 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 This object is
19270 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 .** also used du
19280 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 ring testing of
19290 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 SQLite in order
192a0 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c to specify an al
192b0 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d ternative.** mem
192c0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 ory allocator th
192d0 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d at simulates mem
192e0 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 ory out-of-memor
192f0 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a y conditions in.
19300 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 ** order to veri
19310 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 fy that SQLite r
19320 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c ecovers graceful
19330 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 ly from such.**
19340 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a conditions..**.*
19350 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 * The xMalloc, x
19360 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 Realloc, and xFr
19370 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 ee methods must
19380 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a work like the.**
19390 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c malloc(), reall
193a0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
193b0 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 functions from t
193c0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
193d0 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 brary..** ^SQLit
193e0 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 e guarantees tha
193f0 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 t the second arg
19400 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 ument to.** xRea
19410 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 lloc is always a
19420 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
19430 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 by a prior call
19440 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a to xRoundup..**.
19450 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 ** xSize should
19460 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 return the alloc
19470 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d ated size of a m
19480 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
19490 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f .** previously o
194a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 btained from xMa
194b0 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 lloc or xRealloc
194c0 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 . The allocated
194d0 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 size.** is alwa
194e0 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 ys at least as b
194f0 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 ig as the reques
19500 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 ted size but may
19510 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a be larger..**.*
19520 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d * The xRoundup m
19530 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 ethod returns wh
19540 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 at would be the
19550 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f allocated size o
19560 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c f.** a memory al
19570 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 location given a
19580 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 particular requ
19590 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 ested size. Mos
195a0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f t memory.** allo
195b0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 cators round up
195c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
195d0 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 ns at least to t
195e0 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 he next multiple
195f0 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 .** of 8. Some
19600 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 allocators round
19610 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 up to a larger
19620 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 multiple or to a
19630 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 power of 2..**
19640 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c Every memory all
19650 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 ocation request
19660 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 coming in throug
19670 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f h [sqlite3_mallo
19680 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 c()].** or [sqli
19690 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 te3_realloc()] f
196a0 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e irst calls xRoun
196b0 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 dup. If xRoundu
196c0 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a p returns 0, .**
196d0 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 that causes the
196e0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d corresponding m
196f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
19700 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 to fail..**.**
19710 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 The xInit method
19720 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 initializes the
19730 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f memory allocato
19740 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c r. For example,
19750 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c .** it might all
19760 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 ocate any requir
19770 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 e mutexes or ini
19780 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c tialize internal
19790 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 data.** structu
197a0 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 res. The xShutd
197b0 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e own method is in
197c0 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c voked (indirectl
197d0 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 y) by.** [sqlite
197e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 3_shutdown()] an
197f0 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 d should dealloc
19800 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 ate any resource
19810 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 s acquired.** by
19820 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 xInit. The pAp
19830 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 pData pointer is
19840 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c used as the onl
19850 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a y parameter to.*
19860 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 * xInit and xShu
19870 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c tdown..**.** SQL
19880 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 ite holds the [S
19890 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 QLITE_MUTEX_STAT
198a0 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 IC_MASTER] mutex
198b0 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 when it invokes
198c0 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 .** the xInit me
198d0 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e thod, so the xIn
198e0 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e it method need n
198f0 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 ot be threadsafe
19900 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 . The.** xShutd
19910 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e own method is on
19920 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b ly called from [
19930 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e sqlite3_shutdown
19940 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a ()] so it does.*
19950 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 * not need to be
19960 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 threadsafe eith
19970 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 er. For all oth
19980 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 er methods, SQLi
19990 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 te.** holds the
199a0 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 [SQLITE_MUTEX_ST
199b0 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 ATIC_MEM] mutex
199c0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a as long as the.*
199d0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 * [SQLITE_CONFIG
199e0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 _MEMSTATUS] conf
199f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
19a00 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 is turned on (w
19a10 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 hich.** it is by
19a20 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f default) and so
19a30 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 the methods are
19a40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 automatically s
19a50 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f erialized..** Ho
19a60 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 wever, if [SQLIT
19a70 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
19a80 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c US] is disabled,
19a90 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a then the other.
19aa0 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 ** methods must
19ab0 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 be threadsafe or
19ac0 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 else make their
19ad0 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 own arrangement
19ae0 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 s for.** seriali
19af0 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 zation..**.** SQ
19b00 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 Lite will never
19b10 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d invoke xInit() m
19b20 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 ore than once wi
19b30 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 thout an interve
19b40 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 ning.** call to
19b50 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a xShutdown()..*/.
19b60 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 typedef struct s
19b70 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
19b80 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d ds sqlite3_mem_m
19b90 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 ethods;.struct s
19ba0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f qlite3_mem_metho
19bb0 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 ds {. void *(*x
19bc0 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 Malloc)(int);
19bd0 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 /* Memory
19be0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 allocation funct
19bf0 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a ion */. void (*
19c00 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 xFree)(void*);
19c10 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 /* Free
19c20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 a prior allocati
19c30 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a on */. void *(*
19c40 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c xRealloc)(void*,
19c50 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 int); /* Resize
19c60 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a an allocation *
19c70 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 /. int (*xSize)
19c80 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 (void*);
19c90 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 /* Return the
19ca0 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f size of an allo
19cb0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 cation */. int
19cc0 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 (*xRoundup)(int)
19cd0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f ; /* Ro
19ce0 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 und up request s
19cf0 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f ize to allocatio
19d00 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 n size */. int
19d10 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b (*xInit)(void*);
19d20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e /* In
19d30 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d itialize the mem
19d40 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f ory allocator */
19d50 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 . void (*xShutd
19d60 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 own)(void*);
19d70 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a /* Deinitializ
19d80 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c e the memory all
19d90 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 ocator */. void
19da0 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 *pAppData;
19db0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 /* Ar
19dc0 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 gument to xInit(
19dd0 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 ) and xShutdown(
19de0 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 ) */.};../*.** C
19df0 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 API3REF: Configu
19e00 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a ration Options.*
19e10 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e * KEYWORDS: {con
19e20 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
19e30 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 n}.**.** These c
19e40 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 onstants are the
19e50 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 available integ
19e60 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e er configuration
19e70 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a options that.**
19e80 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 can be passed a
19e90 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 s the first argu
19ea0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c ment to the [sql
19eb0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 ite3_config()] i
19ec0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 nterface..**.**
19ed0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f New configuratio
19ee0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 n options may be
19ef0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 added in future
19f00 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c releases of SQL
19f10 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 ite..** Existing
19f20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
19f30 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 ptions might be
19f40 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 discontinued. A
19f50 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 pplications.** s
19f60 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 hould check the
19f70 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d return code from
19f80 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
19f90 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 ()] to make sure
19fa0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c that.** the cal
19fb0 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b l worked. The [
19fc0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
19fd0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c ] interface will
19fe0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e return a.** non
19ff0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 -zero [error cod
1a000 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 e] if a disconti
1a010 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 nued or unsuppor
1a020 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f ted configuratio
1a030 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 n option.** is i
1a040 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 nvoked..**.** <d
1a050 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 l>.** [[SQLITE_C
1a060 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 ONFIG_SINGLETHRE
1a070 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f AD]] <dt>SQLITE_
1a080 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 CONFIG_SINGLETHR
1a090 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e EAD</dt>.** <dd>
1a0a0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 There are no arg
1a0b0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f uments to this o
1a0c0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 ption. ^This op
1a0d0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a tion sets the.**
1a0e0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 [threading mode
1a0f0 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 ] to Single-thre
1a100 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f ad. In other wo
1a110 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 rds, it disables
1a120 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 .** all mutexing
1a130 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 and puts SQLite
1a140 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 into a mode whe
1a150 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 re it can only b
1a160 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 e used.** by a s
1a170 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 ingle thread.
1a180 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f ^If SQLite is co
1a190 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 mpiled with.** t
1a1a0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 he [SQLITE_THREA
1a1b0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 DSAFE | SQLITE_T
1a1c0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d HREADSAFE=0] com
1a1d0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
1a1e0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e then.** it is n
1a1f0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 ot possible to c
1a200 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 hange the [threa
1a210 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 ding mode] from
1a220 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 its default.** v
1a230 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 alue of Single-t
1a240 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 hread and so [sq
1a250 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 lite3_config()]
1a260 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 will return .**
1a270 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 [SQLITE_ERROR] i
1a280 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 f called with th
1a290 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
1a2a0 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 SINGLETHREAD.**
1a2b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
1a2c0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a tion.</dd>.**.**
1a2d0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
1a2e0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c _MULTITHREAD]] <
1a2f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
1a300 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 _MULTITHREAD</dt
1a310 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 >.** <dd>There a
1a320 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 re no arguments
1a330 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 to this option.
1a340 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 ^This option se
1a350 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 ts the.** [threa
1a360 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 ding mode] to Mu
1a370 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 lti-thread. In
1a380 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 other words, it
1a390 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 disables.** mute
1a3a0 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 xing on [databas
1a3b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e e connection] an
1a3c0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 d [prepared stat
1a3d0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a ement] objects..
1a3e0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 ** The applicati
1a3f0 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c on is responsibl
1a400 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e e for serializin
1a410 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b g access to.** [
1a420 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1a430 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 ions] and [prepa
1a440 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e red statements].
1a450 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 But other mute
1a460 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c xes.** are enabl
1a470 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 ed so that SQLit
1a480 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 e will be safe t
1a490 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 o use in a multi
1a4a0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 -threaded.** env
1a4b0 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 ironment as long
1a4c0 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 as no two threa
1a4d0 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 ds attempt to us
1a4e0 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 e the same.** [d
1a4f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
1a500 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 on] at the same
1a510 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 time. ^If SQLit
1a520 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 e is compiled wi
1a530 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 th.** the [SQLIT
1a540 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 E_THREADSAFE | S
1a550 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 QLITE_THREADSAFE
1a560 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 =0] compile-time
1a570 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 option then.**
1a580 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 it is not possib
1a590 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 le to set the Mu
1a5a0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 lti-thread [thre
1a5b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a ading mode] and.
1a5c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 ** [sqlite3_conf
1a5d0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 ig()] will retur
1a5e0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d n [SQLITE_ERROR]
1a5f0 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 if called with
1a600 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f the.** SQLITE_CO
1a610 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 NFIG_MULTITHREAD
1a620 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
1a630 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a ption.</dd>.**.*
1a640 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
1a650 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c G_SERIALIZED]] <
1a660 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
1a670 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e _SERIALIZED</dt>
1a680 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 .** <dd>There ar
1a690 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 e no arguments t
1a6a0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 o this option.
1a6b0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 ^This option set
1a6c0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 s the.** [thread
1a6d0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 ing mode] to Ser
1a6e0 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 ialized. In othe
1a6f0 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 r words, this op
1a700 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 tion enables.**
1a710 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c all mutexes incl
1a720 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 uding the recurs
1a730 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f ive.** mutexes o
1a740 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e n [database conn
1a750 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 ection] and [pre
1a760 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
1a770 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 objects..** In
1a780 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 this mode (which
1a790 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 is the default
1a7a0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 when SQLite is c
1a7b0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 ompiled with.**
1a7c0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 [SQLITE_THREADSA
1a7d0 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 FE=1]) the SQLit
1a7e0 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 e library will i
1a7f0 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 tself serialize
1a800 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 access.** to [da
1a810 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1a820 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 ns] and [prepare
1a830 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f d statements] so
1a840 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 that the.** app
1a850 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 lication is free
1a860 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 to use the same
1a870 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 [database conne
1a880 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a ction] or the.**
1a890 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 same [prepared
1a8a0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 statement] in di
1a8b0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 fferent threads
1a8c0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 at the same time
1a8d0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 ..** ^If SQLite
1a8e0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 is compiled with
1a8f0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f .** the [SQLITE_
1a900 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c THREADSAFE | SQL
1a910 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 ITE_THREADSAFE=0
1a920 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
1a930 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 ption then.** it
1a940 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 is not possible
1a950 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 to set the Seri
1a960 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
1a970 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b g mode] and.** [
1a980 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 sqlite3_config()
1a990 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 ] will return [S
1a9a0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 QLITE_ERROR] if
1a9b0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a called with the.
1a9c0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ** SQLITE_CONFIG
1a9d0 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 _SERIALIZED conf
1a9e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e iguration option
1a9f0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 .</dd>.**.** [[S
1aa00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
1aa10 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 LOC]] <dt>SQLITE
1aa20 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f _CONFIG_MALLOC</
1aa30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 dt>.** <dd> ^(Th
1aa40 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f e SQLITE_CONFIG_
1aa50 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 MALLOC option ta
1aa60 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 kes a single arg
1aa70 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a ument which is .
1aa80 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 ** a pointer to
1aa90 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 an instance of t
1aaa0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f he [sqlite3_mem_
1aab0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 methods] structu
1aac0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d re..** The argum
1aad0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a ent specifies.**
1aae0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 alternative low
1aaf0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c -level memory al
1ab00 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 location routine
1ab10 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 s to be used in
1ab20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 place of.** the
1ab30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
1ab40 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 n routines built
1ab50 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 into SQLite.)^
1ab60 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a ^SQLite makes.**
1ab70 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 its own private
1ab80 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e copy of the con
1ab90 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c tent of the [sql
1aba0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
1abb0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 ] structure.** b
1abc0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 efore the [sqlit
1abd0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c e3_config()] cal
1abe0 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a l returns.</dd>.
1abf0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 **.** [[SQLITE_C
1ac00 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d ONFIG_GETMALLOC]
1ac10 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
1ac20 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 FIG_GETMALLOC</d
1ac30 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
1ac40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
1ac50 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 ETMALLOC option
1ac60 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
1ac70 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a rgument which.**
1ac80 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f is a pointer to
1ac90 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 an instance of
1aca0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d the [sqlite3_mem
1acb0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 _methods] struct
1acc0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c ure..** The [sql
1acd0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 ite3_mem_methods
1ace0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 ].** structure i
1acf0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 s filled with th
1ad00 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 e currently defi
1ad10 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ned memory alloc
1ad20 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 ation routines.)
1ad30 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e ^.** This option
1ad40 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
1ad50 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 overload the def
1ad60 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f ault memory allo
1ad70 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e cation.** routin
1ad80 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 es with a wrappe
1ad90 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f r that simulatio
1ada0 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 ns memory alloca
1adb0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a tion failure or.
1adc0 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 ** tracks memory
1add0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d usage, for exam
1ade0 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ple. </dd>.**.**
1adf0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
1ae00 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 5d 5d 20 _SMALL_MALLOC]]
1ae10 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
1ae20 47 5f 53 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 3c 2f G_SMALL_MALLOC</
1ae30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 dt>.** <dd> ^The
1ae40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
1ae50 4d 41 4c 4c 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 MALL_MALLOC opti
1ae60 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 on takes single
1ae70 61 72 67 75 6d 65 6e 74 20 6f 66 0a 2a 2a 20 74 argument of.** t
1ae80 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 ype int, interpr
1ae90 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 eted as a boolea
1aea0 6e 2c 20 77 68 69 63 68 20 69 66 20 74 72 75 65 n, which if true
1aeb0 20 70 72 6f 76 69 64 65 73 20 61 20 68 69 6e 74 provides a hint
1aec0 20 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 74 68 to.** SQLite th
1aed0 61 74 20 69 74 20 73 68 6f 75 6c 64 20 61 76 6f at it should avo
1aee0 69 64 20 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 id large memory
1aef0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 66 20 70 allocations if p
1af00 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 53 51 4c 69 ossible..** SQLi
1af10 74 65 20 77 69 6c 6c 20 72 75 6e 20 66 61 73 74 te will run fast
1af20 65 72 20 69 66 20 69 74 20 69 73 20 66 72 65 65 er if it is free
1af30 20 74 6f 20 6d 61 6b 65 20 6c 61 72 67 65 20 6d to make large m
1af40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1af50 73 2c 0a 2a 2a 20 62 75 74 20 73 6f 6d 65 20 61 s,.** but some a
1af60 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 pplication might
1af70 20 70 72 65 66 65 72 20 74 6f 20 72 75 6e 20 73 prefer to run s
1af80 6c 6f 77 65 72 20 69 6e 20 65 78 63 68 61 6e 67 lower in exchang
1af90 65 20 66 6f 72 0a 2a 2a 20 67 75 61 72 61 6e 74 e for.** guarant
1afa0 65 65 73 20 61 62 6f 75 74 20 6d 65 6d 6f 72 79 ees about memory
1afb0 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 74 fragmentation t
1afc0 68 61 74 20 61 72 65 20 70 6f 73 73 69 62 6c 65 hat are possible
1afd0 20 69 66 20 6c 61 72 67 65 0a 2a 2a 20 61 6c 6c if large.** all
1afe0 6f 63 61 74 69 6f 6e 73 20 61 72 65 20 61 76 6f ocations are avo
1aff0 69 64 65 64 2e 20 20 54 68 69 73 20 68 69 6e 74 ided. This hint
1b000 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f 66 66 is normally off
1b010 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a ..** </dd>.**.**
1b020 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 [[SQLITE_CONFIG
1b030 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 _MEMSTATUS]] <dt
1b040 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d >SQLITE_CONFIG_M
1b050 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a EMSTATUS</dt>.**
1b060 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 <dd> ^The SQLIT
1b070 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 E_CONFIG_MEMSTAT
1b080 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 US option takes
1b090 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 single argument
1b0a0 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 of type int,.**
1b0b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
1b0c0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 boolean, which
1b0d0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 enables or disab
1b0e0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 les the collecti
1b0f0 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 on of.** memory
1b100 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 allocation stati
1b110 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 stics. ^(When me
1b120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
1b130 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a statistics are.*
1b140 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 * disabled, the
1b150 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 following SQLite
1b160 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f interfaces beco
1b170 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e me non-operation
1b180 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a al:.** <ul>.**
1b190 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 <li> [sqlite3
1b1a0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a _memory_used()].
1b1b0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 ** <li> [sqlit
1b1c0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
1b1d0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e ter()].** <li>
1b1e0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 [sqlite3_soft_h
1b1f0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a eap_limit64()].*
1b200 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 * <li> [sqlite
1b210 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 3_status64()].**
1b220 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d </ul>)^.** ^M
1b230 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1b240 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 statistics are
1b250 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 enabled by defau
1b260 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 lt unless SQLite
1b270 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 is.** compiled
1b280 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 with [SQLITE_DEF
1b290 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d AULT_MEMSTATUS]=
1b2a0 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 0 in which case
1b2b0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 memory.** alloca
1b2c0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 tion statistics
1b2d0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 are disabled by
1b2e0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 default..** </dd
1b2f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 >.**.** [[SQLITE
1b300 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d _CONFIG_SCRATCH]
1b310 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e ] <dt>SQLITE_CON
1b320 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e FIG_SCRATCH</dt>
1b330 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c .** <dd> The SQL
1b340 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 ITE_CONFIG_SCRAT
1b350 43 48 20 6f 70 74 69 6f 6e 20 69 73 20 6e 6f 20 CH option is no
1b360 6c 6f 6e 67 65 72 20 75 73 65 64 2e 0a 2a 2a 20 longer used..**
1b370 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
1b380 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 LITE_CONFIG_PAGE
1b390 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 CACHE]] <dt>SQLI
1b3a0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 TE_CONFIG_PAGECA
1b3b0 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e CHE</dt>.** <dd>
1b3c0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e ^The SQLITE_CON
1b3d0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70 FIG_PAGECACHE op
1b3e0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 tion specifies a
1b3f0 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 memory pool.**
1b400 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 that SQLite can
1b410 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61 use for the data
1b420 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 base page cache
1b430 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 with the default
1b440 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 page.** cache i
1b450 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 mplementation.
1b460 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 .** This configu
1b470 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 ration option is
1b480 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 a no-op if an a
1b490 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e pplication-defin
1b4a0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 e page.** cache
1b4b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 implementation i
1b4c0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 s loaded using t
1b4d0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 he [SQLITE_CONFI
1b4e0 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e G_PCACHE2]..** ^
1b4f0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 There are three
1b500 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c arguments to SQL
1b510 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 ITE_CONFIG_PAGEC
1b520 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 ACHE: A pointer
1b530 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 to.** 8-byte ali
1b540 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 gned memory (pMe
1b550 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 m), the size of
1b560 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20 each page cache
1b570 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e line (sz),.** an
1b580 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 d the number of
1b590 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e cache lines (N).
1b5a0 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d .** The sz argum
1b5b0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 ent should be th
1b5c0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 e size of the la
1b5d0 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 rgest database p
1b5e0 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 age.** (a power
1b5f0 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 of two between 5
1b600 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c 12 and 65536) pl
1b610 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79 us some extra by
1b620 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 tes for each.**
1b630 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 page header. ^T
1b640 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 he number of ext
1b650 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20 ra bytes needed
1b660 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64 by the page head
1b670 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 er.** can be det
1b680 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 ermined using [S
1b690 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
1b6a0 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e CHE_HDRSZ]..** ^
1b6b0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 It is harmless,
1b6c0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 apart from the w
1b6d0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a asted memory,.**
1b6e0 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61 for the sz para
1b6f0 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67 meter to be larg
1b700 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72 er than necessar
1b710 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 y. The pMem.**
1b720 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 argument must be
1b730 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 either a NULL p
1b740 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e ointer or a poin
1b750 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 ter to an 8-byte
1b760 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 .** aligned bloc
1b770 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 k of memory of a
1b780 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 t least sz*N byt
1b790 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a es, otherwise.**
1b7a0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 subsequent beha
1b7b0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 vior is undefine
1b7c0 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d d..** ^When pMem
1b7d0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 is not NULL, SQ
1b7e0 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65 Lite will strive
1b7f0 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f to use the memo
1b800 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 ry provided.** t
1b810 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63 o satisfy page c
1b820 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c ache needs, fall
1b830 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c ing back to [sql
1b840 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 ite3_malloc()] i
1b850 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68 f.** a page cach
1b860 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72 e line is larger
1b870 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f than sz bytes o
1b880 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 r if all of the
1b890 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 pMem buffer.** i
1b8a0 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 s exhausted..**
1b8b0 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c ^If pMem is NULL
1b8c0 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 and N is non-ze
1b8d0 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61 ro, then each da
1b8e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1b8f0 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 n.** does an ini
1b900 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 tial bulk alloca
1b910 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61 tion for page ca
1b920 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 che memory.** fr
1b930 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c om [sqlite3_mall
1b940 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74 oc()] sufficient
1b950 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e for N cache lin
1b960 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74 es if N is posit
1b970 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 ive or.** of -10
1b980 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20 24*N bytes if N
1b990 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e is negative, . ^
1b9a0 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a If additional.**
1b9b0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f page cache memo
1b9c0 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 ry is needed bey
1b9d0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 ond what is prov
1b9e0 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74 ided by the init
1b9f0 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f ial.** allocatio
1ba00 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 n, then SQLite g
1ba10 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f oes to [sqlite3_
1ba20 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 malloc()] separa
1ba30 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a tely for each.**
1ba40 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 additional cach
1ba50 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a e line. </dd>.**
1ba60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
1ba70 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 FIG_HEAP]] <dt>S
1ba80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 QLITE_CONFIG_HEA
1ba90 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e P</dt>.** <dd> ^
1baa0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 The SQLITE_CONFI
1bab0 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 G_HEAP option sp
1bac0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 ecifies a static
1bad0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a memory buffer .
1bae0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 ** that SQLite w
1baf0 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 ill use for all
1bb00 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d of its dynamic m
1bb10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e emory allocation
1bb20 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 needs.** beyond
1bb30 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20 those provided
1bb40 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 for by [SQLITE_C
1bb50 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d ONFIG_PAGECACHE]
1bb60 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 ..** ^The SQLITE
1bb70 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 _CONFIG_HEAP opt
1bb80 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 ion is only avai
1bb90 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 lable if SQLite
1bba0 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 is compiled.** w
1bbb0 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 ith either [SQLI
1bbc0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 TE_ENABLE_MEMSYS
1bbd0 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 3] or [SQLITE_EN
1bbe0 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e ABLE_MEMSYS5] an
1bbf0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 d returns.** [SQ
1bc00 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 LITE_ERROR] if i
1bc10 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 nvoked otherwise
1bc20 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 ..** ^There are
1bc30 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 three arguments
1bc40 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 to SQLITE_CONFIG
1bc50 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 _HEAP:.** An 8-b
1bc60 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e yte aligned poin
1bc70 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 ter to the memor
1bc80 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 y,.** the number
1bc90 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 of bytes in the
1bca0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 memory buffer,
1bcb0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 and the minimum
1bcc0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e allocation size.
1bcd0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 .** ^If the firs
1bce0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d t pointer (the m
1bcf0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 emory pointer) i
1bd00 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c s NULL, then SQL
1bd10 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 ite reverts.** t
1bd20 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 o using its defa
1bd30 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 ult memory alloc
1bd40 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d ator (the system
1bd50 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d malloc() implem
1bd60 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e entation),.** un
1bd70 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 doing any prior
1bd80 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 invocation of [S
1bd90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c QLITE_CONFIG_MAL
1bda0 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a LOC]. ^If the.*
1bdb0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 * memory pointer
1bdc0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 is not NULL the
1bdd0 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 n the alternativ
1bde0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f e memory.** allo
1bdf0 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 cator is engaged
1be00 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f to handle all o
1be10 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 f SQLites memory
1be20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 allocation need
1be30 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 s..** The first
1be40 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d pointer (the mem
1be50 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 ory pointer) mus
1be60 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 t be aligned to
1be70 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 an 8-byte.** bou
1be80 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 ndary or subsequ
1be90 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 ent behavior of
1bea0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 SQLite will be u
1beb0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 ndefined..** The
1bec0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 minimum allocat
1bed0 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 ion size is capp
1bee0 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 ed at 2**12. Rea
1bef0 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a sonable values.*
1bf00 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 * for the minimu
1bf10 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a m allocation siz
1bf20 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 e are 2**5 throu
1bf30 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a gh 2**8.</dd>.**
1bf40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
1bf50 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e FIG_MUTEX]] <dt>
1bf60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 SQLITE_CONFIG_MU
1bf70 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e TEX</dt>.** <dd>
1bf80 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
1bf90 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f NFIG_MUTEX optio
1bfa0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 n takes a single
1bfb0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 argument which
1bfc0 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 is a.** pointer
1bfd0 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f to an instance o
1bfe0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
1bff0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 utex_methods] st
1c000 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 ructure..** The
1c010 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 argument specifi
1c020 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c es alternative l
1c030 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 ow-level mutex r
1c040 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 outines to be us
1c050 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 ed.** in place t
1c060 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 he mutex routine
1c070 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c s built into SQL
1c080 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 ite.)^ ^SQLite
1c090 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a makes a copy of.
1c0a0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f ** the content o
1c0b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d f the [sqlite3_m
1c0c0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 utex_methods] st
1c0d0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 ructure before t
1c0e0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 he call to.** [s
1c0f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d qlite3_config()]
1c100 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 returns. ^If SQ
1c110 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 Lite is compiled
1c120 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 with.** the [SQ
1c130 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 LITE_THREADSAFE
1c140 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 | SQLITE_THREADS
1c150 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 AFE=0] compile-t
1c160 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a ime option then.
1c170 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 ** the entire mu
1c180 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d texing subsystem
1c190 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d is omitted from
1c1a0 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 the build and h
1c1b0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a ence calls to.**
1c1c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 [sqlite3_config
1c1d0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c ()] with the SQL
1c1e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 ITE_CONFIG_MUTEX
1c1f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f configuration o
1c200 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 ption will.** re
1c210 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 turn [SQLITE_ERR
1c220 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 OR].</dd>.**.**
1c230 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
1c240 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 GETMUTEX]] <dt>S
1c250 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 QLITE_CONFIG_GET
1c260 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 MUTEX</dt>.** <d
1c270 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f d> ^(The SQLITE_
1c280 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 CONFIG_GETMUTEX
1c290 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 option takes a s
1c2a0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 ingle argument w
1c2b0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 hich.** is a poi
1c2c0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 nter to an insta
1c2d0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 nce of the [sqli
1c2e0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 te3_mutex_method
1c2f0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 s] structure. T
1c300 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d he.** [sqlite3_m
1c310 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a utex_methods].**
1c320 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 structure is fi
1c330 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 lled with the cu
1c340 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 rrently defined
1c350 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 mutex routines.)
1c360 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e ^.** This option
1c370 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
1c380 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 overload the def
1c390 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 ault mutex alloc
1c3a0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 ation.** routine
1c3b0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 s with a wrapper
1c3c0 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d used to track m
1c3d0 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 utex usage for p
1c3e0 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 erformance.** pr
1c3f0 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 ofiling or testi
1c400 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e ng, for example.
1c410 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 ^If SQLite is
1c420 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a compiled with.*
1c430 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 * the [SQLITE_TH
1c440 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 READSAFE | SQLIT
1c450 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 E_THREADSAFE=0]
1c460 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 compile-time opt
1c470 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 ion then.** the
1c480 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 entire mutexing
1c490 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 subsystem is omi
1c4a0 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 tted from the bu
1c4b0 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 ild and hence ca
1c4c0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 lls to.** [sqlit
1c4d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 e3_config()] wit
1c4e0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e h the SQLITE_CON
1c4f0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e FIG_GETMUTEX con
1c500 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
1c510 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e n will.** return
1c520 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e [SQLITE_ERROR].
1c530 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
1c540 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b LITE_CONFIG_LOOK
1c550 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 ASIDE]] <dt>SQLI
1c560 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 TE_CONFIG_LOOKAS
1c570 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e IDE</dt>.** <dd>
1c580 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f ^(The SQLITE_CO
1c590 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f NFIG_LOOKASIDE o
1c5a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 ption takes two
1c5b0 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 arguments that d
1c5c0 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 etermine.** the
1c5d0 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 default size of
1c5e0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 lookaside memory
1c5f0 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 on each [databa
1c600 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a se connection]..
1c610 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 ** The first arg
1c620 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 ument is the.**
1c630 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f size of each loo
1c640 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c kaside buffer sl
1c650 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e ot and the secon
1c660 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 d is the number
1c670 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f of.** slots allo
1c680 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 cated to each da
1c690 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
1c6a0 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 n.)^ ^(SQLITE_C
1c6b0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a ONFIG_LOOKASIDE.
1c6c0 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 ** sets the <i>d
1c6d0 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 efault</i> looka
1c6e0 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b side size. The [
1c6f0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
1c700 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 LOOKASIDE].** op
1c710 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 tion to [sqlite3
1c720 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 _db_config()] ca
1c730 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 n be used to cha
1c740 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 nge the lookasid
1c750 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 e.** configurati
1c760 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c on on individual
1c770 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 connections.)^
1c780 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 </dd>.**.** [[SQ
1c790 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
1c7a0 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 HE2]] <dt>SQLITE
1c7b0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c _CONFIG_PCACHE2<
1c7c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 /dt>.** <dd> ^(T
1c7d0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 he SQLITE_CONFIG
1c7e0 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 _PCACHE2 option
1c7f0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
1c800 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 rgument which is
1c810 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 .** a pointer t
1c820 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 o an [sqlite3_pc
1c830 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f ache_methods2] o
1c840 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a bject. This obj
1c850 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a ect specifies.**
1c860 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 the interface t
1c870 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 o a custom page
1c880 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 cache implementa
1c890 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 tion.)^.** ^SQLi
1c8a0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 te makes a copy
1c8b0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f of the [sqlite3_
1c8c0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d pcache_methods2]
1c8d0 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a object.</dd>.**
1c8e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
1c8f0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d FIG_GETPCACHE2]]
1c900 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 <dt>SQLITE_CONF
1c910 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 IG_GETPCACHE2</d
1c920 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 t>.** <dd> ^(The
1c930 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
1c940 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e ETPCACHE2 option
1c950 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
1c960 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a argument which.*
1c970 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 * is a pointer t
1c980 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 o an [sqlite3_pc
1c990 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f ache_methods2] o
1c9a0 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 bject. SQLite c
1c9b0 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 opies of.** the
1c9c0 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 current page cac
1c9d0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f he implementatio
1c9e0 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 n into that obje
1c9f0 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a ct.)^ </dd>.**.*
1ca00 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 * [[SQLITE_CONFI
1ca10 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 G_LOG]] <dt>SQLI
1ca20 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 TE_CONFIG_LOG</d
1ca30 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 t>.** <dd> The S
1ca40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 QLITE_CONFIG_LOG
1ca50 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 option is used
1ca60 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 to configure the
1ca70 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 SQLite.** globa
1ca80 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a l [error log]..*
1ca90 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 * (^The SQLITE_C
1caa0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e ONFIG_LOG option
1cab0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d takes two argum
1cac0 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 ents: a pointer
1cad0 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e to a.** function
1cae0 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 with a call sig
1caf0 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a nature of void(*
1cb00 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 )(void*,int,cons
1cb10 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e t char*), .** an
1cb20 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 d a pointer to v
1cb30 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e oid. ^If the fun
1cb40 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 ction pointer is
1cb50 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 not NULL, it is
1cb60 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b .** invoked by [
1cb70 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 sqlite3_log()] t
1cb80 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c o process each l
1cb90 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e ogging event. ^
1cba0 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 If the.** functi
1cbb0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 on pointer is NU
1cbc0 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 LL, the [sqlite3
1cbd0 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 _log()] interfac
1cbe0 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f e becomes a no-o
1cbf0 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 p..** ^The void
1cc00 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 pointer that is
1cc10 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d the second argum
1cc20 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f ent to SQLITE_CO
1cc30 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 NFIG_LOG is.** p
1cc40 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 assed through as
1cc50 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d the first param
1cc60 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c eter to the appl
1cc70 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 ication-defined
1cc80 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 logger.** functi
1cc90 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 on whenever that
1cca0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 function is inv
1ccb0 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f oked. ^The seco
1ccc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a nd parameter to.
1ccd0 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 ** the logger fu
1cce0 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 nction is a copy
1ccf0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 of the first pa
1cd00 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 rameter to the c
1cd10 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 orresponding.**
1cd20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 [sqlite3_log()]
1cd30 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 call and is inte
1cd40 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 nded to be a [re
1cd50 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e sult code] or an
1cd60 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 .** [extended re
1cd70 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 sult code]. ^Th
1cd80 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
1cd90 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 r passed to the
1cda0 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 logger is.** log
1cdb0 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 message after f
1cdc0 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 ormatting via [s
1cdd0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 qlite3_snprintf(
1cde0 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 )]..** The SQLit
1cdf0 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 e logging interf
1ce00 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 ace is not reent
1ce10 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 rant; the logger
1ce20 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 function.** sup
1ce30 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 plied by the app
1ce40 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f lication must no
1ce50 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c t invoke any SQL
1ce60 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a ite interface..*
1ce70 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 * In a multi-thr
1ce80 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f eaded applicatio
1ce90 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 n, the applicati
1cea0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 on-defined logge
1ceb0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 r.** function mu
1cec0 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 st be threadsafe
1ced0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b . </dd>.**.** [[
1cee0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
1cef0 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 I]] <dt>SQLITE_C
1cf00 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 ONFIG_URI.** <dd
1cf10 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f >^(The SQLITE_CO
1cf20 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 NFIG_URI option
1cf30 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 takes a single a
1cf40 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 rgument of type
1cf50 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a int..** If non-z
1cf60 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 ero, then URI ha
1cf70 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c ndling is global
1cf80 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 ly enabled. If t
1cf90 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 he parameter is
1cfa0 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 zero,.** then UR
1cfb0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c I handling is gl
1cfc0 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e obally disabled.
1cfd0 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c )^ ^If URI handl
1cfe0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a ing is globally.
1cff0 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 ** enabled, all
1d000 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 filenames passed
1d010 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 to [sqlite3_ope
1d020 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f n()], [sqlite3_o
1d030 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 pen_v2()],.** [s
1d040 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d qlite3_open16()]
1d050 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 or.** specified
1d060 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 as part of [ATT
1d070 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 ACH] commands ar
1d080 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 e interpreted as
1d090 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 URIs, regardles
1d0a0 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 s.** of whether
1d0b0 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 or not the [SQLI
1d0c0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 TE_OPEN_URI] fla
1d0d0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 g is set when th
1d0e0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f e database.** co
1d0f0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e nnection is open
1d100 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c ed. ^If it is gl
1d110 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c obally disabled,
1d120 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a filenames are.*
1d130 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 * only interpret
1d140 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 ed as URIs if th
1d150 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 e SQLITE_OPEN_UR
1d160 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 I flag is set wh
1d170 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 en the.** databa
1d180 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 se connection is
1d190 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 opened. ^(By de
1d1a0 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c fault, URI handl
1d1b0 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a ing is globally.
1d1c0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 ** disabled. The
1d1d0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d default value m
1d1e0 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 ay be changed by
1d1f0 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 compiling with
1d200 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 the.** [SQLITE_U
1d210 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 SE_URI] symbol d
1d220 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 efined.)^.**.**
1d230 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
1d240 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 COVERING_INDEX_S
1d250 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 CAN]] <dt>SQLITE
1d260 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 _CONFIG_COVERING
1d270 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c _INDEX_SCAN.** <
1d280 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 dd>^The SQLITE_C
1d290 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 ONFIG_COVERING_I
1d2a0 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e NDEX_SCAN option
1d2b0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 takes a single
1d2c0 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d integer.** argum
1d2d0 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 ent which is int
1d2e0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f erpreted as a bo
1d2f0 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 olean in order t
1d300 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 o enable or disa
1d310 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f ble.** the use o
1d320 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 f covering indic
1d330 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c es for full tabl
1d340 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 e scans in the q
1d350 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a uery optimizer..
1d360 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 ** ^The default
1d370 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 setting is deter
1d380 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 mined.** by the
1d390 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f [SQLITE_ALLOW_CO
1d3a0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 VERING_INDEX_SCA
1d3b0 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 N] compile-time
1d3c0 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f option, or is "o
1d3d0 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f n".** if that co
1d3e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f mpile-time optio
1d3f0 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a n is omitted..**
1d400 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 The ability to
1d410 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 disable the use
1d420 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 of covering indi
1d430 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 ces for full tab
1d440 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 le scans.** is b
1d450 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f ecause some inco
1d460 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 rrectly coded le
1d470 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e gacy application
1d480 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 s might malfunct
1d490 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 ion.** when the
1d4a0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 optimization is
1d4b0 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 enabled. Provid
1d4c0 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 ing the ability
1d4d0 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 to.** disable th
1d4e0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 e optimization a
1d4f0 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c llows the older,
1d500 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 buggy applicati
1d510 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a on code to work.
1d520 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 ** without chang
1d530 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 e even with newe
1d540 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 r versions of SQ
1d550 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 Lite..**.** [[SQ
1d560 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 LITE_CONFIG_PCAC
1d570 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f HE]] [[SQLITE_CO
1d580 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d NFIG_GETPCACHE]]
1d590 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
1d5a0 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 ONFIG_PCACHE and
1d5b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 SQLITE_CONFIG_G
1d5c0 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e ETPCACHE.** <dd>
1d5d0 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 These options a
1d5e0 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 re obsolete and
1d5f0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 should not be us
1d600 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a ed by new code..
1d610 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 ** They are reta
1d620 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 ined for backwar
1d630 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 ds compatibility
1d640 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d but are now no-
1d650 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a ops..** </dd>.**
1d660 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
1d670 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 FIG_SQLLOG]].**
1d680 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 <dt>SQLITE_CONFI
1d690 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e G_SQLLOG.** <dd>
1d6a0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f This option is o
1d6b0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 nly available if
1d6c0 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 sqlite is compi
1d6d0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 led with the.**
1d6e0 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 [SQLITE_ENABLE_S
1d6f0 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 QLLOG] pre-proce
1d700 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e ssor macro defin
1d710 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 ed. The first ar
1d720 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a gument should.**
1d730 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f be a pointer to
1d740 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 a function of t
1d750 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 ype void(*)(void
1d760 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 *,sqlite3*,const
1d770 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a char*, int)..**
1d780 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 The second shou
1d790 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 ld be of type (v
1d7a0 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 oid*). The callb
1d7b0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 ack is invoked b
1d7c0 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a y the library.**
1d7d0 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 in three separa
1d7e0 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 te circumstances
1d7f0 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 , identified by
1d800 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 the value passed
1d810 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 as the.** fourt
1d820 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 h parameter. If
1d830 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
1d840 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 eter is 0, then
1d850 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e the database con
1d860 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 nection.** passe
1d870 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 d as the second
1d880 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 argument has jus
1d890 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 t been opened. T
1d8a0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e he third argumen
1d8b0 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 t.** points to a
1d8c0 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 buffer containi
1d8d0 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 ng the name of t
1d8e0 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 he main database
1d8f0 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a file. If the.**
1d900 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 fourth paramete
1d910 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 r is 1, then the
1d920 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
1d930 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 hat the third pa
1d940 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 rameter.** point
1d950 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 s to has just be
1d960 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c en executed. Or,
1d970 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 if the fourth p
1d980 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 arameter is 2, t
1d990 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 hen.** the conne
1d9a0 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 ction being pass
1d9b0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
1d9c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 parameter is be
1d9d0 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a ing closed. The.
1d9e0 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 ** third paramet
1d9f0 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c er is passed NUL
1da00 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 L In this case.
1da10 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 An example of u
1da20 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e sing this.** con
1da30 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f figuration optio
1da40 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e n can be seen in
1da50 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f the "test_sqllo
1da60 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 g.c" source file
1da70 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e in.** the canon
1da80 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 ical SQLite sour
1da90 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a ce tree.</dd>.**
1daa0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e .** [[SQLITE_CON
1dab0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a FIG_MMAP_SIZE]].
1dac0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
1dad0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a NFIG_MMAP_SIZE.*
1dae0 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f * <dd>^SQLITE_CO
1daf0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 NFIG_MMAP_SIZE t
1db00 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 akes two 64-bit
1db10 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 integer (sqlite3
1db20 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a _int64) values.*
1db30 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 * that are the d
1db40 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 efault mmap size
1db50 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 limit (the defa
1db60 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a ult setting for.
1db70 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f ** [PRAGMA mmap_
1db80 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d size]) and the m
1db90 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d aximum allowed m
1dba0 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a map size limit..
1dbb0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 ** ^The default
1dbc0 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f setting can be o
1dbd0 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 verridden by eac
1dbe0 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 h database conne
1dbf0 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 ction using.** e
1dc00 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d ither the [PRAGM
1dc10 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d A mmap_size] com
1dc20 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e mand, or by usin
1dc30 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 g the.** [SQLITE
1dc40 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 _FCNTL_MMAP_SIZE
1dc50 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 ] file control.
1dc60 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 ^(The maximum a
1dc70 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 llowed mmap size
1dc80 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 .** will be sile
1dc90 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 ntly truncated i
1dca0 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 f necessary so t
1dcb0 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 hat it does not
1dcc0 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f exceed the.** co
1dcd0 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d mpile-time maxim
1dce0 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 um mmap size set
1dcf0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 by the.** [SQLI
1dd00 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 TE_MAX_MMAP_SIZE
1dd10 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
1dd20 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 ption.)^.** ^If
1dd30 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 either argument
1dd40 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 to this option i
1dd50 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e s negative, then
1dd60 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 that argument i
1dd70 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 s.** changed to
1dd80 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 its compile-time
1dd90 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 default..**.**
1dda0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f [[SQLITE_CONFIG_
1ddb0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d WIN32_HEAPSIZE]]
1ddc0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 .** <dt>SQLITE_C
1ddd0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 ONFIG_WIN32_HEAP
1dde0 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 SIZE.** <dd>^The
1ddf0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 SQLITE_CONFIG_W
1de00 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 IN32_HEAPSIZE op
1de10 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 tion is only ava
1de20 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 ilable if SQLite
1de30 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 is.** compiled
1de40 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 for Windows with
1de50 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e the [SQLITE_WIN
1de60 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 32_MALLOC] pre-p
1de70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a rocessor macro.*
1de80 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 * defined. ^SQLI
1de90 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f TE_CONFIG_WIN32_
1dea0 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 HEAPSIZE takes a
1deb0 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 32-bit unsigned
1dec0 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a integer value.*
1ded0 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 * that specifies
1dee0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a the maximum siz
1def0 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 e of the created
1df00 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 heap..**.** [[S
1df10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 QLITE_CONFIG_PCA
1df20 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c CHE_HDRSZ]].** <
1df30 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 dt>SQLITE_CONFIG
1df40 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a _PCACHE_HDRSZ.**
1df50 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 <dd>^The SQLITE
1df60 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 _CONFIG_PCACHE_H
1df70 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 DRSZ option take
1df80 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d s a single param
1df90 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 eter which.** is
1dfa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e a pointer to an
1dfb0 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 integer and wri
1dfc0 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e tes into that in
1dfd0 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 teger the number
1dfe0 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 of extra.** byt
1dff0 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 es per page requ
1e000 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 ired for each pa
1e010 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f ge in [SQLITE_CO
1e020 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e NFIG_PAGECACHE].
1e030 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f .** The amount o
1e040 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 f extra space re
1e050 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 quired can chang
1e060 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 e depending on t
1e070 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 he compiler,.**
1e080 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c target platform,
1e090 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 and SQLite vers
1e0a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c ion..**.** [[SQL
1e0b0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a ITE_CONFIG_PMASZ
1e0c0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 ]].** <dt>SQLITE
1e0d0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a _CONFIG_PMASZ.**
1e0e0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 <dd>^The SQLITE
1e0f0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 _CONFIG_PMASZ op
1e100 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e tion takes a sin
1e110 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 gle parameter wh
1e120 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 ich.** is an uns
1e130 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e igned integer an
1e140 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 d sets the "Mini
1e150 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f mum PMA Size" fo
1e160 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 r the multithrea
1e170 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f ded.** sorter to
1e180 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 that integer.
1e190 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 The default mini
1e1a0 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 mum PMA Size is
1e1b0 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 set by the.** [S
1e1c0 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 QLITE_SORTER_PMA
1e1d0 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 SZ] compile-time
1e1e0 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 option. New th
1e1f0 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 reads are launch
1e200 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 ed.** to help wi
1e210 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f th sort operatio
1e220 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 ns when multithr
1e230 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a eaded sorting.**
1e240 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 is enabled (usi
1e250 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 ng the [PRAGMA t
1e260 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 hreads] command)
1e270 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 and the amount
1e280 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f of content.** to
1e290 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 be sorted excee
1e2a0 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 ds the page size
1e2b0 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d times the minim
1e2c0 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 um of the.** [PR
1e2d0 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d AGMA cache_size]
1e2e0 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 setting and thi
1e2f0 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b s value..**.** [
1e300 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 [SQLITE_CONFIG_S
1e310 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a TMTJRNL_SPILL]].
1e320 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f ** <dt>SQLITE_CO
1e330 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 NFIG_STMTJRNL_SP
1e340 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 ILL.** <dd>^The
1e350 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 SQLITE_CONFIG_ST
1e360 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 MTJRNL_SPILL opt
1e370 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 ion takes a sing
1e380 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 le parameter whi
1e390 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 ch.** becomes th
1e3a0 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 e [statement jou
1e3b0 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 rnal] spill-to-d
1e3c0 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 isk threshold.
1e3d0 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a .** [Statement j
1e3e0 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c ournals] are hel
1e3f0 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 d in memory unti
1e400 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e l their size (in
1e410 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 bytes).** excee
1e420 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c ds this threshol
1e430 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e d, at which poin
1e440 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74 t they are writt
1e450 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f en to disk..** O
1e460 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f r if the thresho
1e470 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d ld is -1, statem
1e480 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 ent journals are
1e490 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 always held.**
1e4a0 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d exclusively in m
1e4b0 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 emory..** Since
1e4c0 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a many statement j
1e4d0 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 ournals never be
1e4e0 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 come large, sett
1e4f0 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a ing the spill.**
1e500 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 threshold to a
1e510 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 value such as 64
1e520 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 KiB can greatly
1e530 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e reduce the amoun
1e540 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 t of.** I/O requ
1e550 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 ired to support
1e560 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 statement rollba
1e570 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 ck..** The defau
1e580 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 lt value for thi
1e590 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e s setting is con
1e5a0 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a trolled by the.*
1e5b0 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 * [SQLITE_STMTJR
1e5c0 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c NL_SPILL] compil
1e5d0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a e-time option..*
1e5e0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 * </dl>.*/.#defi
1e5f0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 ne SQLITE_CONFIG
1e600 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 _SINGLETHREAD 1
1e610 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 /* nil */.#def
1e620 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
1e630 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 G_MULTITHREAD
1e640 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 2 /* nil */.#de
1e650 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
1e660 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 IG_SERIALIZED
1e670 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 3 /* nil */.#d
1e680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
1e690 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 FIG_MALLOC
1e6a0 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 4 /* sqlite3_
1e6b0 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a mem_methods* */.
1e6c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1e6d0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 ONFIG_GETMALLOC
1e6e0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 5 /* sqlite
1e6f0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 3_mem_methods* *
1e700 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1e710 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 _CONFIG_SCRATCH
1e720 20 20 20 20 20 20 36 20 20 2f 2a 20 4e 6f 20 6c 6 /* No l
1e730 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 onger used */.#d
1e740 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e efine SQLITE_CON
1e750 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 FIG_PAGECACHE
1e760 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 7 /* void*, i
1e770 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a nt sz, int N */.
1e780 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1e790 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 ONFIG_HEAP
1e7a0 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 8 /* void*,
1e7b0 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 int nByte, int
1e7c0 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 min */.#define S
1e7d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d QLITE_CONFIG_MEM
1e7e0 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a STATUS 9 /*
1e7f0 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 boolean */.#def
1e800 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
1e810 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 G_MUTEX 1
1e820 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 0 /* sqlite3_mu
1e830 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a tex_methods* */.
1e840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 #define SQLITE_C
1e850 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 ONFIG_GETMUTEX
1e860 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 11 /* sqlite
1e870 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 3_mutex_methods*
1e880 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c */./* previousl
1e890 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f y SQLITE_CONFIG_
1e8a0 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 CHUNKALLOC 12 wh
1e8b0 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 ich is now unuse
1e8c0 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 d. */ .#define S
1e8d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f QLITE_CONFIG_LOO
1e8e0 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a KASIDE 13 /*
1e8f0 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 int int */.#def
1e900 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
1e910 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31 G_PCACHE 1
1e920 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 4 /* no-op */.#
1e930 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f define SQLITE_CO
1e940 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 NFIG_GETPCACHE
1e950 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 15 /* no-op *
1e960 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1e970 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 _CONFIG_LOG
1e980 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 16 /* xFun
1e990 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 c, void* */.#def
1e9a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 ine SQLITE_CONFI
1e9b0 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31 G_URI 1
1e9c0 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 7 /* int */.#de
1e9d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
1e9e0 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 IG_PCACHE2
1e9f0 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 18 /* sqlite3_p
1ea00 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 cache_methods2*
1ea10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
1ea20 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 E_CONFIG_GETPCAC
1ea30 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c HE2 19 /* sql
1ea40 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 ite3_pcache_meth
1ea50 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 ods2* */.#define
1ea60 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 SQLITE_CONFIG_C
1ea70 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 OVERING_INDEX_SC
1ea80 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f AN 20 /* int */
1ea90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
1eaa0 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 CONFIG_SQLLOG
1eab0 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 21 /* xSqll
1eac0 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 og, void* */.#de
1ead0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 fine SQLITE_CONF
1eae0 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 IG_MMAP_SIZE
1eaf0 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 22 /* sqlite3_i
1eb00 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e nt64, sqlite3_in
1eb10 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 t64 */.#define S
1eb20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e QLITE_CONFIG_WIN
1eb30 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 32_HEAPSIZE
1eb40 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 23 /* int nByt
1eb50 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c e */.#define SQL
1eb60 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 ITE_CONFIG_PCACH
1eb70 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 E_HDRSZ 2
1eb80 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 4 /* int *psz *
1eb90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
1eba0 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 _CONFIG_PMASZ
1ebb0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 25
1ebc0 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 /* unsigned int
1ebd0 73 7a 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 szPma */.#define
1ebe0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 SQLITE_CONFIG_S
1ebf0 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 TMTJRNL_SPILL
1ec00 20 20 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 26 /* int nB
1ec10 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 yte */.#define S
1ec20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 4d 41 QLITE_CONFIG_SMA
1ec30 4c 4c 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 LL_MALLOC
1ec40 20 32 37 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 27 /* boolean
1ec50 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 */../*.** CAPI3R
1ec60 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e EF: Database Con
1ec70 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 nection Configur
1ec80 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a ation Options.**
1ec90 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 .** These consta
1eca0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 nts are the avai
1ecb0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f lable integer co
1ecc0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 nfiguration opti
1ecd0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 ons that.** can
1ece0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 be passed as the
1ecf0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 second argument
1ed00 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 to the [sqlite3
1ed10 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e _db_config()] in
1ed20 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e terface..**.** N
1ed30 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e ew configuration
1ed40 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 options may be
1ed50 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 added in future
1ed60 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 releases of SQLi
1ed70 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 te..** Existing
1ed80 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 configuration op
1ed90 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 tions might be d
1eda0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 iscontinued. Ap
1edb0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 plications.** sh
1edc0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 ould check the r
1edd0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 eturn code from
1ede0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 [sqlite3_db_conf
1edf0 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 ig()] to make su
1ee00 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 re that.** the c
1ee10 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 all worked. ^Th
1ee20 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f e [sqlite3_db_co
1ee30 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 nfig()] interfac
1ee40 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a e will return a.
1ee50 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 ** non-zero [err
1ee60 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 or code] if a di
1ee70 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e scontinued or un
1ee80 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 supported config
1ee90 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a uration option.*
1eea0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a * is invoked..**
1eeb0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e .** <dl>.** <dt>
1eec0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
1eed0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a LOOKASIDE</dt>.*
1eee0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 * <dd> ^This opt
1eef0 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 ion takes three
1ef00 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d additional argum
1ef10 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d ents that determ
1ef20 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f ine the .** [loo
1ef30 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c kaside memory al
1ef40 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 locator] configu
1ef50 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b ration for the [
1ef60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
1ef70 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 ion]..** ^The fi
1ef80 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 rst argument (th
1ef90 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 e third paramete
1efa0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 r to [sqlite3_db
1efb0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a _config()] is a.
1efc0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 ** pointer to a
1efd0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f memory buffer to
1efe0 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 use for lookasi
1eff0 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 de memory..** ^T
1f000 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
1f010 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 t after the SQLI
1f020 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b TE_DBCONFIG_LOOK
1f030 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 ASIDE verb.** ma
1f040 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 y be NULL in whi
1f050 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 ch case SQLite w
1f060 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 ill allocate the
1f070 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 .** lookaside bu
1f080 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e ffer itself usin
1f090 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f g [sqlite3_mallo
1f0a0 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e c()]. ^The secon
1f0b0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 d argument is th
1f0c0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 e.** size of eac
1f0d0 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 h lookaside buff
1f0e0 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 er slot. ^The t
1f0f0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 hird argument is
1f100 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a the number of.*
1f110 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 * slots. The si
1f120 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 ze of the buffer
1f130 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 in the first ar
1f140 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 gument must be g
1f150 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f reater than.** o
1f160 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 r equal to the p
1f170 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 roduct of the se
1f180 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 cond and third a
1f190 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 rguments. The b
1f1a0 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 uffer.** must be
1f1b0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 aligned to an 8
1f1c0 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 -byte boundary.
1f1d0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 ^If the second
1f1e0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 argument to.** S
1f1f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c QLITE_DBCONFIG_L
1f200 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 OOKASIDE is not
1f210 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c a multiple of 8,
1f220 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c it is internall
1f230 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 y.** rounded dow
1f240 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d n to the next sm
1f250 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f aller multiple o
1f260 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b f 8. ^(The look
1f270 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 aside memory.**
1f280 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f configuration fo
1f290 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e r a database con
1f2a0 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 nection can only
1f2b0 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e be changed when
1f2c0 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 that.** connect
1f2d0 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 ion is not curre
1f2e0 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 ntly using looka
1f2f0 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 side memory, or
1f300 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a in other words.*
1f310 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 * when the "curr
1f320 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 ent value" retur
1f330 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 ned by.** [sqlit
1f340 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c e3_db_status](D,
1f350 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c [SQLITE_CONFIG_L
1f360 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 OOKASIDE],...) i
1f370 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 s zero..** Any a
1f380 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 ttempt to change
1f390 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d the lookaside m
1f3a0 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 emory configurat
1f3b0 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 ion when lookasi
1f3c0 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 de.** memory is
1f3d0 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 in use leaves th
1f3e0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 e configuration
1f3f0 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 unchanged and re
1f400 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 turns .** [SQLIT
1f410 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a E_BUSY].)^</dd>.
1f420 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 **.** <dt>SQLITE
1f430 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 _DBCONFIG_ENABLE
1f440 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 _FKEY</dt>.** <d
1f450 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 d> ^This option
1f460 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c is used to enabl
1f470 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 e or disable the
1f480 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a enforcement of.
1f490 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 ** [foreign key
1f4a0 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 constraints]. T
1f4b0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 here should be t
1f4c0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 wo additional ar
1f4d0 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 guments..** The
1f4e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 first argument i
1f4f0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 s an integer whi
1f500 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 ch is 0 to disab
1f510 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e le FK enforcemen
1f520 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 t,.** positive t
1f530 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f o enable FK enfo
1f540 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 rcement or negat
1f550 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 ive to leave FK
1f560 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 enforcement.** u
1f570 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 nchanged. The s
1f580 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1f590 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
1f5a0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 an integer into
1f5b0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 which.** is writ
1f5c0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e ten 0 or 1 to in
1f5d0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 dicate whether F
1f5e0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 K enforcement is
1f5f0 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f off or on.** fo
1f600 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c llowing this cal
1f610 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 l. The second p
1f620 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 arameter may be
1f630 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 a NULL pointer,
1f640 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 in.** which case
1f650 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d the FK enforcem
1f660 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e ent setting is n
1f670 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b ot reported back
1f680 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 . </dd>.**.** <d
1f690 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
1f6a0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 G_ENABLE_TRIGGER
1f6b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 </dt>.** <dd> ^T
1f6c0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 his option is us
1f6d0 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 ed to enable or
1f6e0 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 disable [CREATE
1f6f0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 TRIGGER | trigge
1f700 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 rs]..** There sh
1f710 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 ould be two addi
1f720 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 tional arguments
1f730 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 ..** The first a
1f740 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e rgument is an in
1f750 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 teger which is 0
1f760 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 to disable trig
1f770 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 gers,.** positiv
1f780 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 e to enable trig
1f790 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 gers or negative
1f7a0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 to leave the se
1f7b0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e tting unchanged.
1f7c0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 .** The second p
1f7d0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f arameter is a po
1f7e0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 inter to an inte
1f7f0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a ger into which.*
1f800 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f * is written 0 o
1f810 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 r 1 to indicate
1f820 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 whether triggers
1f830 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 are disabled or
1f840 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c enabled.** foll
1f850 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e owing this call.
1f860 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 The second par
1f870 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 ameter may be a
1f880 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e NULL pointer, in
1f890 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 .** which case t
1f8a0 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 he trigger setti
1f8b0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 ng is not report
1f8c0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a ed back. </dd>.*
1f8d0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
1f8e0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f DBCONFIG_ENABLE_
1f8f0 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f FTS3_TOKENIZER</
1f900 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 dt>.** <dd> ^Thi
1f910 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 s option is used
1f920 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 to enable or di
1f930 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 sable the two-ar
1f940 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f gument.** versio
1f950 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74 n of the [fts3_t
1f960 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 okenizer()] func
1f970 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61 tion which is pa
1f980 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 rt of the.** [FT
1f990 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 S3] full-text se
1f9a0 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65 arch engine exte
1f9b0 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 nsion..** There
1f9c0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 should be two ad
1f9d0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
1f9e0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 ts..** The first
1f9f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 argument is an
1fa00 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 integer which is
1fa10 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74 0 to disable ft
1fa20 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f s3_tokenizer() o
1fa30 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f r.** positive to
1fa40 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b enable fts3_tok
1fa50 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 enizer() or nega
1fa60 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 tive to leave th
1fa70 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 e setting.** unc
1fa80 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 hanged..** The s
1fa90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
1faa0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
1fab0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 an integer into
1fac0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 which.** is writ
1fad0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e ten 0 or 1 to in
1fae0 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 66 dicate whether f
1faf0 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 ts3_tokenizer is
1fb00 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 disabled or ena
1fb10 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e bled.** followin
1fb20 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 g this call. Th
1fb30 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 e second paramet
1fb40 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c er may be a NULL
1fb50 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 pointer, in.**
1fb60 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e which case the n
1fb70 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f ew setting is no
1fb80 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e t reported back.
1fb90 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 </dd>.**.** <dt
1fba0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 >SQLITE_DBCONFIG
1fbb0 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 _ENABLE_LOAD_EXT
1fbc0 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c ENSION</dt>.** <
1fbd0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e dd> ^This option
1fbe0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 is used to enab
1fbf0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 le or disable th
1fc00 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f e [sqlite3_load_
1fc10 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 extension()].**
1fc20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70 65 interface indepe
1fc30 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b ndently of the [
1fc40 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 load_extension()
1fc50 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a ] SQL function..
1fc60 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
1fc70 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 enable_load_exte
1fc80 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 nsion()] API ena
1fc90 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 bles or disables
1fca0 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 both the.** C-A
1fcb0 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 PI [sqlite3_load
1fcc0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e _extension()] an
1fcd0 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 d the SQL functi
1fce0 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 on [load_extensi
1fcf0 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 on()]..** There
1fd00 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 should be two ad
1fd10 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e ditional argumen
1fd20 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 ts..** When the
1fd30 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 first argument t
1fd40 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 o this interface
1fd50 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 is 1, then only
1fd60 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a the C-API is.**
1fd70 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65 enabled and the
1fd80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 SQL function re
1fd90 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 mains disabled.
1fda0 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72 If the first ar
1fdb0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 gument to.** thi
1fdc0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 30 s interface is 0
1fdd0 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20 , then both the
1fde0 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53 51 C-API and the SQ
1fdf0 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 L function are d
1fe00 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 isabled..** If t
1fe10 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e he first argumen
1fe20 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f t is -1, then no
1fe30 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64 changes are mad
1fe40 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69 e to state of ei
1fe50 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 ther the.** C-AP
1fe60 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e I or the SQL fun
1fe70 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 ction..** The se
1fe80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 cond parameter i
1fe90 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
1fea0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 n integer into w
1feb0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 hich.** is writt
1fec0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 en 0 or 1 to ind
1fed0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 5b 73 icate whether [s
1fee0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 qlite3_load_exte
1fef0 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 nsion()] interfa
1ff00 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 ce.** is disable
1ff10 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c d or enabled fol
1ff20 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c lowing this call
1ff30 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 . The second pa
1ff40 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 rameter may.** b
1ff50 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 e a NULL pointer
1ff60 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 , in which case
1ff70 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20 the new setting
1ff80 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 is not reported
1ff90 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a back..** </dd>.*
1ffa0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f *.** <dt>SQLITE_
1ffb0 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e DBCONFIG_MAINDBN
1ffc0 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e AME</dt>.** <dd>
1ffd0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 ^This option is
1ffe0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 used to change
1fff0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 the name of the
20000 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65 0a "main" database.
20010 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68 65 ** schema. ^The
20020 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20 69 sole argument i
20030 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 s a pointer to a
20040 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20 73 constant UTF8 s
20050 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77 tring.** which w
20060 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 6e ill become the n
20070 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69 ew schema name i
20080 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e n place of "main
20090 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 ". ^SQLite.** d
200a0 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63 oes not make a c
200b0 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20 6d opy of the new m
200c0 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 ain schema name
200d0 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20 61 string, so the a
200e0 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 pplication.** mu
200f0 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 st ensure that t
20100 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 he argument pass
20110 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42 43 ed into this DBC
20120 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73 20 ONFIG option is
20130 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 unchanged.** unt
20140 69 6c 20 61 66 74 65 72 20 74 68 65 20 64 61 74 il after the dat
20150 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
20160 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 closes..** </dd
20170 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 >.**.** <dt>SQLI
20180 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 TE_DBCONFIG_NO_C
20190 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 KPT_ON_CLOSE</dt
201a0 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c >.** <dd> Usuall
201b0 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 y, when a databa
201c0 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69 se in wal mode i
201d0 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74 61 s closed or deta
201e0 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 ched from a .**
201f0 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2c database handle,
20200 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20 69 SQLite checks i
20210 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e f this will mean
20220 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65 20 that there are
20230 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 now no .** conne
20240 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f ctions at all to
20250 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 49 the database. I
20260 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d f so, it perform
20270 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a s a checkpoint .
20280 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65 66 ** operation bef
20290 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65 20 ore closing the
202a0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73 connection. This
202b0 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75 option may be u
202c0 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 sed to.** overri
202d0 64 65 20 74 68 69 73 20 62 65 68 61 76 69 6f 75 de this behaviou
202e0 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72 r. The first par
202f0 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f ameter passed to
20300 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a this operation.
20310 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ** is an integer
20320 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 - non-zero to d
20330 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e isable checkpoin
20340 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 ts-on-close, or
20350 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66 zero (the.** def
20360 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65 20 ault) to enable
20370 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e 64 them. The second
20380 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 parameter is a
20390 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e pointer to an in
203a0 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 teger.** into wh
203b0 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 30 ich is written 0
203c0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 or 1 to indicat
203d0 65 20 77 68 65 74 68 65 72 20 63 68 65 63 6b 70 e whether checkp
203e0 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a oints-on-close.*
203f0 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69 73 61 * have been disa
20400 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65 79 bled - 0 if they
20410 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c 65 are not disable
20420 64 2c 20 31 20 69 66 20 74 68 65 79 20 61 72 65 d, 1 if they are
20430 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c 64 ..** </dd>.** <d
20440 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 t>SQLITE_DBCONFI
20450 47 5f 45 4e 41 42 4c 45 5f 51 50 53 47 3c 2f 64 G_ENABLE_QPSG</d
20460 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 t>.** <dd>^(The
20470 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
20480 45 4e 41 42 4c 45 5f 51 50 53 47 20 6f 70 74 69 ENABLE_QPSG opti
20490 6f 6e 20 61 63 74 69 76 61 74 65 73 20 6f 72 20 on activates or
204a0 64 65 61 63 74 69 76 61 74 65 73 0a 2a 2a 20 74 deactivates.** t
204b0 68 65 20 5b 71 75 65 72 79 20 70 6c 61 6e 6e 65 he [query planne
204c0 72 20 73 74 61 62 69 6c 69 74 79 20 67 75 61 72 r stability guar
204d0 61 6e 74 65 65 5d 20 28 51 50 53 47 29 2e 20 20 antee] (QPSG).
204e0 57 68 65 6e 20 74 68 65 20 51 50 53 47 20 69 73 When the QPSG is
204f0 20 61 63 74 69 76 65 2c 0a 2a 2a 20 61 20 73 69 active,.** a si
20500 6e 67 6c 65 20 53 51 4c 20 71 75 65 72 79 20 73 ngle SQL query s
20510 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 61 6c tatement will al
20520 77 61 79 73 20 75 73 65 20 74 68 65 20 73 61 6d ways use the sam
20530 65 20 61 6c 67 6f 72 69 74 68 6d 20 72 65 67 61 e algorithm rega
20540 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 76 61 6c rdless.** of val
20550 75 65 73 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 ues of [bound pa
20560 72 61 6d 65 74 65 72 73 5d 2e 29 5e 20 54 68 65 rameters].)^ The
20570 20 51 50 53 47 20 64 69 73 61 62 6c 65 73 20 73 QPSG disables s
20580 6f 6d 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 ome query optimi
20590 7a 61 74 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 zations.** that
205a0 6c 6f 6f 6b 20 61 74 20 74 68 65 20 76 61 6c 75 look at the valu
205b0 65 73 20 6f 66 20 62 6f 75 6e 64 20 70 61 72 61 es of bound para
205c0 6d 65 74 65 72 73 2c 20 77 68 69 63 68 20 63 61 meters, which ca
205d0 6e 20 6d 61 6b 65 20 73 6f 6d 65 20 71 75 65 72 n make some quer
205e0 69 65 73 0a 2a 2a 20 73 6c 6f 77 65 72 2e 20 20 ies.** slower.
205f0 42 75 74 20 74 68 65 20 51 50 53 47 20 68 61 73 But the QPSG has
20600 20 74 68 65 20 61 64 76 61 6e 74 61 67 65 20 6f the advantage o
20610 66 20 6d 6f 72 65 20 70 72 65 64 69 63 74 61 62 f more predictab
20620 6c 65 20 62 65 68 61 76 69 6f 72 2e 20 20 57 69 le behavior. Wi
20630 74 68 0a 2a 2a 20 74 68 65 20 51 50 53 47 20 61 th.** the QPSG a
20640 63 74 69 76 65 2c 20 53 51 4c 69 74 65 20 77 69 ctive, SQLite wi
20650 6c 6c 20 61 6c 77 61 79 73 20 75 73 65 20 74 68 ll always use th
20660 65 20 73 61 6d 65 20 71 75 65 72 79 20 70 6c 61 e same query pla
20670 6e 20 69 6e 20 74 68 65 20 66 69 65 6c 64 20 61 n in the field a
20680 73 0a 2a 2a 20 77 61 73 20 75 73 65 64 20 64 75 s.** was used du
20690 72 69 6e 67 20 74 65 73 74 69 6e 67 20 69 6e 20 ring testing in
206a0 74 68 65 20 6c 61 62 2e 0a 2a 2a 20 3c 2f 64 64 the lab..** </dd
206b0 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f >.** <dt>SQLITE_
206c0 44 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 DBCONFIG_TRIGGER
206d0 5f 45 51 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 _EQP</dt>.** <dd
206e0 3e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 > By default, th
206f0 65 20 6f 75 74 70 75 74 20 6f 66 20 45 58 50 4c e output of EXPL
20700 41 49 4e 20 51 55 45 52 59 20 50 4c 41 4e 20 63 AIN QUERY PLAN c
20710 6f 6d 6d 61 6e 64 73 20 64 6f 65 73 20 6e 6f 74 ommands does not
20720 20 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 6f 75 74 .** include out
20730 70 75 74 20 66 6f 72 20 61 6e 79 20 6f 70 65 72 put for any oper
20740 61 74 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 ations performed
20750 20 62 79 20 74 72 69 67 67 65 72 20 70 72 6f 67 by trigger prog
20760 72 61 6d 73 2e 20 54 68 69 73 0a 2a 2a 20 6f 70 rams. This.** op
20770 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 tion is used to
20780 73 65 74 20 6f 72 20 63 6c 65 61 72 20 28 74 68 set or clear (th
20790 65 20 64 65 66 61 75 6c 74 29 20 61 20 66 6c 61 e default) a fla
207a0 67 20 74 68 61 74 20 67 6f 76 65 72 6e 73 20 74 g that governs t
207b0 68 69 73 0a 2a 2a 20 62 65 68 61 76 69 6f 72 2e his.** behavior.
207c0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d The first param
207d0 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 eter passed to t
207e0 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 his operation is
207f0 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 0a 2a 2a an integer -.**
20800 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 65 6e 61 non-zero to ena
20810 62 6c 65 20 6f 75 74 70 75 74 20 66 6f 72 20 74 ble output for t
20820 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73 2c rigger programs,
20830 20 6f 72 20 7a 65 72 6f 20 74 6f 20 64 69 73 61 or zero to disa
20840 62 6c 65 20 69 74 2e 0a 2a 2a 20 54 68 65 20 73 ble it..** The s
20850 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 econd parameter
20860 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 is a pointer to
20870 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 an integer into
20880 77 68 69 63 68 20 69 73 20 77 72 69 74 74 65 6e which is written
20890 20 0a 2a 2a 20 30 20 6f 72 20 31 20 74 6f 20 69 .** 0 or 1 to i
208a0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 ndicate whether
208b0 6f 75 74 70 75 74 2d 66 6f 72 2d 74 72 69 67 67 output-for-trigg
208c0 65 72 73 20 68 61 73 20 62 65 65 6e 20 64 69 73 ers has been dis
208d0 61 62 6c 65 64 20 2d 20 30 20 69 66 20 0a 2a 2a abled - 0 if .**
208e0 20 69 74 20 69 73 20 6e 6f 74 20 64 69 73 61 62 it is not disab
208f0 6c 65 64 2c 20 31 20 69 66 20 69 74 20 69 73 2e led, 1 if it is.
20900 20 20 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 20 3c .** </dd>.** <
20910 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 /dl>.*/.#define
20920 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
20930 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 MAINDBNAME
20940 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 1000 /* co
20950 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 nst char* */.#de
20960 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f fine SQLITE_DBCO
20970 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 NFIG_LOOKASIDE
20980 20 20 20 20 20 20 20 20 20 20 20 31 30 30 31 20 1001
20990 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 /* void* int int
209a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
209b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 TE_DBCONFIG_ENAB
209c0 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 LE_FKEY
209d0 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 1002 /* int in
209e0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 t* */.#define SQ
209f0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e LITE_DBCONFIG_EN
20a00 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 ABLE_TRIGGER
20a10 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 1003 /* int
20a20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 int* */.#define
20a30 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f SQLITE_DBCONFIG_
20a40 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 ENABLE_FTS3_TOKE
20a50 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e NIZER 1004 /* in
20a60 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e t int* */.#defin
20a70 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 e SQLITE_DBCONFI
20a80 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 G_ENABLE_LOAD_EX
20a90 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 TENSION 1005 /*
20aa0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 int int* */.#def
20ab0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e ine SQLITE_DBCON
20ac0 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 FIG_NO_CKPT_ON_C
20ad0 4c 4f 53 45 20 20 20 20 20 20 31 30 30 36 20 2f LOSE 1006 /
20ae0 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 * int int* */.#d
20af0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 efine SQLITE_DBC
20b00 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 51 50 53 ONFIG_ENABLE_QPS
20b10 47 20 20 20 20 20 20 20 20 20 20 20 31 30 30 37 G 1007
20b20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a /* int int* */.
20b30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
20b40 42 43 4f 4e 46 49 47 5f 54 52 49 47 47 45 52 5f BCONFIG_TRIGGER_
20b50 45 51 50 20 20 20 20 20 20 20 20 20 20 20 31 30 EQP 10
20b60 30 38 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 08 /* int int* *
20b70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
20b80 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 58 20 20 20 _DBCONFIG_MAX
20b90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
20ba0 31 30 30 38 20 2f 2a 20 4c 61 72 67 65 73 74 20 1008 /* Largest
20bb0 44 42 43 4f 4e 46 49 47 20 2a 2f 0a 0a 2f 2a 0a DBCONFIG */../*.
20bc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 ** CAPI3REF: Ena
20bd0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 ble Or Disable E
20be0 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 xtended Result C
20bf0 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 odes.** METHOD:
20c00 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
20c10 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e he sqlite3_exten
20c20 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 ded_result_codes
20c30 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c () routine enabl
20c40 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 es or disables t
20c50 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 he.** [extended
20c60 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 result codes] fe
20c70 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e ature of SQLite.
20c80 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 ^The extended r
20c90 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 esult.** codes a
20ca0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 re disabled by d
20cb0 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f efault for histo
20cc0 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c rical compatibil
20cd0 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ity..*/.SQLITE_A
20ce0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 PI int sqlite3_e
20cf0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 xtended_result_c
20d00 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 odes(sqlite3*, i
20d10 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a nt onoff);../*.*
20d20 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 * CAPI3REF: Last
20d30 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a Insert Rowid.**
20d40 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
20d50 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 .**.** ^Each ent
20d60 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 ry in most SQLit
20d70 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 e tables (except
20d80 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f for [WITHOUT RO
20d90 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 WID] tables).**
20da0 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d has a unique 64-
20db0 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e bit signed.** in
20dc0 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 teger key called
20dd0 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 the [ROWID | "r
20de0 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 owid"]. ^The row
20df0 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 id is always ava
20e00 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 ilable.** as an
20e10 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d undeclared colum
20e20 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f n named ROWID, O
20e30 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 ID, or _ROWID_ a
20e40 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a s long as those.
20e50 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 ** names are not
20e60 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 also used by ex
20e70 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 plicitly declare
20e80 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a d columns. ^If.*
20e90 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 * the table has
20ea0 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 a column of type
20eb0 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 [INTEGER PRIMAR
20ec0 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 Y KEY] then that
20ed0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e column.** is an
20ee0 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 other alias for
20ef0 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a the rowid..**.**
20f00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 ^The sqlite3_la
20f10 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
20f20 44 29 20 69 6e 74 65 72 66 61 63 65 20 75 73 75 D) interface usu
20f30 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 ally returns the
20f40 20 5b 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74 [rowid] of.** t
20f50 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 he most recent s
20f60 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 uccessful [INSER
20f70 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 T] into a rowid
20f80 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 table or [virtua
20f90 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 l table].** on d
20fa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
20fb0 6f 6e 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69 on D. ^Inserts i
20fc0 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 nto [WITHOUT ROW
20fd0 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e ID] tables are n
20fe0 6f 74 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20 ot.** recorded.
20ff0 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 ^If no successfu
21000 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f l [INSERT]s into
21010 20 72 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61 rowid tables ha
21020 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 ve ever occurred
21030 20 0a 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61 .** on the data
21040 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
21050 44 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f D, then sqlite3_
21060 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 last_insert_rowi
21070 64 28 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a d(D) returns .**
21080 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 zero..**.** As
21090 77 65 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65 well as being se
210a0 74 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 t automatically
210b0 61 73 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65 as rows are inse
210c0 72 74 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61 rted into databa
210d0 73 65 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68 se.** tables, th
210e0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
210f0 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f by this functio
21100 6e 20 6d 61 79 20 62 65 20 73 65 74 20 65 78 70 n may be set exp
21110 6c 69 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73 licitly by.** [s
21120 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f qlite3_set_last_
21130 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a insert_rowid()].
21140 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75 **.** Some virtu
21150 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 al table impleme
21160 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53 ntations may INS
21170 45 52 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f ERT rows into ro
21180 77 69 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a wid tables as.**
21190 20 70 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74 part of committ
211a0 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f ing a transactio
211b0 6e 20 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68 n (e.g. to flush
211c0 20 64 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65 data accumulate
211d0 64 20 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74 d in memory.** t
211e0 6f 20 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73 o disk). In this
211f0 20 63 61 73 65 20 73 75 62 73 65 71 75 65 6e 74 case subsequent
21200 20 63 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66 calls to this f
21210 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74 unction return t
21220 68 65 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f he rowid.** asso
21230 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 73 ciated with thes
21240 65 20 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52 e internal INSER
21250 54 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68 T operations, wh
21260 69 63 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a ich leads to .**
21270 20 75 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73 unintuitive res
21280 75 6c 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61 ults. Virtual ta
21290 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 ble implementati
212a0 6f 6e 73 20 74 68 61 74 20 64 6f 20 77 72 69 74 ons that do writ
212b0 65 20 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61 e to rowid.** ta
212c0 62 6c 65 73 20 69 6e 20 74 68 69 73 20 77 61 79 bles in this way
212d0 20 63 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20 can avoid this
212e0 70 72 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f problem by resto
212f0 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 ring the origina
21300 6c 20 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75 l .** rowid valu
21310 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 e using [sqlite3
21320 5f 73 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 _set_last_insert
21330 5f 72 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65 _rowid()] before
21340 20 72 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63 returning .** c
21350 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73 ontrol to the us
21360 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 er..**.** ^(If a
21370 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 n [INSERT] occur
21380 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 s within a trigg
21390 65 72 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 er then this rou
213a0 74 69 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65 tine will .** re
213b0 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d turn the [rowid]
213c0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 of the inserted
213d0 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 row as long as
213e0 74 68 65 20 74 72 69 67 67 65 72 20 69 73 20 0a the trigger is .
213f0 2a 2a 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65 ** running. Once
21400 20 74 68 65 20 74 72 69 67 67 65 72 20 70 72 6f the trigger pro
21410 67 72 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76 gram ends, the v
21420 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a alue returned .*
21430 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e * by this routin
21440 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 e reverts to wha
21450 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 t it was before
21460 74 68 65 20 74 72 69 67 67 65 72 20 77 61 73 20 the trigger was
21470 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e fired.)^.**.** ^
21480 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 An [INSERT] that
21490 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 fails due to a
214a0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 constraint viola
214b0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a tion is not a.**
214c0 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 successful [INS
214d0 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f ERT] and does no
214e0 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c t change the val
214f0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 ue returned by t
21500 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 his.** routine.
21510 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 ^Thus INSERT OR
21520 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 FAIL, INSERT OR
21530 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 IGNORE, INSERT
21540 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 OR ROLLBACK,.**
21550 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 and INSERT OR AB
21560 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e ORT make no chan
21570 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 ges to the retur
21580 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a n value of this.
21590 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 ** routine when
215a0 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 their insertion
215b0 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 fails. ^(When I
215c0 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 NSERT OR REPLACE
215d0 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 .** encounters a
215e0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c constraint viol
215f0 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e ation, it does n
21600 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a ot fail. The.**
21610 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 INSERT continue
21620 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 s to completion
21630 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 after deleting r
21640 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a ows that caused.
21650 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e ** the constrain
21660 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 t problem so INS
21670 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 ERT OR REPLACE w
21680 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 ill always chang
21690 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 e.** the return
216a0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e value of this in
216b0 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a terface.)^.**.**
216c0 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 ^For the purpos
216d0 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 es of this routi
216e0 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 ne, an [INSERT]
216f0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f is considered to
21700 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 .** be successfu
21710 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 l even if it is
21720 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c subsequently rol
21730 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 led back..**.**
21740 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 This function is
21750 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 accessible to S
21760 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 QL statements vi
21770 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 a the.** [last_i
21780 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 nsert_rowid() SQ
21790 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a L function]..**.
217a0 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 ** If a separate
217b0 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 thread performs
217c0 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 a new [INSERT]
217d0 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 on the same.** d
217e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
217f0 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 on while the [sq
21800 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
21810 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 t_rowid()].** fu
21820 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e nction is runnin
21830 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 g and thus chang
21840 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 es the last inse
21850 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 rt [rowid],.** t
21860 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
21870 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
21880 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 e3_last_insert_r
21890 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e owid()] is.** un
218a0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 predictable and
218b0 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 might not equal
218c0 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f either the old o
218d0 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 r the new.** las
218e0 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d t insert [rowid]
218f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
21900 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 sqlite3_int64 sq
21910 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 lite3_last_inser
21920 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a t_rowid(sqlite3*
21930 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
21940 45 46 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 EF: Set the Last
21950 20 49 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 Insert Rowid va
21960 6c 75 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 lue..** METHOD:
21970 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 sqlite3.**.** Th
21980 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 e sqlite3_set_la
21990 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 st_insert_rowid(
219a0 44 2c 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c D, R) method all
219b0 6f 77 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 ows the applicat
219c0 69 6f 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 ion to.** set th
219d0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 e value returned
219e0 20 62 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 by calling sqli
219f0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f te3_last_insert_
21a00 72 6f 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a rowid(D) to R .*
21a10 2a 20 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 * without insert
21a20 69 6e 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 ing a row into t
21a30 68 65 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a he database..*/.
21a40 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 SQLITE_API void
21a50 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 sqlite3_set_last
21a60 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 _insert_rowid(sq
21a70 6c 69 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 lite3*,sqlite3_i
21a80 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 nt64);../*.** CA
21a90 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 PI3REF: Count Th
21aa0 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 e Number Of Rows
21ab0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 Modified.** MET
21ac0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a HOD: sqlite3.**.
21ad0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f ** ^This functio
21ae0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 n returns the nu
21af0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 mber of rows mod
21b00 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 ified, inserted
21b10 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 or.** deleted by
21b20 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 the most recent
21b30 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 ly completed INS
21b40 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 ERT, UPDATE or D
21b50 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 ELETE.** stateme
21b60 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 nt on the databa
21b70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 se connection sp
21b80 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f ecified by the o
21b90 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a nly parameter..*
21ba0 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 * ^Executing any
21bb0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 other type of S
21bc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 QL statement doe
21bd0 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 s not modify the
21be0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e value.** return
21bf0 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 ed by this funct
21c00 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 ion..**.** ^Only
21c10 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 changes made di
21c20 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e rectly by the IN
21c30 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 SERT, UPDATE or
21c40 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 DELETE statement
21c50 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 are.** consider
21c60 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 ed - auxiliary c
21c70 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 hanges caused by
21c80 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 [CREATE TRIGGER
21c90 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a | triggers], .*
21ca0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 * [foreign key a
21cb0 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c ctions] or [REPL
21cc0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 ACE] constraint
21cd0 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e resolution are n
21ce0 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a ot counted..** .
21cf0 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 ** Changes to a
21d00 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e view that are in
21d10 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a tercepted by .**
21d20 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 [INSTEAD OF tri
21d30 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f gger | INSTEAD O
21d40 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 F triggers] are
21d50 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 not counted. ^Th
21d60 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 e value .** retu
21d70 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f rned by sqlite3_
21d80 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 changes() immedi
21d90 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 ately after an I
21da0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 NSERT, UPDATE or
21db0 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 .** DELETE stat
21dc0 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 ement run on a v
21dd0 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 iew is always ze
21de0 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 ro. Only changes
21df0 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a made to real .*
21e00 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 * tables are cou
21e10 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e nted..**.** Thin
21e20 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 gs are more comp
21e30 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73 licated if the s
21e40 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 qlite3_changes()
21e50 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 function is.**
21e60 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 executed while a
21e70 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d trigger program
21e80 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 is running. Thi
21e90 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 s may happen if
21ea0 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 the.** program u
21eb0 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 ses the [changes
21ec0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d () SQL function]
21ed0 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 , or if some oth
21ee0 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 er callback.** f
21ef0 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 unction invokes
21f00 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 sqlite3_changes(
21f10 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 ) directly. Esse
21f20 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 ntially:.** .**
21f30 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e <ul>.** <li> ^
21f40 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 (Before entering
21f50 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 a trigger progr
21f60 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 am the value ret
21f70 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 urned by.**
21f80 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 sqlite3_chang
21f90 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 es() function is
21fa0 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 saved. After th
21fb0 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 e trigger progra
21fc0 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 m .** has
21fd0 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f finished, the o
21fe0 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 riginal value is
21ff0 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 restored.)^.**
22000 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 .** <li> ^(Wit
22010 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 hin a trigger pr
22020 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 ogram each INSER
22030 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 T, UPDATE and DE
22040 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 LETE .**
22050 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 statement sets t
22060 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 he value returne
22070 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 d by sqlite3_cha
22080 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 nges() .**
22090 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f upon completio
220a0 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 n as normal. Of
220b0 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c course, this val
220c0 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c ue will not incl
220d0 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 ude .** a
220e0 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f ny changes perfo
220f0 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 rmed by sub-trig
22100 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c gers, as the sql
22110 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a ite3_changes() .
22120 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 ** value
22130 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e will be saved an
22140 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 d restored after
22150 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 each sub-trigge
22160 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 r has run.)^.**
22170 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 </ul>.** .** ^Th
22180 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 is means that if
22190 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 the changes() S
221a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 QL function (or
221b0 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 similar) is used
221c0 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 .** by the first
221d0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 INSERT, UPDATE
221e0 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d or DELETE statem
221f0 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 ent within a tri
22200 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 gger, it .** ret
22210 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 urns the value a
22220 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 s set when the c
22230 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 alling statement
22240 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 began executing
22250 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 ..** ^If it is u
22260 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e sed by the secon
22270 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 d or subsequent
22280 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 such statement w
22290 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 ithin a trigger
222a0 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 .** program, the
222b0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 value returned
222c0 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d reflects the num
222d0 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 ber of rows modi
222e0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 fied by the .**
222f0 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c previous INSERT,
22300 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 UPDATE or DELET
22310 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 E statement with
22320 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 in the same trig
22330 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ger..**.** See a
22340 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 lso the [sqlite3
22350 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 _total_changes()
22360 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 ] interface, the
22370 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 .** [count_chang
22380 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 es pragma], and
22390 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 the [changes() S
223a0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a QL function]..**
223b0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 .** If a separat
223c0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 e thread makes c
223d0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 hanges on the sa
223e0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e me database conn
223f0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 ection.** while
22400 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 [sqlite3_changes
22410 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 ()] is running t
22420 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 hen the value re
22430 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 turned.** is unp
22440 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e redictable and n
22450 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a ot meaningful..*
22460 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
22470 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 sqlite3_changes
22480 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a (sqlite3*);../*.
22490 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 ** CAPI3REF: Tot
224a0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 al Number Of Row
224b0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 s Modified.** ME
224c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a THOD: sqlite3.**
224d0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 .** ^This functi
224e0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 on returns the t
224f0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 otal number of r
22500 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f ows inserted, mo
22510 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c dified or.** del
22520 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 eted by all [INS
22530 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f ERT], [UPDATE] o
22540 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 r [DELETE] state
22550 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a ments completed.
22560 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 ** since the dat
22570 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
22580 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 was opened, inc
22590 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 luding those exe
225a0 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 cuted as.** part
225b0 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 of trigger prog
225c0 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 rams. ^Executing
225d0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 any other type
225e0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 of SQL statement
225f0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 .** does not aff
22600 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 ect the value re
22610 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 turned by sqlite
22620 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 3_total_changes(
22630 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 )..** .** ^Chang
22640 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 es made as part
22650 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 of [foreign key
22660 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 actions] are inc
22670 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 luded in the.**
22680 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 count, but those
22690 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 made as part of
226a0 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 REPLACE constra
226b0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 int resolution a
226c0 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e re.** not. ^Chan
226d0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 ges to a view th
226e0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 at are intercept
226f0 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 ed by INSTEAD OF
22700 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 triggers .** ar
22710 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a e not counted..*
22720 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 * .** See also t
22730 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e he [sqlite3_chan
22740 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 ges()] interface
22750 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f , the.** [count_
22760 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c changes pragma],
22770 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f and the [total_
22780 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 changes() SQL fu
22790 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 nction]..**.** I
227a0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 f a separate thr
227b0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 ead makes change
227c0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 s on the same da
227d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
227e0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 n.** while [sqli
227f0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 te3_total_change
22800 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 s()] is running
22810 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a then the value.*
22820 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e * returned is un
22830 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 predictable and
22840 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a not meaningful..
22850 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e */.SQLITE_API in
22860 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f t sqlite3_total_
22870 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a changes(sqlite3*
22880 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
22890 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 EF: Interrupt A
228a0 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 Long-Running Que
228b0 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 ry.** METHOD: sq
228c0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 lite3.**.** ^Thi
228d0 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 s function cause
228e0 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 s any pending da
228f0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e tabase operation
22900 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a to abort and.**
22910 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 return at its e
22920 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e arliest opportun
22930 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e ity. This routin
22940 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a e is typically.*
22950 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 * called in resp
22960 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 onse to a user a
22970 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 ction such as pr
22980 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a essing "Cancel".
22990 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 ** or Ctrl-C whe
229a0 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 re the user want
229b0 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f s a long query o
229c0 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 peration to halt
229d0 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e .** immediately.
229e0 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 .**.** ^It is sa
229f0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 fe to call this
22a00 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 routine from a t
22a10 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 hread different
22a20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 from the.** thre
22a30 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 ad that is curre
22a40 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 ntly running the
22a50 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 database operat
22a60 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 ion. But it.**
22a70 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 is not safe to c
22a80 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 all this routine
22a90 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 with a [databas
22aa0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 e connection] th
22ab0 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 at.** is closed
22ac0 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 or might close b
22ad0 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e efore sqlite3_in
22ae0 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e terrupt() return
22af0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 s..**.** ^If an
22b00 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 SQL operation is
22b10 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e very nearly fin
22b20 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d ished at the tim
22b30 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 e when.** sqlite
22b40 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 3_interrupt() is
22b50 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 called, then it
22b60 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 might not have
22b70 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a an opportunity.*
22b80 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 * to be interrup
22b90 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f ted and might co
22ba0 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 ntinue to comple
22bb0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 tion..**.** ^An
22bc0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 SQL operation th
22bd0 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 at is interrupte
22be0 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 d will return [S
22bf0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d QLITE_INTERRUPT]
22c00 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 ..** ^If the int
22c10 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 errupted SQL ope
22c20 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 ration is an INS
22c30 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 ERT, UPDATE, or
22c40 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 DELETE.** that i
22c50 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c s inside an expl
22c60 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e icit transaction
22c70 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 , then the entir
22c80 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a e transaction.**
22c90 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 will be rolled
22ca0 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c back automatical
22cb0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ly..**.** ^The s
22cc0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 qlite3_interrupt
22cd0 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 (D) call is in e
22ce0 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 ffect until all
22cf0 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e currently runnin
22d00 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 g.** SQL stateme
22d10 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 nts on [database
22d20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 connection] D c
22d30 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e omplete. ^Any n
22d40 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 ew SQL statement
22d50 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 s.** that are st
22d60 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 arted after the
22d70 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 sqlite3_interrup
22d80 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 t() call and bef
22d90 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e ore the .** runn
22da0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 ing statements r
22db0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 eaches zero are
22dc0 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 interrupted as i
22dd0 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a f they had been.
22de0 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 ** running prior
22df0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f to the sqlite3_
22e00 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c interrupt() call
22e10 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 . ^New SQL stat
22e20 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 ements.** that a
22e30 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 re started after
22e40 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 the running sta
22e50 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 tement count rea
22e60 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a ches zero are.**
22e70 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 not effected by
22e80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 the sqlite3_int
22e90 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 errupt()..** ^A
22ea0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f call to sqlite3_
22eb0 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 interrupt(D) tha
22ec0 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 t occurs when th
22ed0 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 ere are no runni
22ee0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d ng.** SQL statem
22ef0 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 ents is a no-op
22f00 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 and has no effec
22f10 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 t on SQL stateme
22f20 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 nts.** that are
22f30 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 started after th
22f40 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 e sqlite3_interr
22f50 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 upt() call retur
22f60 6e 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ns..*/.SQLITE_AP
22f70 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 I void sqlite3_i
22f80 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 nterrupt(sqlite3
22f90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 *);../*.** CAPI3
22fa0 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 REF: Determine I
22fb0 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 f An SQL Stateme
22fc0 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a nt Is Complete.*
22fd0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 *.** These routi
22fe0 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 nes are useful d
22ff0 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 uring command-li
23000 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 ne input to dete
23010 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 rmine if the.**
23020 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 currently entere
23030 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 d text seems to
23040 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 form a complete
23050 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 SQL statement or
23060 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 .** if additiona
23070 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 l input is neede
23080 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 d before sending
23090 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a the text into.*
230a0 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 * SQLite for par
230b0 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f sing. ^These ro
230c0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 utines return 1
230d0 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 if the input str
230e0 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 ing.** appears t
230f0 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 o be a complete
23100 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 SQL statement.
23110 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 ^A statement is
23120 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 judged to be.**
23130 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 complete if it e
23140 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 nds with a semic
23150 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 olon token and i
23160 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f s not a prefix o
23170 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d f a.** well-form
23180 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45 ed CREATE TRIGGE
23190 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 R statement. ^S
231a0 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 emicolons that a
231b0 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 re embedded with
231c0 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 in.** string lit
231d0 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 erals or quoted
231e0 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 identifier names
231f0 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 or comments are
23200 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 not.** independ
23210 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 ent tokens (they
23220 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 are part of the
23230 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 token in which
23240 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 they are.** embe
23250 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 dded) and thus d
23260 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 o not count as a
23270 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 statement termi
23280 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 nator. ^Whitesp
23290 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 ace.** and comme
232a0 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 nts that follow
232b0 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f the final semico
232c0 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e lon are ignored.
232d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f .**.** ^These ro
232e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 utines return 0
232f0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 if the statement
23300 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 is incomplete.
23310 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 ^If a.** memory
23320 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c allocation fail
23330 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e s, then SQLITE_N
23340 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 OMEM is returned
23350 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 ..**.** ^These r
23360 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 outines do not p
23370 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 arse the SQL sta
23380 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 tements thus.**
23390 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 will not detect
233a0 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e syntactically in
233b0 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a correct SQL..**.
233c0 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 ** ^(If SQLite h
233d0 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 as not been init
233e0 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 ialized using [s
233f0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a qlite3_initializ
23400 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 e()] prior .** t
23410 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 o invoking sqlit
23420 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 e3_complete16()
23430 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 then sqlite3_ini
23440 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 tialize() is inv
23450 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 oked.** automati
23460 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 cally by sqlite3
23470 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 _complete16().
23480 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 If that initiali
23490 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a zation fails,.**
234a0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e then the return
234b0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 value from sqli
234c0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 te3_complete16()
234d0 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 will be non-zer
234e0 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 o.** regardless
234f0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f of whether or no
23500 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 t the input SQL
23510 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a is complete.)^.*
23520 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 *.** The input t
23530 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c o [sqlite3_compl
23540 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 ete()] must be a
23550 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 zero-terminated
23560 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 .** UTF-8 string
23570 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 ..**.** The inpu
23580 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f t to [sqlite3_co
23590 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 mplete16()] must
235a0 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 be a zero-termi
235b0 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 nated.** UTF-16
235c0 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 string in native
235d0 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a byte order..*/.
235e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
235f0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 qlite3_complete(
23600 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 const char *sql)
23610 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
23620 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 sqlite3_complet
23630 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a e16(const void *
23640 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 sql);../*.** CAP
23650 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 I3REF: Register
23660 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 A Callback To Ha
23670 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 ndle SQLITE_BUSY
23680 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f Errors.** KEYWO
23690 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c RDS: {busy-handl
236a0 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 er callback} {bu
236b0 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d sy handler}.** M
236c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a ETHOD: sqlite3.*
236d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
236e0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 3_busy_handler(D
236f0 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 ,X,P) routine se
23700 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 ts a callback fu
23710 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 nction X.** that
23720 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 might be invoke
23730 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 d with argument
23740 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e P whenever.** an
23750 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 attempt is made
23760 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 to access a dat
23770 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f abase table asso
23780 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b ciated with.** [
23790 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
237a0 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 ion] D when anot
237b0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 her thread.** or
237c0 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 process has the
237d0 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a table locked..*
237e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 * The sqlite3_bu
237f0 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 sy_handler() int
23800 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 erface is used t
23810 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b o implement.** [
23820 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d sqlite3_busy_tim
23830 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 eout()] and [PRA
23840 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 GMA busy_timeout
23850 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 ]..**.** ^If the
23860 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 busy callback i
23870 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 s NULL, then [SQ
23880 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 LITE_BUSY].** is
23890 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 returned immedi
238a0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 ately upon encou
238b0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b ntering the lock
238c0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 . ^If the busy
238d0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e callback.** is n
238e0 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 ot NULL, then th
238f0 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 e callback might
23900 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 be invoked with
23910 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a two arguments..
23920 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 **.** ^The first
23930 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 argument to the
23940 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 busy handler is
23950 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 a copy of the v
23960 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 oid* pointer whi
23970 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 ch.** is the thi
23980 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 rd argument to s
23990 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 qlite3_busy_hand
239a0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 ler(). ^The sec
239b0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a ond argument to.
239c0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 ** the busy hand
239d0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 ler callback is
239e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 the number of ti
239f0 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 mes that the bus
23a00 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a y handler has.**
23a10 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 been invoked pr
23a20 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 eviously for the
23a30 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 same locking ev
23a40 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a ent. ^If the.**
23a50 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 busy callback r
23a60 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e eturns 0, then n
23a70 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 o additional att
23a80 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 empts are made t
23a90 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 o.** access the
23aa0 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 database and [SQ
23ab0 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 LITE_BUSY] is re
23ac0 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 turned.** to the
23ad0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a application..**
23ae0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 ^If the callbac
23af0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 k returns non-ze
23b00 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 ro, then another
23b10 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d attempt.** is m
23b20 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 ade to access th
23b30 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 e database and t
23b40 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 he cycle repeats
23b50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 ..**.** The pres
23b60 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 ence of a busy h
23b70 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 andler does not
23b80 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 guarantee that i
23b90 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 t will be invoke
23ba0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 d.** when there
23bb0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 is lock contenti
23bc0 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 on. ^If SQLite d
23bd0 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 etermines that i
23be0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 nvoking the busy
23bf0 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c .** handler coul
23c00 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 d result in a de
23c10 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 adlock, it will
23c20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 go ahead and ret
23c30 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 urn [SQLITE_BUSY
23c40 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c ].** to the appl
23c50 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 ication instead
23c60 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 of invoking the
23c70 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 .** busy handler
23c80 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 ..** Consider a
23c90 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f scenario where o
23ca0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f ne process is ho
23cb0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 lding a read loc
23cc0 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 k that.** it is
23cd0 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 trying to promot
23ce0 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 e to a reserved
23cf0 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 lock and.** a se
23d00 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 cond process is
23d10 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 holding a reserv
23d20 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 ed lock that it
23d30 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 is trying.** to
23d40 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 promote to an ex
23d50 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 clusive lock. T
23d60 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 he first process
23d70 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a cannot proceed.
23d80 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73 ** because it is
23d90 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 blocked by the
23da0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 second and the s
23db0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 econd process ca
23dc0 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 nnot.** proceed
23dd0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c because it is bl
23de0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 ocked by the fir
23df0 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f st. If both pro
23e00 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 cesses.** invoke
23e10 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 the busy handle
23e20 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c rs, neither will
23e30 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 make any progre
23e40 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a ss. Therefore,.
23e50 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e ** SQLite return
23e60 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 s [SQLITE_BUSY]
23e70 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72 for the first pr
23e80 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 ocess, hoping th
23e90 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 at this.** will
23ea0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74 induce the first
23eb0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 process to rele
23ec0 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 ase its read loc
23ed0 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 k and allow.** t
23ee0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 he second proces
23ef0 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a s to proceed..**
23f00 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 .** ^The default
23f10 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 busy callback i
23f20 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 s NULL..**.** ^(
23f30 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 There can only b
23f40 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 e a single busy
23f50 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 handler defined
23f60 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 for each.** [dat
23f70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e abase connection
23f80 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 ]. Setting a ne
23f90 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 w busy handler c
23fa0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 lears any.** pre
23fb0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 viously set hand
23fc0 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 ler.)^ ^Note th
23fd0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 at calling [sqli
23fe0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 te3_busy_timeout
23ff0 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 ()].** or evalua
24000 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 ting [PRAGMA bus
24010 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c y_timeout=N] wil
24020 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 l change the.**
24030 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 busy handler and
24040 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 thus clear any
24050 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 previously set b
24060 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a usy handler..**.
24070 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c ** The busy call
24080 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 back should not
24090 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 take any actions
240a0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 which modify th
240b0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f e.** database co
240c0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e nnection that in
240d0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 voked the busy h
240e0 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 andler. In othe
240f0 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 r words,.** the
24100 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 busy handler is
24110 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 not reentrant.
24120 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 Any such actions
24130 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e .** result in un
24140 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 defined behavior
24150 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 ..** .** A busy
24160 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 handler must not
24170 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 close the datab
24180 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a ase connection.*
24190 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 * or [prepared s
241a0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 tatement] that i
241b0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 nvoked the busy
241c0 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 handler..*/.SQLI
241d0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
241e0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 e3_busy_handler(
241f0 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 sqlite3*,int(*)(
24200 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a void*,int),void*
24210 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
24220 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 EF: Set A Busy T
24230 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 imeout.** METHOD
24240 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
24250 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 ^This routine se
24260 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 ts a [sqlite3_bu
24270 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 sy_handler | bus
24280 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 y handler] that
24290 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 sleeps.** for a
242a0 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 specified amount
242b0 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 of time when a
242c0 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e table is locked.
242d0 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a ^The handler.*
242e0 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c * will sleep mul
242f0 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 tiple times unti
24300 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 l at least "ms"
24310 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 milliseconds of
24320 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 sleeping.** have
24330 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e accumulated. ^
24340 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 After at least "
24350 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 ms" milliseconds
24360 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a of sleeping,.**
24370 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 the handler ret
24380 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 urns 0 which cau
24390 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 ses [sqlite3_ste
243a0 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a p()] to return.*
243b0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e * [SQLITE_BUSY].
243c0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 .**.** ^Calling
243d0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 this routine wit
243e0 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 h an argument le
243f0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c ss than or equal
24400 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e to zero.** turn
24410 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 s off all busy h
24420 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e andlers..**.** ^
24430 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 (There can only
24440 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 be a single busy
24450 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 handler for a p
24460 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 articular.** [da
24470 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
24480 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 n] at any given
24490 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 moment. If anot
244a0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 her busy handler
244b0 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 .** was defined
244c0 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 (using [sqlite3
244d0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d _busy_handler()]
244e0 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 ) prior to calli
244f0 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 ng.** this routi
24500 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 ne, that other b
24510 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 usy handler is c
24520 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 leared.)^.**.**
24530 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 See also: [PRAG
24540 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d MA busy_timeout]
24550 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .*/.SQLITE_API i
24560 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f nt sqlite3_busy_
24570 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a timeout(sqlite3*
24580 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a , int ms);../*.*
24590 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 * CAPI3REF: Conv
245a0 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 enience Routines
245b0 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 For Running Que
245c0 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ries.** METHOD:
245d0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 sqlite3.**.** Th
245e0 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 is is a legacy i
245f0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 nterface that is
24600 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 preserved for b
24610 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 ackwards compati
24620 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f bility..** Use o
24630 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 f this interface
24640 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e is not recommen
24650 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e ded..**.** Defin
24660 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 ition: A <b>resu
24670 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 lt table</b> is
24680 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 memory data stru
24690 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 cture created by
246a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
246b0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e _get_table()] in
246c0 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 terface. A resu
246d0 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 lt table records
246e0 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 the.** complete
246f0 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 query results f
24700 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 rom one or more
24710 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 queries..**.** T
24720 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 he table concept
24730 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 ually has a numb
24740 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 er of rows and c
24750 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 olumns. But.**
24760 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 these numbers ar
24770 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 e not part of th
24780 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 e result table i
24790 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a tself. These.**
247a0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 numbers are obt
247b0 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 ained separately
247c0 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 . Let N be the
247d0 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a number of rows.*
247e0 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e * and M be the n
247f0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
24800 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 ..**.** A result
24810 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 table is an arr
24820 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 ay of pointers t
24830 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 o zero-terminate
24840 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e d UTF-8 strings.
24850 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e .** There are (N
24860 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 +1)*M elements i
24870 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 n the array. Th
24880 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 e first M pointe
24890 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a rs point.** to z
248a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 ero-terminated s
248b0 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e trings that con
248c0 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f tain the names o
248d0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a f the columns..*
248e0 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 * The remaining
248f0 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e entries all poin
24900 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c t to query resul
24910 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 ts. NULL values
24920 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 result.** in NU
24930 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c LL pointers. Al
24940 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 l other values a
24950 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d re in their UTF-
24960 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 8 zero-terminate
24970 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 d.** string repr
24980 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 esentation as re
24990 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
249a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 e3_column_text()
249b0 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c ]..**.** A resul
249c0 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f t table might co
249d0 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 nsist of one or
249e0 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f more memory allo
249f0 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 cations..** It i
24a00 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 s not safe to pa
24a10 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c ss a result tabl
24a20 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 e directly to [s
24a30 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a qlite3_free()]..
24a40 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c ** A result tabl
24a50 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c e should be deal
24a60 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 located using [s
24a70 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c qlite3_free_tabl
24a80 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 e()]..**.** ^(As
24a90 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 an example of t
24aa0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 he result table
24ab0 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 format, suppose
24ac0 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a a query result.*
24ad0 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a * is as follows:
24ae0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
24af0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 te><pre>.**
24b00 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c Name |
24b10 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d Age.** -
24b20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d ----------------
24b30 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 ------.**
24b40 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 Alice | 4
24b50 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 3.** Bob
24b60 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 | 28.**
24b70 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 Cindy
24b80 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 | 21.** </pre
24b90 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a ></blockquote>.*
24ba0 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 *.** There are t
24bb0 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 wo column (M==2)
24bc0 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 and three rows
24bd0 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 (N==3). Thus th
24be0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c e.** result tabl
24bf0 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e e has 8 entries.
24c00 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 Suppose the re
24c10 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 sult table is st
24c20 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 ored.** in an ar
24c30 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 ray names azResu
24c40 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 lt. Then azResu
24c50 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f lt holds this co
24c60 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c ntent:.**.** <bl
24c70 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a ockquote><pre>.*
24c80 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c * azResul
24c90 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 t[0] = "Name
24ca0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 ";.** azR
24cb0 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 esult[1] = "
24cc0 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 Age";.**
24cd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 azResult[2]
24ce0 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 = "Alice";.**
24cf0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 azResult	
24d00 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 1;3] = "43";.**
24d10 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 azResult&
24d20 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a #91;4] = "Bob";.
24d30 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 ** azResu
24d40 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 lt[5] = "28"
24d50 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 ;.** azRe
24d60 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 sult[6] = "C
24d70 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 indy";.**
24d80 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d azResult[7]
24d90 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 = "21";.** </pr
24da0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 e></blockquote>)
24db0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ^.**.** ^The sql
24dc0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 ite3_get_table()
24dd0 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 function evalua
24de0 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a tes one or more.
24df0 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 ** semicolon-sep
24e00 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 arated SQL state
24e10 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 ments in the zer
24e20 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 o-terminated UTF
24e30 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 -8.** string of
24e40 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 its 2nd paramete
24e50 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 r and returns a
24e60 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 result table to
24e70 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 the.** pointer g
24e80 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 iven in its 3rd
24e90 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a parameter..**.**
24ea0 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 After the appli
24eb0 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 cation has finis
24ec0 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 hed with the res
24ed0 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 ult from sqlite3
24ee0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a _get_table(),.**
24ef0 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 it must pass th
24f00 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 e result table p
24f10 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 ointer to sqlite
24f20 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 3_free_table() i
24f30 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 n order to.** re
24f40 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 lease the memory
24f50 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 that was malloc
24f60 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 ed. Because of
24f70 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b the way the.** [
24f80 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 sqlite3_malloc()
24f90 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e ] happens within
24fa0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 sqlite3_get_tab
24fb0 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e le(), the callin
24fc0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 g.** function mu
24fd0 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 st not try to ca
24fe0 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 ll [sqlite3_free
24ff0 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f ()] directly. O
25000 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f nly.** [sqlite3_
25010 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 free_table()] is
25020 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 able to release
25030 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 the memory prop
25040 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e erly and safely.
25050 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
25060 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 e3_get_table() i
25070 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c nterface is impl
25080 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 emented as a wra
25090 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b pper around.** [
250a0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e sqlite3_exec()].
250b0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 The sqlite3_ge
250c0 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e t_table() routin
250d0 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 e does not have
250e0 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 access.** to any
250f0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 internal data s
25100 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c tructures of SQL
25110 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e ite. It uses on
25120 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a ly the public.**
25130 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e interface defin
25140 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 ed here. As a c
25150 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f onsequence, erro
25160 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e rs that occur in
25170 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 the.** wrapper
25180 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 layer outside of
25190 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 the internal [s
251a0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 qlite3_exec()] c
251b0 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 all are not.** r
251c0 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 eflected in subs
251d0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
251e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 [sqlite3_errcode
251f0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
25200 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f e3_errmsg()]..*/
25210 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
25220 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c sqlite3_get_tabl
25230 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 e(. sqlite3 *db
25240 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e , /* An
25250 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a open database *
25260 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
25270 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c zSql, /* SQL
25280 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 to be evaluated
25290 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 */. char ***pa
252a0 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 zResult, /* R
252b0 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 esults of the qu
252c0 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e ery */. int *pn
252d0 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f Row, /
252e0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 * Number of resu
252f0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 lt rows written
25300 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 here */. int *p
25310 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 nColumn,
25320 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 /* Number of res
25330 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 ult columns writ
25340 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 ten here */. ch
25350 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 ar **pzErrmsg
25360 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 /* Error msg
25370 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f written here */
25380 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 .);.SQLITE_API v
25390 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 oid sqlite3_free
253a0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 _table(char **re
253b0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 sult);../*.** CA
253c0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 PI3REF: Formatte
253d0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e d String Printin
253e0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a g Functions.**.*
253f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 * These routines
25400 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 are work-alikes
25410 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 of the "printf(
25420 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e )" family of fun
25430 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 ctions.** from t
25440 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 he standard C li
25450 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 brary..** These
25460 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 routines underst
25470 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 and most of the
25480 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 common K&R forma
25490 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a tting options,.*
254a0 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 * plus some addi
254b0 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 tional non-stand
254c0 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 ard formats, det
254d0 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 ailed below..**
254e0 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f Note that some o
254f0 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 f the more obscu
25500 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 re formatting op
25510 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e tions from recen
25520 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 t.** C-library s
25530 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 tandards are omi
25540 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 tted from this i
25550 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a mplementation..*
25560 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 *.** ^The sqlite
25570 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 3_mprintf() and
25580 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 sqlite3_vmprintf
25590 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 () routines writ
255a0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c e their.** resul
255b0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f ts into memory o
255c0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 btained from [sq
255d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e lite3_malloc()].
255e0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 .** The strings
255f0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 returned by thes
25600 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 e two routines s
25610 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 hould be.** rele
25620 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 ased by [sqlite3
25630 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 _free()]. ^Both
25640 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
25650 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 a.** NULL point
25660 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d er if [sqlite3_m
25670 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 alloc()] is unab
25680 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 le to allocate e
25690 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 nough.** memory
256a0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 to hold the resu
256b0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a lting string..**
256c0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 .** ^(The sqlite
256d0 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 3_snprintf() rou
256e0 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 tine is similar
256f0 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 to "snprintf()"
25700 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e from.** the stan
25710 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 dard C library.
25720 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 The result is w
25730 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a ritten into the.
25740 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 ** buffer suppli
25750 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 ed as the second
25760 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 parameter whose
25770 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 size is given b
25780 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 y.** the first p
25790 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 arameter. Note t
257a0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 hat the order of
257b0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 the.** first tw
257c0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 o parameters is
257d0 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e reversed from sn
257e0 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 printf().)^ Thi
257f0 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f s is an.** histo
25800 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 rical accident t
25810 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 hat cannot be fi
25820 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 xed without brea
25830 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 king.** backward
25840 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e s compatibility.
25850 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 ^(Note also th
25860 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 at sqlite3_snpri
25870 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 ntf().** returns
25880 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 a pointer to it
25890 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 s buffer instead
258a0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f of the number o
258b0 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 f.** characters
258c0 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e actually written
258d0 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 into the buffer
258e0 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 .)^ We admit th
258f0 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 at.** the number
25900 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 of characters w
25910 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 ritten would be
25920 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 a more useful re
25930 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 turn.** value bu
25940 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e t we cannot chan
25950 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 ge the implement
25960 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 ation of sqlite3
25970 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e _snprintf().** n
25980 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b ow without break
25990 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 ing compatibilit
259a0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e y..**.** ^As lon
259b0 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 g as the buffer
259c0 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 size is greater
259d0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 than zero, sqlit
259e0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a e3_snprintf().**
259f0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 guarantees that
25a00 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 the buffer is a
25a10 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 lways zero-termi
25a20 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 nated. ^The fir
25a30 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 st.** parameter
25a40 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c "n" is the total
25a50 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 size of the buf
25a60 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 fer, including s
25a70 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 pace for.** the
25a80 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e zero terminator.
25a90 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 So the longest
25aa0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e string that can
25ab0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a be completely.*
25ac0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 * written will b
25ad0 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 e n-1 characters
25ae0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
25af0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 ite3_vsnprintf()
25b00 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 routine is a va
25b10 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 rargs version of
25b20 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 sqlite3_snprint
25b30 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 f()..**.** These
25b40 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d routines all im
25b50 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 plement some add
25b60 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 itional formatti
25b70 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 ng.** options th
25b80 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f at are useful fo
25b90 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 r constructing S
25ba0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a QL statements..*
25bb0 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 * All of the usu
25bc0 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d al printf() form
25bd0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 atting options a
25be0 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 pply. In additi
25bf0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 on, there.** is
25c00 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 are "%q", "%Q",
25c10 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 "%w" and "%z" op
25c20 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 tions..**.** ^(T
25c30 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 he %q option wor
25c40 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 ks like %s in th
25c50 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 at it substitute
25c60 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 s a nul-terminat
25c70 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f ed.** string fro
25c80 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c m the argument l
25c90 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 ist. But %q als
25ca0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 o doubles every
25cb0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a '\'' character..
25cc0 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 ** %q is designe
25cd0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 d for use inside
25ce0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 a string litera
25cf0 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e l.)^ By doublin
25d00 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 g each '\''.** c
25d10 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 haracter it esca
25d20 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 pes that charact
25d30 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 er and allows it
25d40 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 to be inserted
25d50 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 into.** the stri
25d60 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 ng..**.** For ex
25d70 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 ample, assume th
25d80 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c e string variabl
25d90 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 e zText contains
25da0 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 text as follows
25db0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 :.**.** <blockqu
25dc0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 ote><pre>.** ch
25dd0 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 ar *zText = "It'
25de0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b s a happy day!";
25df0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 .** </pre></bloc
25e00 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e kquote>.**.** On
25e10 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 e can use this t
25e20 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 ext in an SQL st
25e30 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f atement as follo
25e40 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b ws:.**.** <block
25e50 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 quote><pre>.**
25e60 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c char *zSQL = sql
25e70 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e ite3_mprintf("IN
25e80 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 SERT INTO table
25e90 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a VALUES('%q')", z
25ea0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 Text);.** sqlit
25eb0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c e3_exec(db, zSQL
25ec0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 , 0, 0, 0);.**
25ed0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 sqlite3_free(zSQ
25ee0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 L);.** </pre></b
25ef0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a lockquote>.**.**
25f00 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 Because the %q
25f10 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 format string is
25f20 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 used, the '\''
25f30 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 character in zTe
25f40 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 xt.** is escaped
25f50 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e and the SQL gen
25f60 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c erated is as fol
25f70 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f lows:.**.** <blo
25f80 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a ckquote><pre>.**
25f90 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 INSERT INTO ta
25fa0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 ble1 VALUES('It'
25fb0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 's a happy day!'
25fc0 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f ).** </pre></blo
25fd0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 ckquote>.**.** T
25fe0 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 his is correct.
25ff0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 Had we used %s
26000 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 instead of %q, t
26010 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c he generated SQL
26020 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c .** would have l
26030 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a ooked like this:
26040 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f .**.** <blockquo
26050 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 te><pre>.** INS
26060 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 ERT INTO table1
26070 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 VALUES('It's a h
26080 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 appy day!');.**
26090 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
260a0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 te>.**.** This s
260b0 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 econd example is
260c0 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 an SQL syntax e
260d0 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 rror. As a gene
260e0 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f ral rule you sho
260f0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 uld.** always us
26100 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 e %q instead of
26110 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e %s when insertin
26120 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 g text into a st
26130 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a ring literal..**
26140 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 .** ^(The %Q opt
26150 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 ion works like %
26160 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f q except it also
26170 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f adds single quo
26180 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 tes around.** th
26190 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 e outside of the
261a0 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 total string.
261b0 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 Additionally, if
261c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 the parameter i
261d0 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e n the.** argumen
261e0 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c t list is a NULL
261f0 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 pointer, %Q sub
26200 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 stitutes the tex
26210 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 t "NULL" (withou
26220 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 t.** single quot
26230 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 es).)^ So, for
26240 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 example, one cou
26250 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ld say:.**.** <b
26260 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
26270 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d ** char *zSQL =
26280 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 sqlite3_mprintf
26290 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 ("INSERT INTO ta
262a0 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c ble VALUES(%Q)",
262b0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c zText);.** sql
262c0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 ite3_exec(db, zS
262d0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a QL, 0, 0, 0);.**
262e0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a sqlite3_free(z
262f0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c SQL);.** </pre><
26300 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a /blockquote>.**.
26310 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 ** The code abov
26320 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 e will render a
26330 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 correct SQL stat
26340 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 ement in the zSQ
26350 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 L.** variable ev
26360 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 en if the zText
26370 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 variable is a NU
26380 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a LL pointer..**.*
26390 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 * ^(The "%w" for
263a0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 matting option i
263b0 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 s like "%q" exce
263c0 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63 pt that it expec
263d0 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 ts to.** be cont
263e0 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 ained within dou
263f0 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 ble-quotes inste
26400 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f ad of single quo
26410 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 tes, and it.** e
26420 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c scapes the doubl
26430 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 e-quote characte
26440 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 r instead of the
26450 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a single-quote.**
26460 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 character.)^ T
26470 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 he "%w" formatti
26480 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 ng option is int
26490 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 ended for safely
264a0 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 inserting.** ta
264b0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e ble and column n
264c0 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 ames into a cons
264d0 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 tructed SQL stat
264e0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 ement..**.** ^(T
264f0 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 he "%z" formatti
26500 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 ng option works
26510 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 like "%s" but wi
26520 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 th the.** additi
26530 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 on that after th
26540 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 e string has bee
26550 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 n read and copie
26560 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 d into.** the re
26570 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 sult, [sqlite3_f
26580 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 ree()] is called
26590 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 on the input st
265a0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 ring.)^.*/.SQLIT
265b0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 E_API char *sqli
265c0 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 te3_mprintf(cons
265d0 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 t char*,...);.SQ
265e0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 LITE_API char *s
265f0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 qlite3_vmprintf(
26600 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f const char*, va_
26610 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 list);.SQLITE_AP
26620 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f I char *sqlite3_
26630 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 snprintf(int,cha
26640 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 r*,const char*,
26650 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 ...);.SQLITE_API
26660 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 char *sqlite3_v
26670 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 snprintf(int,cha
26680 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 r*,const char*,
26690 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a va_list);../*.**
266a0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 CAPI3REF: Memor
266b0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 y Allocation Sub
266c0 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 system.**.** The
266d0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 SQLite core use
266e0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f s these three ro
266f0 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f utines for all o
26700 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 f its own.** int
26710 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c ernal memory all
26720 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 ocation needs. "
26730 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 Core" in the pre
26740 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a vious sentence.*
26750 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 * does not inclu
26760 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 de operating-sys
26770 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 tem specific VFS
26780 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e implementation.
26790 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 The.** Windows
267a0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 VFS uses native
267b0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 malloc() and fr
267c0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 ee() for some op
267d0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 erations..**.**
267e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^The sqlite3_mal
267f0 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 loc() routine re
26800 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 turns a pointer
26810 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 to a block.** of
26820 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 memory at least
26830 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 N bytes in leng
26840 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 th, where N is t
26850 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a he parameter..**
26860 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c ^If sqlite3_mal
26870 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 loc() is unable
26880 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 to obtain suffic
26890 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d ient free.** mem
268a0 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 ory, it returns
268b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 a NULL pointer.
268c0 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 ^If the paramet
268d0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 er N to.** sqlit
268e0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a e3_malloc() is z
268f0 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 ero or negative
26900 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c then sqlite3_mal
26910 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a loc() returns.**
26920 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e a NULL pointer.
26930 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 .**.** ^The sqli
26940 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 te3_malloc64(N)
26950 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 routine works ju
26960 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 st like.** sqlit
26970 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 e3_malloc(N) exc
26980 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e ept that N is an
26990 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 unsigned 64-bit
269a0 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 integer instead
269b0 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 .** of a signed
269c0 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 32-bit integer..
269d0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 **.** ^Calling s
269e0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 qlite3_free() wi
269f0 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 th a pointer pre
26a00 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 viously returned
26a10 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d .** by sqlite3_m
26a20 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 alloc() or sqlit
26a30 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c e3_realloc() rel
26a40 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 eases that memor
26a50 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 y so.** that it
26a60 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e might be reused.
26a70 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 ^The sqlite3_f
26a80 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 ree() routine is
26a90 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 .** a no-op if i
26aa0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 s called with a
26ab0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 NULL pointer. P
26ac0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f assing a NULL po
26ad0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 inter.** to sqli
26ae0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 te3_free() is ha
26af0 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 rmless. After b
26b00 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f eing freed, memo
26b10 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 ry.** should nei
26b20 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 ther be read nor
26b30 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 written. Even
26b40 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 reading previous
26b50 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f ly freed.** memo
26b60 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 ry might result
26b70 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f in a segmentatio
26b80 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 n fault or other
26b90 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a severe error..*
26ba0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 * Memory corrupt
26bb0 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 ion, a segmentat
26bc0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 ion fault, or ot
26bd0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 her severe error
26be0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 .** might result
26bf0 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 if sqlite3_free
26c00 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 () is called wit
26c10 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 h a non-NULL poi
26c20 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 nter that.** was
26c30 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 not obtained fr
26c40 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
26c50 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 c() or sqlite3_r
26c60 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 ealloc()..**.**
26c70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 ^The sqlite3_rea
26c80 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 lloc(X,N) interf
26c90 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 ace attempts to
26ca0 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f resize a.** prio
26cb0 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 r memory allocat
26cc0 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c ion X to be at l
26cd0 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a east N bytes..**
26ce0 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d ^If the X param
26cf0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f eter to sqlite3_
26d00 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 realloc(X,N).**
26d10 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 is a NULL pointe
26d20 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 r then its behav
26d30 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c ior is identical
26d40 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 to calling.** s
26d50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 qlite3_malloc(N)
26d60 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 ..** ^If the N p
26d70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 arameter to sqli
26d80 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 te3_realloc(X,N)
26d90 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e is zero or.** n
26da0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 egative then the
26db0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 behavior is exa
26dc0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 ctly the same as
26dd0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 calling.** sqli
26de0 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 te3_free(X)..**
26df0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 ^sqlite3_realloc
26e00 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 (X,N) returns a
26e10 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d pointer to a mem
26e20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a ory allocation.*
26e30 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 * of at least N
26e40 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 bytes in size or
26e50 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 NULL if insuffi
26e60 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 cient memory is
26e70 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 available..** ^I
26e80 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 f M is the size
26e90 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
26ea0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 ocation, then mi
26eb0 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 n(N,M) bytes.**
26ec0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c of the prior all
26ed0 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 ocation are copi
26ee0 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 ed into the begi
26ef0 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 nning of buffer
26f00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 returned.** by s
26f10 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 qlite3_realloc(X
26f20 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f ,N) and the prio
26f30 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 r allocation is
26f40 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 freed..** ^If sq
26f50 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c lite3_realloc(X,
26f60 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 N) returns NULL
26f70 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 and N is positiv
26f80 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 e, then the.** p
26f90 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 rior allocation
26fa0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a is not freed..**
26fb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 .** ^The sqlite3
26fc0 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 _realloc64(X,N)
26fd0 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 interfaces works
26fe0 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 the same as.**
26ff0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
27000 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 X,N) except that
27010 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 N is a 64-bit u
27020 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 nsigned integer
27030 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 instead.** of a
27040 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 32-bit signed in
27050 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 teger..**.** ^If
27060 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 X is a memory a
27070 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f llocation previo
27080 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 usly obtained fr
27090 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f om sqlite3_mallo
270a0 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f c(),.** sqlite3_
270b0 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 malloc64(), sqli
270c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f te3_realloc(), o
270d0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f r sqlite3_reallo
270e0 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 c64(), then.** s
270f0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 qlite3_msize(X)
27100 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 returns the size
27110 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 of that memory
27120 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 allocation in by
27130 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c tes..** ^The val
27140 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 ue returned by s
27150 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 qlite3_msize(X)
27160 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 might be larger
27170 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a than the number.
27180 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 ** of bytes requ
27190 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 ested when X was
271a0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 allocated. ^If
271b0 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 X is a NULL poi
271c0 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c nter then.** sql
271d0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 ite3_msize(X) re
271e0 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 turns zero. If
271f0 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 X points to some
27200 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f thing that is no
27210 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 t.** the beginni
27220 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c ng of memory all
27230 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 ocation, or if i
27240 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f t points to a fo
27250 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 rmerly.** valid
27260 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f memory allocatio
27270 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 n that has now b
27280 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 een freed, then
27290 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 the behavior.**
272a0 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 of sqlite3_msize
272b0 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 (X) is undefined
272c0 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 and possibly ha
272d0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 rmful..**.** ^Th
272e0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 e memory returne
272f0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c d by sqlite3_mal
27300 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 loc(), sqlite3_r
27310 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c ealloc(),.** sql
27320 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c ite3_malloc64(),
27330 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 and sqlite3_rea
27340 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 lloc64().** is a
27350 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f lways aligned to
27360 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 at least an 8 b
27370 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 yte boundary, or
27380 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 to a.** 4 byte
27390 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 boundary if the
273a0 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 [SQLITE_4_BYTE_A
273b0 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 LIGNED_MALLOC] c
273c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f ompile-time.** o
273d0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a ption is used..*
273e0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 *.** In SQLite v
273f0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 ersion 3.5.0 and
27400 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 3.5.1, it was p
27410 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e ossible to defin
27420 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f e.** the SQLITE_
27430 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f OMIT_MEMORY_ALLO
27440 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 CATION which wou
27450 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 ld cause the bui
27460 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 lt-in.** impleme
27470 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 ntation of these
27480 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 routines to be
27490 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 omitted. That c
274a0 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 apability.** is
274b0 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 no longer provid
274c0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d ed. Only built-
274d0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 in memory alloca
274e0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 tors can be used
274f0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f ..**.** Prior to
27500 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 SQLite version
27510 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 3.7.10, the Wind
27520 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 ows OS interface
27530 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a layer called.**
27540 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c the system mall
27550 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 oc() and free()
27560 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f directly when co
27570 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 nverting.** file
27580 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 names between th
27590 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 e UTF-8 encoding
275a0 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a used by SQLite.
275b0 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 ** and whatever
275c0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e filename encodin
275d0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 g is used by the
275e0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 particular Wind
275f0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 ows.** installat
27600 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c ion. Memory all
27610 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 ocation errors w
27620 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 ere detected, bu
27630 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 t.** they were r
27640 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 eported back as
27650 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e [SQLITE_CANTOPEN
27660 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ] or.** [SQLITE_
27670 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 IOERR] rather th
27680 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d an [SQLITE_NOMEM
27690 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 ]..**.** The poi
276a0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 nter arguments t
276b0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
276c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f )] and [sqlite3_
276d0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 realloc()].** mu
276e0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c st be either NUL
276f0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 L or else pointe
27700 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d rs obtained from
27710 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f a prior.** invo
27720 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 cation of [sqlit
27730 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 e3_malloc()] or
27740 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 [sqlite3_realloc
27750 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a ()] that have.**
27760 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 not yet been re
27770 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 leased..**.** Th
27780 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 e application mu
27790 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 st not read or w
277a0 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 rite any part of
277b0 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d .** a block of m
277c0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 emory after it h
277d0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 as been released
277e0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 using.** [sqlit
277f0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 e3_free()] or [s
27800 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 qlite3_realloc()
27810 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 ]..*/.SQLITE_API
27820 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d void *sqlite3_m
27830 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 alloc(int);.SQLI
27840 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c TE_API void *sql
27850 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 ite3_malloc64(sq
27860 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 lite3_uint64);.S
27870 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a QLITE_API void *
27880 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 sqlite3_realloc(
27890 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c void*, int);.SQL
278a0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 ITE_API void *sq
278b0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 lite3_realloc64(
278c0 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 void*, sqlite3_u
278d0 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 int64);.SQLITE_A
278e0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f PI void sqlite3_
278f0 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c free(void*);.SQL
27900 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
27910 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d uint64 sqlite3_m
27920 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a size(void*);../*
27930 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 .** CAPI3REF: Me
27940 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 mory Allocator S
27950 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 tatistics.**.**
27960 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 SQLite provides
27970 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 these two interf
27980 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 aces for reporti
27990 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 ng on the status
279a0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 .** of the [sqli
279b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b te3_malloc()], [
279c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c sqlite3_free()],
279d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 and [sqlite3_re
279e0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 alloc()].** rout
279f0 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d ines, which form
27a00 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 the built-in me
27a10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 mory allocation
27a20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a subsystem..**.**
27a30 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d ^The [sqlite3_m
27a40 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f emory_used()] ro
27a50 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 utine returns th
27a60 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
27a70 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 s.** of memory c
27a80 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e urrently outstan
27a90 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 ding (malloced b
27aa0 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a ut not freed)..*
27ab0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f * ^The [sqlite3_
27ac0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 memory_highwater
27ad0 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 ()] routine retu
27ae0 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a rns the maximum.
27af0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c ** value of [sql
27b00 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 ite3_memory_used
27b10 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 ()] since the hi
27b20 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a gh-water mark.**
27b30 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e was last reset.
27b40 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 ^The values re
27b50 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 turned by [sqlit
27b60 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 e3_memory_used()
27b70 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 ] and.** [sqlite
27b80 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
27b90 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e er()] include an
27ba0 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 y overhead.** ad
27bb0 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e ded by SQLite in
27bc0 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 its implementat
27bd0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f ion of [sqlite3_
27be0 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 malloc()],.** bu
27bf0 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 t not overhead a
27c00 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 dded by the any
27c10 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 underlying syste
27c20 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 m library.** rou
27c30 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 tines that [sqli
27c40 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 te3_malloc()] ma
27c50 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 y call..**.** ^T
27c60 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 he memory high-w
27c70 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 ater mark is res
27c80 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e et to the curren
27c90 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 t value of.** [s
27ca0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 qlite3_memory_us
27cb0 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c ed()] if and onl
27cc0 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 y if the paramet
27cd0 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 er to.** [sqlite
27ce0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 3_memory_highwat
27cf0 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 er()] is true.
27d00 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 ^The value retur
27d10 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 ned.** by [sqlit
27d20 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 e3_memory_highwa
27d30 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 ter(1)] is the h
27d40 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a igh-water mark.*
27d50 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 * prior to the r
27d60 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f eset..*/.SQLITE_
27d70 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 API sqlite3_int6
27d80 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 4 sqlite3_memory
27d90 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c _used(void);.SQL
27da0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f ITE_API sqlite3_
27db0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 int64 sqlite3_me
27dc0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 mory_highwater(i
27dd0 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a nt resetFlag);..
27de0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 /*.** CAPI3REF:
27df0 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 Pseudo-Random Nu
27e00 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a mber Generator.*
27e10 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 *.** SQLite cont
27e20 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c ains a high-qual
27e30 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f ity pseudo-rando
27e40 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 m number generat
27e50 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 or (PRNG) used t
27e60 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 o.** select rand
27e70 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 om [ROWID | ROWI
27e80 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 Ds] when inserti
27e90 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 ng new records i
27ea0 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 nto a table that
27eb0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 .** already uses
27ec0 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 the largest pos
27ed0 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 sible [ROWID].
27ee0 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f The PRNG is also
27ef0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 used for.** the
27f00 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d build-in random
27f10 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f () and randomblo
27f20 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e b() SQL function
27f30 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 s. This interfa
27f40 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 ce allows.** app
27f50 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 lications to acc
27f60 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e ess the same PRN
27f70 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 G for other purp
27f80 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 oses..**.** ^A c
27f90 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 all to this rout
27fa0 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 ine stores N byt
27fb0 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 es of randomness
27fc0 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a into buffer P..
27fd0 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 ** ^The P parame
27fe0 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c ter can be a NUL
27ff0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a L pointer..**.**
28000 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e ^If this routin
28010 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 e has not been p
28020 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 reviously called
28030 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 or if the previ
28040 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 ous.** call had
28050 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 N less than one
28060 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 or a NULL pointe
28070 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 r for P, then th
28080 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 e PRNG is.** see
28090 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d ded using random
280a0 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 ness obtained fr
280b0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 om the xRandomne
280c0 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 ss method of.**
280d0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c the default [sql
280e0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 ite3_vfs] object
280f0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 ..** ^If the pre
28100 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 vious call to th
28110 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 is routine had a
28120 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 n N of 1 or more
28130 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 and a.** non-NU
28140 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 LL P then the ps
28150 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 eudo-randomness
28160 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 is generated.**
28170 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 internally and w
28180 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 ithout recourse
28190 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f to the [sqlite3_
281a0 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 vfs] xRandomness
281b0 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 .** method..*/.S
281c0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 QLITE_API void s
281d0 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 qlite3_randomnes
281e0 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 s(int N, void *P
281f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
28200 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 EF: Compile-Time
28210 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 Authorization C
28220 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 allbacks.** METH
28230 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b OD: sqlite3.** K
28240 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 EYWORDS: {author
28250 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a izer callback}.*
28260 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 *.** ^This routi
28270 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 ne registers an
28280 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 authorizer callb
28290 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 ack with a parti
282a0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 cular.** [databa
282b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 se connection],
282c0 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 supplied in the
282d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a first argument..
282e0 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a ** ^The authoriz
282f0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 er callback is i
28300 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 nvoked as SQL st
28310 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 atements are bei
28320 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 ng compiled.** b
28330 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 y [sqlite3_prepa
28340 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 re()] or its var
28350 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 iants [sqlite3_p
28360 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a repare_v2()],.**
28370 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
28380 65 5f 76 33 28 29 5d 2c 20 5b 73 71 6c 69 74 65 e_v3()], [sqlite
28390 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 3_prepare16()],
283a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
283b0 31 36 5f 76 32 28 29 5d 2c 0a 2a 2a 20 61 6e 64 16_v2()],.** and
283c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
283d0 65 31 36 5f 76 33 28 29 5d 2e 20 20 5e 41 74 20 e16_v3()]. ^At
283e0 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 various.** point
283f0 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d s during the com
28400 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 pilation process
28410 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 , as logic is be
28420 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 ing created.** t
28430 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 o perform variou
28440 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 s actions, the a
28450 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
28460 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f ck is invoked to
28470 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 .** see if those
28480 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c actions are all
28490 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 owed. ^The auth
284a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 orizer callback
284b0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e should.** return
284c0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 [SQLITE_OK] to
284d0 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e allow the action
284e0 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 , [SQLITE_IGNORE
284f0 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 ] to disallow th
28500 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 e.** specific ac
28510 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 tion but allow t
28520 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 he SQL statement
28530 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 to continue to
28540 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 be.** compiled,
28550 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d or [SQLITE_DENY]
28560 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e to cause the en
28570 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 tire SQL stateme
28580 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 nt to be.** reje
28590 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 cted with an err
285a0 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 or. ^If the aut
285b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b horizer callback
285c0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 returns.** any
285d0 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e value other than
285e0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d [SQLITE_IGNORE]
285f0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f , [SQLITE_OK], o
28600 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a r [SQLITE_DENY].
28610 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c ** then the [sql
28620 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
28630 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 )] or equivalent
28640 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 call that trigg
28650 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 ered.** the auth
28660 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c orizer will fail
28670 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d with an error m
28680 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 essage..**.** Wh
28690 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 en the callback
286a0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f returns [SQLITE_
286b0 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 OK], that means
286c0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a the operation.**
286d0 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b requested is ok
286e0 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c . ^When the cal
286f0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 lback returns [S
28700 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 QLITE_DENY], the
28710 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
28720 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 pare_v2()] or eq
28730 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 uivalent call th
28740 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 at triggered the
28750 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 .** authorizer w
28760 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e ill fail with an
28770 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 error message e
28780 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a xplaining that.*
28790 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 * access is deni
287a0 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ed. .**.** ^The
287b0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 first parameter
287c0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 to the authorize
287d0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 r callback is a
287e0 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 copy of the thir
287f0 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 d.** parameter t
28800 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 o the sqlite3_se
28810 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 t_authorizer() i
28820 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 nterface. ^The s
28830 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a econd parameter.
28840 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 ** to the callba
28850 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ck is an integer
28860 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 [SQLITE_COPY |
28870 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 action code] tha
28880 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 t specifies.** t
28890 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 he particular ac
288a0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f tion to be autho
288b0 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 rized. ^The thir
288c0 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 d through sixth
288d0 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f parameters.** to
288e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 the callback ar
288f0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 70 6f e either NULL po
28900 69 6e 74 65 72 73 20 6f 72 20 7a 65 72 6f 2d 74 inters or zero-t
28910 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 erminated string
28920 73 0a 2a 2a 20 74 68 61 74 20 63 6f 6e 74 61 69 s.** that contai
28930 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 64 65 74 n additional det
28940 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 ails about the a
28950 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 ction to be auth
28960 6f 72 69 7a 65 64 2e 0a 2a 2a 20 41 70 70 6c 69 orized..** Appli
28970 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 61 6c 77 cations must alw
28980 61 79 73 20 62 65 20 70 72 65 70 61 72 65 64 20 ays be prepared
28990 74 6f 20 65 6e 63 6f 75 6e 74 65 72 20 61 20 4e to encounter a N
289a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 6e 20 61 ULL pointer in a
289b0 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 74 68 69 ny.** of the thi
289c0 72 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 73 rd through the s
289d0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 ixth parameters
289e0 6f 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 of the authoriza
289f0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a tion callback..*
28a00 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 *.** ^If the act
28a10 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c ion code is [SQL
28a20 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 ITE_READ].** and
28a30 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
28a40 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 turns [SQLITE_IG
28a50 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a NORE] then the.*
28a60 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 * [prepared stat
28a70 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 ement] statement
28a80 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 is constructed
28a90 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a to substitute.**
28aa0 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e a NULL value in
28ab0 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 place of the ta
28ac0 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 ble column that
28ad0 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 would have.** be
28ae0 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 en read if [SQLI
28af0 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 TE_OK] had been
28b00 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b returned. The [
28b10 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a SQLITE_IGNORE].*
28b20 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 * return can be
28b30 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 used to deny an
28b40 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 untrusted user a
28b50 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 ccess to individ
28b60 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f ual.** columns o
28b70 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 57 f a table..** ^W
28b80 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 72 hen a table is r
28b90 65 66 65 72 65 6e 63 65 64 20 62 79 20 61 20 5b eferenced by a [
28ba0 53 45 4c 45 43 54 5d 20 62 75 74 20 6e 6f 20 63 SELECT] but no c
28bb0 6f 6c 75 6d 6e 20 76 61 6c 75 65 73 20 61 72 65 olumn values are
28bc0 0a 2a 2a 20 65 78 74 72 61 63 74 65 64 20 66 72 .** extracted fr
28bd0 6f 6d 20 74 68 61 74 20 74 61 62 6c 65 20 28 66 om that table (f
28be0 6f 72 20 65 78 61 6d 70 6c 65 20 69 6e 20 61 20 or example in a
28bf0 71 75 65 72 79 20 6c 69 6b 65 0a 2a 2a 20 22 53 query like.** "S
28c00 45 4c 45 43 54 20 63 6f 75 6e 74 28 2a 29 20 46 ELECT count(*) F
28c10 52 4f 4d 20 74 61 62 22 29 20 74 68 65 6e 20 74 ROM tab") then t
28c20 68 65 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d he [SQLITE_READ]
28c30 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c authorizer call
28c40 62 61 63 6b 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b back.** is invok
28c50 65 64 20 6f 6e 63 65 20 66 6f 72 20 74 68 61 74 ed once for that
28c60 20 74 61 62 6c 65 20 77 69 74 68 20 61 20 63 6f table with a co
28c70 6c 75 6d 6e 20 6e 61 6d 65 20 74 68 61 74 20 69 lumn name that i
28c80 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e s an empty strin
28c90 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 g..** ^If the ac
28ca0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 tion code is [SQ
28cb0 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 LITE_DELETE] and
28cc0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 the callback re
28cd0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 turns.** [SQLITE
28ce0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 _IGNORE] then th
28cf0 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 e [DELETE] opera
28d00 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 tion proceeds bu
28d10 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 t the.** [trunca
28d20 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d te optimization]
28d30 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 is disabled and
28d40 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 all rows are de
28d50 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c leted individual
28d60 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 ly..**.** An aut
28d70 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 horizer is used
28d80 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 when [sqlite3_pr
28d90 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e epare | preparin
28da0 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d g].** SQL statem
28db0 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 ents from an unt
28dc0 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 rusted source, t
28dd0 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 o ensure that th
28de0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 e SQL statements
28df0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 .** do not try t
28e00 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 o access data th
28e10 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 ey are not allow
28e20 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 ed to see, or th
28e30 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a at they do not.*
28e40 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 * try to execute
28e50 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 malicious state
28e60 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 ments that damag
28e70 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 e the database.
28e80 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c For.** example,
28e90 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 an application
28ea0 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 may allow a user
28eb0 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 to enter arbitr
28ec0 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 ary.** SQL queri
28ed0 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f es for evaluatio
28ee0 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e n by a database.
28ef0 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 But the applic
28f00 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f ation does.** no
28f10 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 t want the user
28f20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 to be able to ma
28f30 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 ke arbitrary cha
28f40 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 nges to the.** d
28f50 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 atabase. An aut
28f60 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 horizer could th
28f70 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 en be put in pla
28f80 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 ce while the.**
28f90 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c user-entered SQL
28fa0 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 is being [sqlit
28fb0 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 e3_prepare | pre
28fc0 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 pared] that.** d
28fd0 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 isallows everyth
28fe0 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 ing except [SELE
28ff0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a CT] statements..
29000 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f **.** Applicatio
29010 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 ns that need to
29020 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d process SQL from
29030 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 untrusted sourc
29040 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f es.** might also
29050 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 consider loweri
29060 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 ng resource limi
29070 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ts using [sqlite
29080 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 3_limit()].** an
29090 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 d limiting datab
290a0 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 ase size using t
290b0 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 he [max_page_cou
290c0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 nt] [PRAGMA].**
290d0 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 in addition to u
290e0 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a sing an authoriz
290f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 er..**.** ^(Only
29100 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 a single author
29110 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 izer can be in p
29120 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 lace on a databa
29130 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a se connection.**
29140 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 at a time. Eac
29150 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 h call to sqlite
29160 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 3_set_authorizer
29170 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a overrides the.*
29180 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e * previous call.
29190 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 )^ ^Disable the
291a0 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 authorizer by i
291b0 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c nstalling a NULL
291c0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 callback..** Th
291d0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 e authorizer is
291e0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 disabled by defa
291f0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 ult..**.** The a
29200 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 uthorizer callba
29210 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 ck must not do a
29220 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c nything that wil
29230 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 l modify.** the
29240 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
29250 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 ion that invoked
29260 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 the authorizer
29270 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 callback..** Not
29280 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f e that [sqlite3_
29290 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e prepare_v2()] an
292a0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 d [sqlite3_step(
292b0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 )] both modify t
292c0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 heir.** database
292d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 connections for
292e0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 the meaning of
292f0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 "modify" in this
29300 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a paragraph..**.*
29310 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 * ^When [sqlite3
29320 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 _prepare_v2()] i
29330 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 s used to prepar
29340 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 e a statement, t
29350 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 he.** statement
29360 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 might be re-prep
29370 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c ared during [sql
29380 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 ite3_step()] due
29390 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 to a .** schema
293a0 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c change. Hence,
293b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e the application
293c0 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 should ensure t
293d0 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 hat the.** corre
293e0 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 ct authorizer ca
293f0 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 llback remains i
29400 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 n place during t
29410 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 he [sqlite3_step
29420 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 ()]..**.** ^Note
29430 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 that the author
29440 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 izer callback is
29450 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 invoked only du
29460 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ring.** [sqlite3
29470 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 _prepare()] or i
29480 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 ts variants. Au
29490 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e thorization is n
294a0 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 ot.** performed
294b0 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 during statement
294c0 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b evaluation in [
294d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c sqlite3_step()],
294e0 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 unless.** as st
294f0 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 ated in the prev
29500 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 ious paragraph,
29510 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 sqlite3_step() i
29520 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 nvokes.** sqlite
29530 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 3_prepare_v2() t
29540 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 o reprepare a st
29550 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 atement after a
29560 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a schema change..*
29570 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
29580 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 sqlite3_set_aut
29590 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 horizer(. sqlit
295a0 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 e3*,. int (*xAu
295b0 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f th)(void*,int,co
295c0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 nst char*,const
295d0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 char*,const char
295e0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a *,const char*),.
295f0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 void *pUserDat
29600 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 a.);../*.** CAPI
29610 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 3REF: Authorizer
29620 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a Return Codes.**
29630 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
29640 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 _set_authorizer
29650 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c | authorizer cal
29660 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 lback function]
29670 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 must.** return e
29680 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b ither [SQLITE_OK
29690 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 ] or one of thes
296a0 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 e two constants
296b0 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 in order.** to s
296c0 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 ignal SQLite whe
296d0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 ther or not the
296e0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 action is permit
296f0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a ted. See the.**
29700 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 [sqlite3_set_au
29710 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f thorizer | autho
29720 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 rizer documentat
29730 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f ion] for additio
29740 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 nal.** informati
29750 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 on..**.** Note t
29760 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 hat SQLITE_IGNOR
29770 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 E is also used a
29780 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 s a [conflict re
29790 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a solution mode].*
297a0 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 * returned from
297b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 the [sqlite3_vta
297c0 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d b_on_conflict()]
297d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 interface..*/.#
297e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 define SQLITE_DE
297f0 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 NY 1 /* Abor
29800 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d t the SQL statem
29810 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f ent with an erro
29820 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c r */.#define SQL
29830 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f ITE_IGNORE 2 /
29840 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 * Don't allow ac
29850 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 cess, but don't
29860 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f generate an erro
29870 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 r */../*.** CAPI
29880 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 3REF: Authorizer
29890 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a Action Codes.**
298a0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 .** The [sqlite3
298b0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 _set_authorizer(
298c0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 )] interface reg
298d0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 isters a callbac
298e0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 k function.** th
298f0 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f at is invoked to
29900 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 authorize certa
29910 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 in SQL statement
29920 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a actions. The.*
29930 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 * second paramet
29940 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 er to the callba
29950 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 ck is an integer
29960 20 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 code that speci
29970 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 fies.** what act
29980 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 ion is being aut
29990 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 horized. These
299a0 61 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 are the integer
299b0 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 action codes tha
299c0 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 t.** the authori
299d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 zer callback may
299e0 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a be passed..**.*
299f0 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 * These action c
29a00 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 ode values signi
29a10 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 fy what kind of
29a20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 operation is to
29a30 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 be.** authorized
29a40 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 . The 3rd and 4
29a50 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f th parameters to
29a60 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 the authorizati
29a70 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 on.** callback f
29a80 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 unction will be
29a90 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 parameters or NU
29aa0 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 LL depending on
29ab0 77 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a which of these.*
29ac0 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 * codes is used
29ad0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 as the second pa
29ae0 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 rameter. ^(The
29af0 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 5th parameter to
29b00 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a the.** authoriz
29b10 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 er callback is t
29b20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 he name of the d
29b30 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c atabase ("main",
29b40 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e "temp",.** etc.
29b50 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e ) if applicable.
29b60 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 )^ ^The 6th par
29b70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 ameter to the au
29b80 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 thorizer callbac
29b90 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 k.** is the name
29ba0 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f of the inner-mo
29bb0 73 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 st trigger or vi
29bc0 65 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f ew that is respo
29bd0 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 nsible for.** th
29be0 65 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 e access attempt
29bf0 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 or NULL if this
29c00 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 access attempt
29c10 69 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d is directly from
29c20 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 .** top-level SQ
29c30 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a L code..*/./****
29c40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
29c50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a ****************
29c60 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a ******* 3rd ****
29c70 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a ******** 4th ***
29c80 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e ********/.#defin
29c90 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f e SQLITE_CREATE_
29ca0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 INDEX 1
29cb0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 /* Index Name
29cc0 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 Table Name
29cd0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
29ce0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 SQLITE_CREATE_T
29cf0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 ABLE 2
29d00 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
29d10 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
29d20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
29d30 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 SQLITE_CREATE_TE
29d40 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 MP_INDEX 3
29d50 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 /* Index Name
29d60 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 Table Name
29d70 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 */.#define S
29d80 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d QLITE_CREATE_TEM
29d90 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 P_TABLE 4
29da0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
29db0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 NULL
29dc0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
29dd0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 LITE_CREATE_TEMP
29de0 5f 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f _TRIGGER 5 /
29df0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 * Trigger Name
29e00 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 Table Name
29e10 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
29e20 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f ITE_CREATE_TEMP_
29e30 56 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a VIEW 6 /*
29e40 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 View Name
29e50 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
29e60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
29e70 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 TE_CREATE_TRIGGE
29e80 52 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 R 7 /*
29e90 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 Trigger Name
29ea0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
29eb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
29ec0 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 E_CREATE_VIEW
29ed0 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 8 /* V
29ee0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e iew Name N
29ef0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
29f00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
29f10 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 _DELETE
29f20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 9 /* Ta
29f30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 ble Name NU
29f40 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
29f50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
29f60 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 DROP_INDEX
29f70 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 10 /* Ind
29f80 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 ex Name Tab
29f90 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
29fa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 #define SQLITE_D
29fb0 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 ROP_TABLE
29fc0 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 11 /* Tabl
29fd0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c e Name NULL
29fe0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
29ff0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 define SQLITE_DR
2a000 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 OP_TEMP_INDEX
2a010 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 12 /* Index
2a020 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 Name Table
2a030 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 Name */.#d
2a040 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f efine SQLITE_DRO
2a050 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 P_TEMP_TABLE
2a060 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 13 /* Table
2a070 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 Name NULL
2a080 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 */.#de
2a090 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
2a0a0 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 _TEMP_TRIGGER
2a0b0 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 14 /* Trigger
2a0c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e Name Table N
2a0d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 ame */.#def
2a0e0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f ine SQLITE_DROP_
2a0f0 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 TEMP_VIEW
2a100 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 15 /* View Nam
2a110 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 e NULL
2a120 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 */.#defi
2a130 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 ne SQLITE_DROP_T
2a140 52 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 RIGGER 1
2a150 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 6 /* Trigger N
2a160 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d ame Table Nam
2a170 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e e */.#defin
2a180 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 e SQLITE_DROP_VI
2a190 45 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 EW 17
2a1a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 /* View Name
2a1b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 NULL
2a1c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 */.#define
2a1d0 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 SQLITE_INSERT
2a1e0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 18
2a1f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 /* Table Name
2a200 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 NULL
2a210 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 */.#define
2a220 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 SQLITE_PRAGMA
2a230 20 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 19
2a240 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 /* Pragma Name
2a250 20 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 1st arg or N
2a260 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 ULL */.#define S
2a270 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 QLITE_READ
2a280 20 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 20
2a290 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 /* Table Name
2a2a0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 Column Name
2a2b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 */.#define SQ
2a2c0 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 LITE_SELECT
2a2d0 20 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 21 /
2a2e0 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 * NULL
2a2f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 NULL
2a300 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c */.#define SQL
2a310 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 ITE_TRANSACTION
2a320 20 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 22 /*
2a330 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 Operation
2a340 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 NULL
2a350 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 */.#define SQLI
2a360 54 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 TE_UPDATE
2a370 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 23 /*
2a380 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 Table Name
2a390 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 Column Name
2a3a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2a3b0 45 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 E_ATTACH
2a3c0 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 24 /* F
2a3d0 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e ilename N
2a3e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a ULL *
2a3f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 /.#define SQLITE
2a400 5f 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 _DETACH
2a410 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 25 /* Da
2a420 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 tabase Name NU
2a430 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f LL */
2a440 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
2a450 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 ALTER_TABLE
2a460 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 26 /* Dat
2a470 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 abase Name Tab
2a480 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a le Name */.
2a490 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 #define SQLITE_R
2a4a0 45 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 EINDEX
2a4b0 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 27 /* Inde
2a4c0 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c x Name NULL
2a4d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 */.#
2a4e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e define SQLITE_AN
2a4f0 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 ALYZE
2a500 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 28 /* Table
2a510 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 Name NULL
2a520 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 */.#d
2a530 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 efine SQLITE_CRE
2a540 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 ATE_VTABLE
2a550 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 29 /* Table
2a560 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 Name Module
2a570 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 Name */.#de
2a580 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 fine SQLITE_DROP
2a590 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 _VTABLE
2a5a0 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 30 /* Table N
2a5b0 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 ame Module
2a5c0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 Name */.#def
2a5d0 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 ine SQLITE_FUNCT
2a5e0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 ION
2a5f0 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 31 /* NULL
2a600 20 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e Function
2a610 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 Name */.#defi
2a620 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f ne SQLITE_SAVEPO
2a630 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 INT 3
2a640 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 2 /* Operation
2a650 20 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 Savepoint
2a660 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e Name */.#defin
2a670 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 e SQLITE_COPY
2a680 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0
2a690 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 /* No longer
2a6a0 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 used */.#define
2a6b0 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 SQLITE_RECURSIVE
2a6c0 20 20 20 20 20 20 20 20 20 20 20 20 33 33 20 20 33
2a6d0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 /* NULL
2a6e0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 NULL
2a6f0 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 */../*.** CA
2a700 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 PI3REF: Tracing
2a710 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 And Profiling Fu
2a720 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f nctions.** METHO
2a730 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a D: sqlite3.**.**
2a740 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
2a750 61 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 20 are deprecated.
2a760 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 Use the [sqlite3
2a770 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 _trace_v2()] int
2a780 65 72 66 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 erface.** instea
2a790 64 20 6f 66 20 74 68 65 20 72 6f 75 74 69 6e 65 d of the routine
2a7a0 73 20 64 65 73 63 72 69 62 65 64 20 68 65 72 65 s described here
2a7b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f ..**.** These ro
2a7c0 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 utines register
2a7d0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
2a7e0 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 ns that can be u
2a7f0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 sed for.** traci
2a800 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 ng and profiling
2a810 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f the execution o
2a820 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 f SQL statements
2a830 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c ..**.** ^The cal
2a840 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 lback function r
2a850 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c egistered by sql
2a860 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 ite3_trace() is
2a870 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 invoked at.** va
2a880 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e rious times when
2a890 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e an SQL statemen
2a8a0 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 t is being run b
2a8b0 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 y [sqlite3_step(
2a8c0 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 )]..** ^The sqli
2a8d0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c te3_trace() call
2a8e0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
2a8f0 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e with a UTF-8 ren
2a900 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a dering of the.**
2a910 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 SQL statement t
2a920 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 ext as the state
2a930 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e ment first begin
2a940 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 s executing..**
2a950 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c ^(Additional sql
2a960 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c ite3_trace() cal
2a970 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 lbacks might occ
2a980 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 ur.** as each tr
2a990 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 iggered subprogr
2a9a0 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 am is entered.
2a9b0 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f The callbacks fo
2a9c0 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f r triggers.** co
2a9d0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 ntain a UTF-8 SQ
2a9e0 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 L comment that i
2a9f0 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 dentifies the tr
2aa00 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 igger.)^.**.** T
2aa10 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 he [SQLITE_TRACE
2aa20 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d _SIZE_LIMIT] com
2aa30 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e pile-time option
2aa40 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 can be used to
2aa50 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e limit.** the len
2aa60 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 gth of [bound pa
2aa70 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 rameter] expansi
2aa80 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 on in the output
2aa90 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 of sqlite3_trac
2aaa0 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 e()..**.** ^The
2aab0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f callback functio
2aac0 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 n registered by
2aad0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 sqlite3_profile(
2aae0 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 ) is invoked.**
2aaf0 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 as each SQL stat
2ab00 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 ement finishes.
2ab10 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 ^The profile ca
2ab20 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a llback contains.
2ab30 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 ** the original
2ab40 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 statement text a
2ab50 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f nd an estimate o
2ab60 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d f wall-clock tim
2ab70 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 e.** of how long
2ab80 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 that statement
2ab90 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 took to run. ^T
2aba0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 he profile callb
2abb0 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 ack.** time is i
2abc0 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 n units of nanos
2abd0 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 econds, however
2abe0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c the current impl
2abf0 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 ementation.** is
2ac00 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 only capable of
2ac10 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 millisecond res
2ac20 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 olution so the s
2ac30 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 ix least signifi
2ac40 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 cant.** digits i
2ac50 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d n the time are m
2ac60 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 eaningless. Fut
2ac70 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 ure versions of
2ac80 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 SQLite.** might
2ac90 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 provide greater
2aca0 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 resolution on th
2acb0 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 e profiler callb
2acc0 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c ack. The.** sql
2acd0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 ite3_profile() f
2ace0 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 unction is consi
2acf0 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 dered experiment
2ad00 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 al and is.** sub
2ad10 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 ject to change i
2ad20 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e n future version
2ad30 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a s of SQLite..*/.
2ad40 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 SQLITE_API SQLIT
2ad50 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 E_DEPRECATED voi
2ad60 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 d *sqlite3_trace
2ad70 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f (sqlite3*,. vo
2ad80 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 id(*xTrace)(void
2ad90 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 *,const char*),
2ada0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 void*);.SQLITE_A
2adb0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 PI SQLITE_DEPREC
2adc0 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 ATED void *sqlit
2add0 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 e3_profile(sqlit
2ade0 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 e3*,. void(*xP
2adf0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f rofile)(void*,co
2ae00 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 nst char*,sqlite
2ae10 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 3_uint64), void*
2ae20 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 );../*.** CAPI3R
2ae30 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76 EF: SQL Trace Ev
2ae40 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 ent Codes.** KEY
2ae50 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 WORDS: SQLITE_TR
2ae60 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 ACE.**.** These
2ae70 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69 constants identi
2ae80 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76 fy classes of ev
2ae90 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65 ents that can be
2aea0 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 monitored.** us
2aeb0 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 ing the [sqlite3
2aec0 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61 _trace_v2()] tra
2aed0 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 cing logic. The
2aee0 20 4d 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 M argument.** t
2aef0 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 o [sqlite3_trace
2af00 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 5d 20 69 73 _v2(D,M,X,P)] is
2af10 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e an OR-ed combin
2af20 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 ation of one or
2af30 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 more of.** the f
2af40 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e ollowing constan
2af50 74 73 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 ts. ^The first
2af60 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 argument to the
2af70 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a trace callback.*
2af80 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 * is one of the
2af90 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 following consta
2afa0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 nts..**.** New t
2afb0 72 61 63 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 racing constants
2afc0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e may be added in
2afd0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 future releases
2afe0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 ..**.** ^A trace
2aff0 20 63 61 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f callback has fo
2b000 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 ur arguments: xC
2b010 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 allback(T,C,P,X)
2b020 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75 ..** ^The T argu
2b030 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 ment is one of t
2b040 68 65 20 69 6e 74 65 67 65 72 20 74 79 70 65 20 he integer type
2b050 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 codes above..**
2b060 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20 ^The C argument
2b070 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 is a copy of the
2b080 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 context pointer
2b090 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 passed in as th
2b0a0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61 72 67 75 e.** fourth argu
2b0b0 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 ment to [sqlite3
2b0c0 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a _trace_v2()]..**
2b0d0 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67 The P and X arg
2b0e0 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 uments are point
2b0f0 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e ers whose meanin
2b100 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a gs depend on T..
2b110 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b **.** <dl>.** [[
2b120 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d SQLITE_TRACE_STM
2b130 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 T]] <dt>SQLITE_T
2b140 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a RACE_STMT</dt>.*
2b150 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 * <dd>^An SQLITE
2b160 5f 54 52 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c _TRACE_STMT call
2b170 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 back is invoked
2b180 77 68 65 6e 20 61 20 70 72 65 70 61 72 65 64 20 when a prepared
2b190 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 statement.** fir
2b1a0 73 74 20 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e st begins runnin
2b1b0 67 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 g and possibly a
2b1c0 74 20 6f 74 68 65 72 20 74 69 6d 65 73 20 64 75 t other times du
2b1d0 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 ring the.** exec
2b1e0 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 ution of the pre
2b1f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2c pared statement,
2b200 20 73 75 63 68 20 61 73 20 61 74 20 74 68 65 20 such as at the
2b210 73 74 61 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a start of each.**
2b220 20 74 72 69 67 67 65 72 20 73 75 62 70 72 6f 67 trigger subprog
2b230 72 61 6d 2e 20 5e 54 68 65 20 50 20 61 72 67 75 ram. ^The P argu
2b240 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
2b250 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 r to the.** [pre
2b260 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d pared statement]
2b270 2e 20 5e 54 68 65 20 58 20 61 72 67 75 6d 65 6e . ^The X argumen
2b280 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 t is a pointer t
2b290 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 o a string which
2b2a0 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e 65 78 70 .** is the unexp
2b2b0 61 6e 64 65 64 20 53 51 4c 20 74 65 78 74 20 6f anded SQL text o
2b2c0 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 f the prepared s
2b2d0 74 61 74 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 tatement or an S
2b2e0 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 QL comment .** t
2b2f0 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 hat indicates th
2b300 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 e invocation of
2b310 61 20 74 72 69 67 67 65 72 2e 20 20 5e 54 68 65 a trigger. ^The
2b320 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f callback can co
2b330 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d mpute.** the sam
2b340 65 20 74 65 78 74 20 74 68 61 74 20 77 6f 75 6c e text that woul
2b350 64 20 68 61 76 65 20 62 65 65 6e 20 72 65 74 75 d have been retu
2b360 72 6e 65 64 20 62 79 20 74 68 65 20 6c 65 67 61 rned by the lega
2b370 63 79 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 cy [sqlite3_trac
2b380 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 e()].** interfac
2b390 65 20 62 79 20 75 73 69 6e 67 20 74 68 65 20 58 e by using the X
2b3a0 20 61 72 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 argument when X
2b3b0 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 2d 2d begins with "--
2b3c0 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a " and invoking.*
2b3d0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 70 61 6e * [sqlite3_expan
2b3e0 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 ded_sql(P)] othe
2b3f0 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 rwise..**.** [[S
2b400 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 QLITE_TRACE_PROF
2b410 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 ILE]] <dt>SQLITE
2b420 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f _TRACE_PROFILE</
2b430 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 dt>.** <dd>^An S
2b440 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 QLITE_TRACE_PROF
2b450 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f ILE callback pro
2b460 76 69 64 65 73 20 61 70 70 72 6f 78 69 6d 61 74 vides approximat
2b470 65 6c 79 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 ely the same.**
2b480 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 information as i
2b490 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 s provided by th
2b4a0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 e [sqlite3_profi
2b4b0 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a le()] callback..
2b4c0 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 ** ^The P argume
2b4d0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 nt is a pointer
2b4e0 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 to the [prepared
2b4f0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 statement] and
2b500 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e the.** X argumen
2b510 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 t points to a 64
2b520 2d 62 69 74 20 69 6e 74 65 67 65 72 20 77 68 69 -bit integer whi
2b530 63 68 20 69 73 20 74 68 65 20 65 73 74 69 6d 61 ch is the estima
2b540 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 ted of.** the nu
2b550 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f mber of nanoseco
2b560 6e 64 20 74 68 61 74 20 74 68 65 20 70 72 65 70 nd that the prep
2b570 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 74 ared statement t
2b580 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e ook to run..** ^
2b590 54 68 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 The SQLITE_TRACE
2b5a0 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 _PROFILE callbac
2b5b0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 k is invoked whe
2b5c0 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 n the statement
2b5d0 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 finishes..**.**
2b5e0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 [[SQLITE_TRACE_R
2b5f0 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f OW]] <dt>SQLITE_
2b600 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a TRACE_ROW</dt>.*
2b610 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 * <dd>^An SQLITE
2b620 5f 54 52 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 _TRACE_ROW callb
2b630 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 ack is invoked w
2b640 68 65 6e 65 76 65 72 20 61 20 70 72 65 70 61 72 henever a prepar
2b650 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 ed.** statement
2b660 67 65 6e 65 72 61 74 65 73 20 61 20 73 69 6e 67 generates a sing
2b670 6c 65 20 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 le row of result
2b680 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 . .** ^The P ar
2b690 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e gument is a poin
2b6a0 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 ter to the [prep
2b6b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
2b6c0 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 and the.** X arg
2b6d0 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e ument is unused.
2b6e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
2b6f0 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 TRACE_CLOSE]] <d
2b700 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 t>SQLITE_TRACE_C
2b710 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 LOSE</dt>.** <dd
2b720 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 >^An SQLITE_TRAC
2b730 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b E_CLOSE callback
2b740 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e is invoked when
2b750 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 a database.** c
2b760 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 onnection closes
2b770 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 ..** ^The P argu
2b780 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 ment is a pointe
2b790 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 r to the [databa
2b7a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f se connection] o
2b7b0 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 bject.** and the
2b7c0 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 X argument is u
2b7d0 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a nused..** </dl>.
2b7e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 */.#define SQLIT
2b7f0 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 20 20 20 E_TRACE_STMT
2b800 20 20 20 30 78 30 31 0a 23 64 65 66 69 6e 65 20 0x01.#define
2b810 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f SQLITE_TRACE_PRO
2b820 46 49 4c 45 20 20 20 20 30 78 30 32 0a 23 64 65 FILE 0x02.#de
2b830 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 fine SQLITE_TRAC
2b840 45 5f 52 4f 57 20 20 20 20 20 20 20 20 30 78 30 E_ROW 0x0
2b850 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 4.#define SQLITE
2b860 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 _TRACE_CLOSE
2b870 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 0x08../*.** CA
2b880 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72 61 63 PI3REF: SQL Trac
2b890 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 e Hook.** METHOD
2b8a0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 : sqlite3.**.**
2b8b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 ^The sqlite3_tra
2b8c0 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 ce_v2(D,M,X,P) i
2b8d0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 nterface registe
2b8e0 72 73 20 61 20 74 72 61 63 65 20 63 61 6c 6c 62 rs a trace callb
2b8f0 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 ack.** function
2b900 58 20 61 67 61 69 6e 73 74 20 5b 64 61 74 61 62 X against [datab
2b910 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 ase connection]
2b920 44 2c 20 75 73 69 6e 67 20 70 72 6f 70 65 72 74 D, using propert
2b930 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 y mask M.** and
2b940 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 context pointer
2b950 50 2e 20 20 5e 49 66 20 74 68 65 20 58 20 63 61 P. ^If the X ca
2b960 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c llback is.** NUL
2b970 4c 20 6f 72 20 69 66 20 74 68 65 20 4d 20 6d 61 L or if the M ma
2b980 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e sk is zero, then
2b990 20 74 72 61 63 69 6e 67 20 69 73 20 64 69 73 61 tracing is disa
2b9a0 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 bled. The.** M
2b9b0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 argument should
2b9c0 62 65 20 74 68 65 20 62 69 74 77 69 73 65 20 4f be the bitwise O
2b9d0 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e R-ed combination
2b9e0 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d of.** zero or m
2b9f0 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 ore [SQLITE_TRAC
2ba00 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a E] constants..**
2ba10 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 .** ^Each call t
2ba20 6f 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 o either sqlite3
2ba30 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 _trace() or sqli
2ba40 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 6f te3_trace_v2() o
2ba50 76 65 72 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 verrides .** (ca
2ba60 6e 63 65 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 ncels) any prior
2ba70 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 calls to sqlite
2ba80 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73 71 6c 3_trace() or sql
2ba90 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 2e ite3_trace_v2().
2baa0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 .**.** ^The X ca
2bab0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 llback is invoke
2bac0 64 20 77 68 65 6e 65 76 65 72 20 61 6e 79 20 6f d whenever any o
2bad0 66 20 74 68 65 20 65 76 65 6e 74 73 20 69 64 65 f the events ide
2bae0 6e 74 69 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d ntified by .** m
2baf0 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 ask M occur. ^T
2bb00 68 65 20 69 6e 74 65 67 65 72 20 72 65 74 75 72 he integer retur
2bb10 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 n value from the
2bb20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 callback is cur
2bb30 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 rently.** ignore
2bb40 64 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 6d d, though this m
2bb50 61 79 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 ay change in fut
2bb60 75 72 65 20 72 65 6c 65 61 73 65 73 2e 20 20 43 ure releases. C
2bb70 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 allback.** imple
2bb80 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c mentations shoul
2bb90 64 20 72 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f d return zero to
2bba0 20 65 6e 73 75 72 65 20 66 75 74 75 72 65 20 63 ensure future c
2bbb0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a ompatibility..**
2bbc0 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c .** ^A trace cal
2bbd0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 lback is invoked
2bbe0 20 77 69 74 68 20 66 6f 75 72 20 61 72 67 75 6d with four argum
2bbf0 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 ents: callback(T
2bc00 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 ,C,P,X)..** ^The
2bc10 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f T argument is o
2bc20 6e 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 ne of the [SQLIT
2bc30 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 E_TRACE].** cons
2bc40 74 61 6e 74 73 20 74 6f 20 69 6e 64 69 63 61 74 tants to indicat
2bc50 65 20 77 68 79 20 74 68 65 20 63 61 6c 6c 62 61 e why the callba
2bc60 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a ck was invoked..
2bc70 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65 ** ^The C argume
2bc80 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 nt is a copy of
2bc90 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e the context poin
2bca0 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e ter..** The P an
2bcb0 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 d X arguments ar
2bcc0 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 e pointers whose
2bcd0 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 meanings depend
2bce0 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 on T..**.** The
2bcf0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 sqlite3_trace_v
2bd00 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 2() interface is
2bd10 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 72 65 70 intended to rep
2bd20 6c 61 63 65 20 74 68 65 20 6c 65 67 61 63 79 0a lace the legacy.
2bd30 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 ** interfaces [s
2bd40 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 20 qlite3_trace()]
2bd50 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f and [sqlite3_pro
2bd60 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 file()], both of
2bd70 20 77 68 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 which.** are de
2bd80 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a 53 51 4c precated..*/.SQL
2bd90 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 ITE_API int sqli
2bda0 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a 20 20 te3_trace_v2(.
2bdb0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e 73 69 sqlite3*,. unsi
2bdc0 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20 69 6e gned uMask,. in
2bdd0 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28 75 6e t(*xCallback)(un
2bde0 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76 6f 69 signed,void*,voi
2bdf0 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76 6f 69 d*,void*),. voi
2be00 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a 0a 2a d *pCtx.);../*.*
2be10 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 * CAPI3REF: Quer
2be20 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 y Progress Callb
2be30 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 acks.** METHOD:
2be40 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 sqlite3.**.** ^T
2be50 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 he sqlite3_progr
2be60 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c ess_handler(D,N,
2be70 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 X,P) interface c
2be80 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 auses the callba
2be90 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 ck.** function X
2bea0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 to be invoked p
2beb0 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 eriodically duri
2bec0 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 ng long running
2bed0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c calls to.** [sql
2bee0 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 ite3_exec()], [s
2bef0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 qlite3_step()] a
2bf00 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f nd [sqlite3_get_
2bf10 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 table()] for.**
2bf20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2bf30 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 ion D. An examp
2bf40 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a le use for this.
2bf50 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 ** interface is
2bf60 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 to keep a GUI up
2bf70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c dated during a l
2bf80 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a arge query..**.*
2bf90 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 * ^The parameter
2bfa0 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 P is passed thr
2bfb0 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 ough as the only
2bfc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 parameter to th
2bfd0 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 e .** callback f
2bfe0 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 unction X. ^The
2bff0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 parameter N is
2c000 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 the approximate
2c010 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 number of .** [v
2c020 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 irtual machine i
2c030 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 nstructions] tha
2c040 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 t are evaluated
2c050 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 between successi
2c060 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e ve.** invocation
2c070 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 s of the callbac
2c080 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c k X. ^If N is l
2c090 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 ess than one the
2c0a0 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a n the progress.*
2c0b0 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 * handler is dis
2c0c0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e abled..**.** ^On
2c0d0 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 ly a single prog
2c0e0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 ress handler may
2c0f0 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f be defined at o
2c100 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b ne time per.** [
2c110 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2c120 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 ion]; setting a
2c130 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e new progress han
2c140 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 dler cancels the
2c150 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 .** old one. ^S
2c160 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 etting parameter
2c170 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 X to NULL disab
2c180 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 les the progress
2c190 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 handler..** ^Th
2c1a0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c e progress handl
2c1b0 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 er is also disab
2c1c0 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e led by setting N
2c1d0 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 to a value less
2c1e0 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a .** than 1..**.*
2c1f0 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 * ^If the progre
2c200 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 ss callback retu
2c210 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 rns non-zero, th
2c220 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a e operation is.*
2c230 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 * interrupted.
2c240 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e This feature can
2c250 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c be used to impl
2c260 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 ement a.** "Canc
2c270 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 el" button on a
2c280 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 GUI progress dia
2c290 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 log box..**.** T
2c2a0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 he progress hand
2c2b0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 ler callback mus
2c2c0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e t not do anythin
2c2d0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 g that will modi
2c2e0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 fy.** the databa
2c2f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 se connection th
2c300 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 at invoked the p
2c310 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e rogress handler.
2c320 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 .** Note that [s
2c330 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
2c340 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 2()] and [sqlite
2c350 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 3_step()] both m
2c360 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 odify their.** d
2c370 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2c380 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e ons for the mean
2c390 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 ing of "modify"
2c3a0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 in this paragrap
2c3b0 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f h..**.*/.SQLITE_
2c3c0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 API void sqlite3
2c3d0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 _progress_handle
2c3e0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c r(sqlite3*, int,
2c3f0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 int(*)(void*),
2c400 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 void*);../*.** C
2c410 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 API3REF: Opening
2c420 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 A New Database
2c430 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f Connection.** CO
2c440 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 NSTRUCTOR: sqlit
2c450 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 e3.**.** ^These
2c460 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e routines open an
2c470 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 SQLite database
2c480 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 file as specifi
2c490 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 ed by the .** fi
2c4a0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e lename argument.
2c4b0 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 ^The filename a
2c4c0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 rgument is inter
2c4d0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 preted as UTF-8
2c4e0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f for.** sqlite3_o
2c4f0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 pen() and sqlite
2c500 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 3_open_v2() and
2c510 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 as UTF-16 in the
2c520 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 native byte.**
2c530 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 order for sqlite
2c540 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 3_open16(). ^(A
2c550 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2c560 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 tion] handle is
2c570 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 usually.** retur
2c580 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 ned in *ppDb, ev
2c590 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f en if an error o
2c5a0 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 ccurs. The only
2c5b0 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 exception is th
2c5c0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 at.** if SQLite
2c5d0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c is unable to all
2c5e0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 ocate memory to
2c5f0 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 hold the [sqlite
2c600 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 3] object,.** a
2c610 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 NULL will be wri
2c620 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 tten into *ppDb
2c630 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 instead of a poi
2c640 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c nter to the [sql
2c650 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e ite3].** object.
2c660 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 )^ ^(If the data
2c670 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 base is opened (
2c680 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 and/or created)
2c690 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 successfully, th
2c6a0 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b en.** [SQLITE_OK
2c6b0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 ] is returned.
2c6c0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 Otherwise an [er
2c6d0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 ror code] is ret
2c6e0 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a urned.)^ ^The.**
2c6f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 [sqlite3_errmsg
2c700 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f ()] or [sqlite3_
2c710 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 errmsg16()] rout
2c720 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 ines can be used
2c730 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e to obtain.** an
2c740 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 English languag
2c750 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 e description of
2c760 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f the error follo
2c770 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f wing a failure o
2c780 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 f any.** of the
2c790 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 sqlite3_open() r
2c7a0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e outines..**.** ^
2c7b0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f The default enco
2c7c0 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 ding will be UTF
2c7d0 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 -8 for databases
2c7e0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a created using.*
2c7f0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 * sqlite3_open()
2c800 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e or sqlite3_open
2c810 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 _v2(). ^The def
2c820 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f ault encoding fo
2c830 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 r databases.** c
2c840 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c reated using sql
2c850 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 ite3_open16() wi
2c860 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 ll be UTF-16 in
2c870 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 the native byte
2c880 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 order..**.** Whe
2c890 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 ther or not an e
2c8a0 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e rror occurs when
2c8b0 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 it is opened, r
2c8c0 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f esources.** asso
2c8d0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 ciated with the
2c8e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 [database connec
2c8f0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f tion] handle sho
2c900 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 uld be released
2c910 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 by.** passing it
2c920 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f to [sqlite3_clo
2c930 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 se()] when it is
2c940 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 no longer requi
2c950 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 red..**.** The s
2c960 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 qlite3_open_v2()
2c970 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 interface works
2c980 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 like sqlite3_op
2c990 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 en().** except t
2c9a0 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 hat it accepts t
2c9b0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 wo additional pa
2c9c0 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 rameters for add
2c9d0 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a itional control.
2c9e0 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 ** over the new
2c9f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 database connect
2ca00 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 ion. ^(The flag
2ca10 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a s parameter to.*
2ca20 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 * sqlite3_open_v
2ca30 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 2() can take one
2ca40 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f of.** the follo
2ca50 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 wing three value
2ca60 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f s, optionally co
2ca70 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 mbined with the
2ca80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
2ca90 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 _NOMUTEX], [SQLI
2caa0 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 TE_OPEN_FULLMUTE
2cab0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e X], [SQLITE_OPEN
2cac0 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a _SHAREDCACHE],.*
2cad0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 * [SQLITE_OPEN_P
2cae0 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e RIVATECACHE], an
2caf0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 d/or [SQLITE_OPE
2cb00 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a N_URI] flags:)^.
2cb10 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 **.** <dl>.** ^(
2cb20 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e <dt>[SQLITE_OPEN
2cb30 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a _READONLY]</dt>.
2cb40 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 ** <dd>The datab
2cb50 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e ase is opened in
2cb60 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e read-only mode.
2cb70 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 If the databas
2cb80 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c e does not.** al
2cb90 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 ready exist, an
2cba0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 error is returne
2cbb0 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 d.</dd>)^.**.**
2cbc0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 ^(<dt>[SQLITE_OP
2cbd0 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 EN_READWRITE]</d
2cbe0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 t>.** <dd>The da
2cbf0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 tabase is opened
2cc00 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 for reading and
2cc10 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 writing if poss
2cc20 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 ible, or reading
2cc30 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 .** only if the
2cc40 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 file is write pr
2cc50 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f otected by the o
2cc60 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e perating system.
2cc70 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 In either.** c
2cc80 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 ase the database
2cc90 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 must already ex
2cca0 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 ist, otherwise a
2ccb0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 n error is retur
2ccc0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a ned.</dd>)^.**.*
2ccd0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f * ^(<dt>[SQLITE_
2cce0 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 OPEN_READWRITE]
2ccf0 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 | [SQLITE_OPEN_C
2cd00 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c REATE]</dt>.** <
2cd10 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 dd>The database
2cd20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 is opened for re
2cd30 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e ading and writin
2cd40 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 g, and is create
2cd50 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 d if.** it does
2cd60 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 not already exis
2cd70 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 t. This is the b
2cd80 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 ehavior that is
2cd90 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a always used for.
2cda0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 ** sqlite3_open(
2cdb0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 ) and sqlite3_op
2cdc0 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a en16().</dd>)^.*
2cdd0 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 * </dl>.**.** If
2cde0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 the 3rd paramet
2cdf0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
2ce00 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f en_v2() is not o
2ce10 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d ne of the.** com
2ce20 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 binations shown
2ce30 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 above optionally
2ce40 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f combined with o
2ce50 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f ther.** [SQLITE_
2ce60 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 OPEN_READONLY |
2ce70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 SQLITE_OPEN_* bi
2ce80 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 ts].** then the
2ce90 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 behavior is unde
2cea0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 fined..**.** ^If
2ceb0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 the [SQLITE_OPE
2cec0 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 N_NOMUTEX] flag
2ced0 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 is set, then the
2cee0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2cef0 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e tion.** opens in
2cf00 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 the multi-threa
2cf10 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 d [threading mod
2cf20 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 e] as long as th
2cf30 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a e single-thread.
2cf40 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 ** mode has not
2cf50 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 been set at comp
2cf60 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 ile-time or star
2cf70 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 t-time. ^If the
2cf80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e .** [SQLITE_OPEN
2cf90 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 _FULLMUTEX] flag
2cfa0 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 is set then the
2cfb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 database connec
2cfc0 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e tion opens.** in
2cfd0 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 the serialized
2cfe0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d [threading mode]
2cff0 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 unless single-t
2d000 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 hread was.** pre
2d010 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 viously selected
2d020 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 at compile-time
2d030 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a or start-time..
2d040 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f ** ^The [SQLITE_
2d050 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
2d060 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 ] flag causes th
2d070 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 e database conne
2d080 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 ction to be.** e
2d090 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b ligible to use [
2d0a0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 shared cache mod
2d0b0 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f e], regardless o
2d0c0 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 f whether or not
2d0d0 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 shared.** cache
2d0e0 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e is enabled usin
2d0f0 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c g [sqlite3_enabl
2d100 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 e_shared_cache()
2d110 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c ]. ^The.** [SQL
2d120 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
2d130 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 CACHE] flag caus
2d140 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 es the database
2d150 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f connection to no
2d160 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 t.** participate
2d170 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 in [shared cach
2d180 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 e mode] even if
2d190 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a it is enabled..*
2d1a0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 *.** ^The fourth
2d1b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 parameter to sq
2d1c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 lite3_open_v2()
2d1d0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 is the name of t
2d1e0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 he.** [sqlite3_v
2d1f0 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 fs] object that
2d200 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 defines the oper
2d210 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 ating system int
2d220 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 erface that.** t
2d230 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 he new database
2d240 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c connection shoul
2d250 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 d use. ^If the
2d260 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 fourth parameter
2d270 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f is.** a NULL po
2d280 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 inter then the d
2d290 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f efault [sqlite3_
2d2a0 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 vfs] object is u
2d2b0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 sed..**.** ^If t
2d2c0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 he filename is "
2d2d0 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 :memory:", then
2d2e0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f a private, tempo
2d2f0 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 rary in-memory d
2d300 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 atabase.** is cr
2d310 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f eated for the co
2d320 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 nnection. ^This
2d330 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 in-memory datab
2d340 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 ase will vanish
2d350 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 when.** the data
2d360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 base connection
2d370 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 is closed. Futu
2d380 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 re versions of S
2d390 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d QLite might.** m
2d3a0 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 ake use of addit
2d3b0 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 ional special fi
2d3c0 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 lenames that beg
2d3d0 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 in with the ":"
2d3e0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 character..** It
2d3f0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 is recommended
2d400 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 that when a data
2d410 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 base filename ac
2d420 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 tually does begi
2d430 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 n with.** a ":"
2d440 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 character you sh
2d450 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 ould prefix the
2d460 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 filename with a
2d470 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 pathname such as
2d480 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 .** "./" to avoi
2d490 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a d ambiguity..**.
2d4a0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e ** ^If the filen
2d4b0 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 ame is an empty
2d4c0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 string, then a p
2d4d0 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 rivate, temporar
2d4e0 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 y.** on-disk dat
2d4f0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 abase will be cr
2d500 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 eated. ^This pr
2d510 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 ivate database w
2d520 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 ill be.** automa
2d530 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 tically deleted
2d540 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 as soon as the d
2d550 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
2d560 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a on is closed..**
2d570 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 .** [[URI filena
2d580 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f mes in sqlite3_o
2d590 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 pen()]] <h3>URI
2d5a0 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a Filenames</h3>.*
2d5b0 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 *.** ^If [URI fi
2d5c0 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 lename] interpre
2d5d0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 tation is enable
2d5e0 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e d, and the filen
2d5f0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 ame argument.**
2d600 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c begins with "fil
2d610 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 e:", then the fi
2d620 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 lename is interp
2d630 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 reted as a URI.
2d640 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 ^URI.** filename
2d650 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 interpretation
2d660 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 is enabled if th
2d670 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 e [SQLITE_OPEN_U
2d680 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 RI] flag is.** s
2d690 65 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 et in the third
2d6a0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 argument to sqli
2d6b0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f te3_open_v2(), o
2d6c0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 r if it has.** b
2d6d0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 een enabled glob
2d6e0 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b ally using the [
2d6f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 SQLITE_CONFIG_UR
2d700 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 I] option with t
2d710 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 he.** [sqlite3_c
2d720 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 onfig()] method
2d730 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 or by the [SQLIT
2d740 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 E_USE_URI] compi
2d750 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a le-time option..
2d760 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 ** URI filename
2d770 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 interpretation i
2d780 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 s turned off.**
2d790 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 by default, but
2d7a0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 future releases
2d7b0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 of SQLite might
2d7c0 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e enable URI filen
2d7d0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 ame.** interpret
2d7e0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 ation by default
2d7f0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c . See "[URI fil
2d800 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 enames]" for add
2d810 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 itional.** infor
2d820 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 mation..**.** UR
2d830 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 I filenames are
2d840 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 parsed according
2d850 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 to RFC 3986. ^I
2d860 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 f the URI contai
2d870 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 ns an.** authori
2d880 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 ty, then it must
2d890 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d be either an em
2d8a0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 pty string or th
2d8b0 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f e string .** "lo
2d8c0 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 calhost". ^If th
2d8d0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e e authority is n
2d8e0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 ot an empty stri
2d8f0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 ng or "localhost
2d900 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 ", an .** error
2d910 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 is returned to t
2d920 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 he caller. ^The
2d930 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 fragment compone
2d940 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 nt of a URI, if
2d950 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 .** present, is
2d960 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e ignored..**.** ^
2d970 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 SQLite uses the
2d980 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f path component o
2d990 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 f the URI as the
2d9a0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 name of the dis
2d9b0 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 k file.** which
2d9c0 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 contains the dat
2d9d0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 abase. ^If the p
2d9e0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 ath begins with
2d9f0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c a '/' character,
2da00 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 .** then it is
2da10 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 interpreted as a
2da20 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e n absolute path.
2da30 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f ^If the path do
2da40 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a es not begin .**
2da50 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 with a '/' (mea
2da60 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 ning that the au
2da70 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 thority section
2da80 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 is omitted from
2da90 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e the URI).** then
2daa0 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 the path is int
2dab0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 erpreted as a re
2dac0 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a lative path. .**
2dad0 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 ^(On windows, t
2dae0 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 he first compone
2daf0 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 nt of an absolut
2db00 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 e path .** is a
2db10 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 drive specificat
2db20 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e ion (e.g. "C:").
2db30 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 )^.**.** [[core
2db40 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 URI query parame
2db50 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 ters]].** The qu
2db60 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 ery component of
2db70 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 a URI may conta
2db80 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 in parameters th
2db90 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 at are interpret
2dba0 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 ed.** either by
2dbb0 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f SQLite itself, o
2dbc0 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 r by a [VFS | cu
2dbd0 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 stom VFS impleme
2dbe0 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c ntation]..** SQL
2dbf0 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c ite and its buil
2dc00 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 t-in [VFSes] int
2dc10 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f erpret the.** fo
2dc20 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 llowing query pa
2dc30 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 rameters:.**.**
2dc40 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c <ul>.** <li> <
2dc50 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 b>vfs</b>: ^The
2dc60 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 "vfs" parameter
2dc70 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 may be used to s
2dc80 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 pecify the name
2dc90 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 of.** a VFS
2dca0 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 object that prov
2dcb0 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 ides the operati
2dcc0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 ng system interf
2dcd0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a ace that should.
2dce0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 ** be used t
2dcf0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 o access the dat
2dd00 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 abase file on di
2dd10 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 sk. ^If this opt
2dd20 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a ion is set to.**
2dd30 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 an empty st
2dd40 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 ring the default
2dd50 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 VFS object is u
2dd60 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 sed. ^Specifying
2dd70 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 an unknown.**
2dd80 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 VFS is an err
2dd90 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f or. ^If sqlite3_
2dda0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 open_v2() is use
2ddb0 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 d and the vfs op
2ddc0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 tion is.** p
2ddd0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 resent, then the
2dde0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 VFS specified b
2ddf0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b y the option tak
2de00 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 es precedence ov
2de10 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 er.** the va
2de20 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 lue passed as th
2de30 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
2de40 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 er to sqlite3_op
2de50 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 en_v2()..**.**
2de60 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 <li> <b>mode</b
2de70 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 >: ^(The mode pa
2de80 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 rameter may be s
2de90 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f et to either "ro
2dea0 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 ", "rw",.**
2deb0 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 "rwc", or "memor
2dec0 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 y". Attempting t
2ded0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 o set it to any
2dee0 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a other value is.*
2def0 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e * an error)^
2df00 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 . .** ^If "r
2df10 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c o" is specified,
2df20 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 then the databa
2df30 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 se is opened for
2df40 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 read-only .**
2df50 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 access, just
2df60 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 as if the [SQLIT
2df70 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d E_OPEN_READONLY]
2df80 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 flag had been s
2df90 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 et in the .**
2dfa0 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 third argument
2dfb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e to sqlite3_open
2dfc0 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d _v2(). ^If the m
2dfd0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 ode option is se
2dfe0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 t to .** "rw
2dff0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 ", then the data
2e000 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 base is opened f
2e010 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 or read-write (b
2e020 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a ut not create) .
2e030 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 ** access, a
2e040 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e s if SQLITE_OPEN
2e050 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 _READWRITE (but
2e060 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f not SQLITE_OPEN_
2e070 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 CREATE) had .**
2e080 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 been set. ^V
2e090 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 alue "rwc" is eq
2e0a0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 uivalent to sett
2e0b0 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 ing both .**
2e0c0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 SQLITE_OPEN_REA
2e0d0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 DWRITE and SQLIT
2e0e0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 E_OPEN_CREATE.
2e0f0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 ^If the mode opt
2e100 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 ion is.** se
2e110 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 t to "memory" th
2e120 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 en a pure [in-me
2e130 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 mory database] t
2e140 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a hat never reads.
2e150 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 ** or writes
2e160 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 from disk is us
2e170 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 ed. ^It is an er
2e180 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 ror to specify a
2e190 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 value for.**
2e1a0 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d the mode param
2e1b0 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 eter that is les
2e1c0 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 s restrictive th
2e1d0 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 an that specifie
2e1e0 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 d by.** the
2e1f0 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 flags passed in
2e200 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 the third parame
2e210 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f ter to sqlite3_o
2e220 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 pen_v2()..**.**
2e230 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c <li> <b>cache<
2e240 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 /b>: ^The cache
2e250 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 parameter may be
2e260 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 set to either "
2e270 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 shared" or.**
2e280 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 "private". ^Se
2e290 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 tting it to "sha
2e2a0 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 red" is equivale
2e2b0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 nt to setting th
2e2c0 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f e.** SQLITE_
2e2d0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
2e2e0 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 bit in the flag
2e2f0 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 s argument passe
2e300 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 d to.** sqli
2e310 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e te3_open_v2(). ^
2e320 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 Setting the cach
2e330 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 e parameter to "
2e340 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 private" is .**
2e350 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 equivalent t
2e360 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 o setting the SQ
2e370 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 LITE_OPEN_PRIVAT
2e380 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 ECACHE bit..**
2e390 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f ^If sqlite3_o
2e3a0 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 pen_v2() is used
2e3b0 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 and the "cache"
2e3c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 parameter is pr
2e3d0 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 esent in.**
2e3e0 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 a URI filename,
2e3f0 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 its value overri
2e400 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 des any behavior
2e410 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 requested by se
2e420 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c tting.** SQL
2e430 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 ITE_OPEN_PRIVATE
2e440 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f CACHE or SQLITE_
2e450 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 OPEN_SHAREDCACHE
2e460 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c flag..**.** <l
2e470 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 i> <b>psow</b>:
2e480 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 ^The psow parame
2e490 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 ter indicates wh
2e4a0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 ether or not the
2e4b0 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 .** [powersa
2e4c0 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 fe overwrite] pr
2e4d0 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 operty does or d
2e4e0 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f oes not apply to
2e4f0 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 the.** stor
2e500 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 age media on whi
2e510 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ch the database
2e520 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a file resides..**
2e530 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c .** <li> <b>nol
2e540 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f ock</b>: ^The no
2e550 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 lock parameter i
2e560 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 s a boolean quer
2e570 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 y parameter.**
2e580 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 which if set
2e590 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f disables file lo
2e5a0 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 cking in rollbac
2e5b0 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e k journal modes.
2e5c0 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 This.** is
2e5d0 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 useful for acce
2e5e0 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 ssing a database
2e5f0 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d on a filesystem
2e600 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a that does not.*
2e610 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f * support lo
2e620 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a cking. Caution:
2e630 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 Database corru
2e640 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 ption might resu
2e650 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 lt if two.**
2e660 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 or more process
2e670 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 es write to the
2e680 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e same database an
2e690 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f d any one of tho
2e6a0 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 se.** proces
2e6b0 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d ses uses nolock=
2e6c0 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 1..**.** <li> <
2e6d0 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a b>immutable</b>:
2e6e0 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 ^The immutable
2e6f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 parameter is a b
2e700 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 oolean query.**
2e710 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 parameter th
2e720 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 at indicates tha
2e730 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 t the database f
2e740 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e ile is stored on
2e750 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c .** read-onl
2e760 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 y media. ^When
2e770 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 immutable is set
2e780 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 , SQLite assumes
2e790 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 that the.**
2e7a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 database file c
2e7b0 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 annot be changed
2e7c0 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 , even by a proc
2e7d0 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a ess with higher.
2e7e0 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 ** privilege
2e7f0 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 , and so the dat
2e800 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 abase is opened
2e810 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c read-only and al
2e820 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 l locking.**
2e830 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 and change dete
2e840 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 ction is disable
2e850 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 d. Caution: Set
2e860 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 ting the immutab
2e870 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 le.** proper
2e880 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 ty on a database
2e890 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 file that does
2e8a0 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 in fact change c
2e8b0 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 an result.**
2e8c0 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 in incorrect qu
2e8d0 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f ery results and/
2e8e0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 or [SQLITE_CORRU
2e8f0 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 PT] errors..**
2e900 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 See also: [SQ
2e910 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 LITE_IOCAP_IMMUT
2e920 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 ABLE]..**
2e930 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 .** </ul>.**.**
2e940 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 ^Specifying an u
2e950 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 nknown parameter
2e960 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f in the query co
2e970 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 mponent of a URI
2e980 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 is not an.** er
2e990 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 ror. Future ver
2e9a0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 sions of SQLite
2e9b0 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 might understand
2e9c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 additional quer
2e9d0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e y.** parameters.
2e9e0 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 See "[query pa
2e9f0 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 rameters with sp
2ea00 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f ecial meaning to
2ea10 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a SQLite]" for.**
2ea20 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f additional info
2ea30 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b rmation..**.** [
2ea40 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 [URI filename ex
2ea50 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 amples]] <h3>URI
2ea60 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c filename exampl
2ea70 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 es</h3>.**.** <t
2ea80 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 able border="1"
2ea90 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c align=center cel
2eaa0 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c lpadding=5>.** <
2eab0 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 tr><th> URI file
2eac0 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c names <th> Resul
2ead0 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 ts.** <tr><td> f
2eae0 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e ile:data.db <td>
2eaf0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 .** Op
2eb00 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 en the file "dat
2eb10 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 a.db" in the cur
2eb20 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a rent directory..
2eb30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
2eb40 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 :/home/fred/data
2eb50 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 .db<br>.**
2eb60 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 file:///home
2eb70 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 /fred/data.db <b
2eb80 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 r> .**
2eb90 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 file://localhost
2eba0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e /home/fred/data.
2ebb0 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a db <br> <td> .**
2ebc0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 Open t
2ebd0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 he database file
2ebe0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 "/home/fred/dat
2ebf0 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 a.db"..** <tr><t
2ec00 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 d> file://darkst
2ec10 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 ar/home/fred/dat
2ec20 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 a.db <td> .**
2ec30 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e An error.
2ec40 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e "darkstar" is n
2ec50 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 ot a recognized
2ec60 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 authority..** <t
2ec70 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 r><td style="whi
2ec80 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 te-space:nowrap"
2ec90 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 > .** f
2eca0 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 ile:///C:/Docume
2ecb0 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 nts%20and%20Sett
2ecc0 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f ings/fred/Deskto
2ecd0 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 p/data.db.**
2ece0 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e <td> Windows on
2ecf0 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c ly: Open the fil
2ed00 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 e "data.db" on f
2ed10 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e red's desktop on
2ed20 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 drive.**
2ed30 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 C:. Note that
2ed40 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e the %20 escapin
2ed50 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c g in this exampl
2ed60 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c e is not strictl
2ed70 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e y .** n
2ed80 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 ecessary - space
2ed90 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 characters can
2eda0 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c be used literall
2edb0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e y.** in
2edc0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a URI filenames..
2edd0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 ** <tr><td> file
2ede0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f :data.db?mode=ro
2edf0 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c &cache=private <
2ee00 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 td> .**
2ee10 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 Open file "data
2ee20 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 .db" in the curr
2ee30 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f ent directory fo
2ee40 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 r read-only acce
2ee50 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 ss..**
2ee60 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 Regardless of wh
2ee70 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 ether or not sha
2ee80 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 red-cache mode i
2ee90 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 s enabled by.**
2eea0 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 default
2eeb0 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 , use a private
2eec0 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 cache..** <tr><t
2eed0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 d> file:/home/fr
2eee0 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 ed/data.db?vfs=u
2eef0 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e nix-dotfile <td>
2ef00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 .** Ope
2ef10 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 n file "/home/fr
2ef20 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 ed/data.db". Use
2ef30 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 the special VFS
2ef40 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a "unix-dotfile".
2ef50 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 ** that
2ef60 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 uses dot-files
2ef70 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 in place of posi
2ef80 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 x advisory locki
2ef90 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 ng..** <tr><td>
2efa0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 file:data.db?mod
2efb0 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 e=readonly <td>
2efc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 .** An
2efd0 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 error. "readonly
2efe0 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 " is not a valid
2eff0 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 option for the
2f000 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 "mode" parameter
2f010 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a ..** </table>.**
2f020 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 .** ^URI hexadec
2f030 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 imal escape sequ
2f040 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 ences (%HH) are
2f050 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e supported within
2f060 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a the path and.**
2f070 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 query component
2f080 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 s of a URI. A he
2f090 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 xadecimal escape
2f0a0 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 sequence consis
2f0b0 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 ts of a.** perce
2f0c0 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 nt sign - "%" -
2f0d0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 followed by exac
2f0e0 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 tly two hexadeci
2f0f0 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 mal digits .** s
2f100 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 pecifying an oct
2f110 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 et value. ^Befor
2f120 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 e the path or qu
2f130 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f ery components o
2f140 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e f a.** URI filen
2f150 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 ame are interpre
2f160 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e ted, they are en
2f170 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d coded using UTF-
2f180 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 8 and all .** he
2f190 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 xadecimal escape
2f1a0 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 sequences repla
2f1b0 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 ced by a single
2f1c0 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 byte containing
2f1d0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e the.** correspon
2f1e0 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 ding octet. If t
2f1f0 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 his process gene
2f200 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 rates an invalid
2f210 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c UTF-8 encoding,
2f220 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 .** the results
2f230 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a are undefined..*
2f240 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 *.** <b>Note to
2f250 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f Windows users:</
2f260 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 b> The encoding
2f270 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 used for the fi
2f280 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a lename argument.
2f290 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 ** of sqlite3_op
2f2a0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 en() and sqlite3
2f2b0 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 _open_v2() must
2f2c0 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 be UTF-8, not wh
2f2d0 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 atever.** codepa
2f2e0 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 ge is currently
2f2f0 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 defined. Filena
2f300 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 mes containing i
2f310 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 nternational.**
2f320 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 characters must
2f330 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 be converted to
2f340 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 UTF-8 prior to p
2f350 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f assing them into
2f360 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e .** sqlite3_open
2f370 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 () or sqlite3_op
2f380 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c en_v2()..**.** <
2f390 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 b>Note to Window
2f3a0 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a s Runtime users:
2f3b0 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 </b> The tempor
2f3c0 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 ary directory mu
2f3d0 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 st be set.** pri
2f3e0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 or to calling sq
2f3f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 lite3_open() or
2f400 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 sqlite3_open_v2(
2f410 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 ). Otherwise, v
2f420 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 arious.** featur
2f430 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 es that require
2f440 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f the use of tempo
2f450 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 rary files may f
2f460 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 ail..**.** See a
2f470 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 lso: [sqlite3_te
2f480 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f mp_directory].*/
2f490 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2f4a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 sqlite3_open(.
2f4b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 const char *file
2f4c0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 name, /* Datab
2f4d0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 ase filename (UT
2f4e0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 F-8) */. sqlite
2f4f0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 3 **ppDb
2f500 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 /* OUT: SQLite
2f510 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b db handle */.);
2f520 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
2f530 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a sqlite3_open16(.
2f540 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 const void *fi
2f550 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 lename, /* Dat
2f560 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 abase filename (
2f570 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c UTF-16) */. sql
2f580 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 ite3 **ppDb
2f590 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c /* OUT: SQL
2f5a0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f ite db handle */
2f5b0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 .);.SQLITE_API i
2f5c0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f nt sqlite3_open_
2f5d0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 v2(. const char
2f5e0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a *filename, /*
2f5f0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 Database filena
2f600 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 me (UTF-8) */.
2f610 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 sqlite3 **ppDb,
2f620 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 /* OUT:
2f630 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 SQLite db handle
2f640 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c */. int flags,
2f650 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a /*
2f660 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 Flags */. cons
2f670 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 t char *zVfs
2f680 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 /* Name of V
2f690 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 FS module to use
2f6a0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 */.);../*.** CA
2f6b0 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 PI3REF: Obtain V
2f6c0 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 alues For URI Pa
2f6d0 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 rameters.**.** T
2f6e0 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 hese are utility
2f6f0 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 routines, usefu
2f700 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 l to VFS impleme
2f710 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 ntations, that c
2f720 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 heck.** to see i
2f730 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c f a database fil
2f740 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 e was a URI that
2f750 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 contained a spe
2f760 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 cific query .**
2f770 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 parameter, and i
2f780 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 f so obtains the
2f790 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 value of that q
2f7a0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a uery parameter..
2f7b0 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 **.** If F is th
2f7c0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e e database filen
2f7d0 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 ame pointer pass
2f7e0 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 ed into the xOpe
2f7f0 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a n() method of .*
2f800 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e * a VFS implemen
2f810 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 tation when the
2f820 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 flags parameter
2f830 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f to xOpen() has o
2f840 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f ne or .** more o
2f850 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 f the [SQLITE_OP
2f860 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 EN_URI] or [SQLI
2f870 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d TE_OPEN_MAIN_DB]
2f880 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a bits set and.**
2f890 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f P is the name o
2f8a0 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 f the query para
2f8b0 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 meter, then.** s
2f8c0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d qlite3_uri_param
2f8d0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e eter(F,P) return
2f8e0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 s the value of t
2f8f0 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 he P.** paramete
2f900 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f r if it exists o
2f910 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 r a NULL pointer
2f920 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 if P does not a
2f930 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 ppear as a .** q
2f940 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f uery parameter o
2f950 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 n F. If P is a
2f960 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 query parameter
2f970 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 of F.** has no e
2f980 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 xplicit value, t
2f990 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f hen sqlite3_uri_
2f9a0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 parameter(F,P) r
2f9b0 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e eturns.** a poin
2f9c0 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 ter to an empty
2f9d0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 string..**.** Th
2f9e0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f e sqlite3_uri_bo
2f9f0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 olean(F,P,B) rou
2fa00 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 tine assumes tha
2fa10 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e t P is a boolean
2fa20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e .** parameter an
2fa30 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 d returns true (
2fa40 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 1) or false (0)
2fa50 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 according to the
2fa60 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 value.** of P.
2fa70 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 The sqlite3_uri
2fa80 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 _boolean(F,P,B)
2fa90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 routine returns
2faa0 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a true (1) if the.
2fab0 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 ** value of quer
2fac0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 y parameter P is
2fad0 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 one of "yes", "
2fae0 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 true", or "on" i
2faf0 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 n any.** case or
2fb00 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 if the value be
2fb10 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d gins with a non-
2fb20 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 zero number. Th
2fb30 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 e .** sqlite3_ur
2fb40 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 i_boolean(F,P,B)
2fb50 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e routines return
2fb60 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 s false (0) if t
2fb70 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 he value of.** q
2fb80 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 uery parameter P
2fb90 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c is one of "no",
2fba0 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 "false", or "of
2fbb0 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f f" in any case o
2fbc0 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 r.** if the valu
2fbd0 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 e begins with a
2fbe0 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 numeric zero. I
2fbf0 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 f P is not a que
2fc00 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 ry.** parameter
2fc10 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 on F or if the v
2fc20 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 alue of P is doe
2fc30 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 s not match any
2fc40 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c of the.** above,
2fc50 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 then sqlite3_ur
2fc60 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 i_boolean(F,P,B)
2fc70 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e returns (B!=0).
2fc80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 .**.** The sqlit
2fc90 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 e3_uri_int64(F,P
2fca0 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 ,D) routine conv
2fcb0 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f erts the value o
2fcc0 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 f P into a.** 64
2fcd0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 -bit signed inte
2fce0 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 ger and returns
2fcf0 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 that integer, or
2fd00 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 D if P does not
2fd10 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 .** exist. If t
2fd20 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 he value of P is
2fd30 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 something other
2fd40 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 than an integer
2fd50 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 , then.** zero i
2fd60 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a s returned..** .
2fd70 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c ** If F is a NUL
2fd80 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 L pointer, then
2fd90 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 sqlite3_uri_para
2fda0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 meter(F,P) retur
2fdb0 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 ns NULL and.** s
2fdc0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 qlite3_uri_boole
2fdd0 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e an(F,P,B) return
2fde0 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f s B. If F is no
2fdf0 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 t a NULL pointer
2fe00 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 and.** is not a
2fe10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 database file p
2fe20 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 athname pointer
2fe30 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 that SQLite pass
2fe40 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 ed into the xOpe
2fe50 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c n.** VFS method,
2fe60 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 then the behavi
2fe70 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 or of this routi
2fe80 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 ne is undefined
2fe90 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 and probably.**
2fea0 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a undesirable..*/.
2feb0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 SQLITE_API const
2fec0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 char *sqlite3_u
2fed0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e ri_parameter(con
2fee0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 st char *zFilena
2fef0 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a me, const char *
2ff00 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f zParam);.SQLITE_
2ff10 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f API int sqlite3_
2ff20 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 uri_boolean(cons
2ff30 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 t char *zFile, c
2ff40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 onst char *zPara
2ff50 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 m, int bDefault)
2ff60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c ;.SQLITE_API sql
2ff70 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 ite3_int64 sqlit
2ff80 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e e3_uri_int64(con
2ff90 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 st char*, const
2ffa0 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 char*, sqlite3_i
2ffb0 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 nt64);.../*.** C
2ffc0 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 API3REF: Error C
2ffd0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 odes And Message
2ffe0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
2fff0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 ite3.**.** ^If t
30000 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 he most recent s
30010 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c qlite3_* API cal
30020 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 l associated wit
30030 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 h .** [database
30040 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 connection] D fa
30050 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 iled, then the s
30060 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 qlite3_errcode(D
30070 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 ) interface.** r
30080 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 eturns the numer
30090 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d ic [result code]
300a0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 or [extended re
300b0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 sult code] for t
300c0 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e hat.** API call.
300d0 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 .** If the most
300e0 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 recent API call
300f0 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a was successful,.
30100 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 ** then the retu
30110 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 rn value from sq
30120 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 lite3_errcode()
30130 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a is undefined..**
30140 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 ^The sqlite3_ex
30150 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 tended_errcode()
30160 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 .** interface is
30170 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 the same except
30180 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 that it always
30190 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 returns the .**
301a0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 [extended result
301b0 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e code] even when
301c0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 extended result
301d0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 codes are.** di
301e0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 sabled..**.** ^T
301f0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 he sqlite3_errms
30200 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f g() and sqlite3_
30210 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 errmsg16() retur
30220 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 n English-langua
30230 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 ge.** text that
30240 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 describes the er
30250 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 ror, as either U
30260 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 TF-8 or UTF-16 r
30270 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
30280 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 ^(Memory to hold
30290 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 the error messa
302a0 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e ge string is man
302b0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e aged internally.
302c0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 .** The applicat
302d0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 ion does not nee
302e0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 d to worry about
302f0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 freeing the res
30300 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c ult..** However,
30310 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e the error strin
30320 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 g might be overw
30330 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f ritten or deallo
30340 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 cated by.** subs
30350 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 equent calls to
30360 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 other SQLite int
30370 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 erface functions
30380 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 .)^.**.** ^The s
30390 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 qlite3_errstr()
303a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e interface return
303b0 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 s the English-la
303c0 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 nguage text.** t
303d0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 hat describes th
303e0 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c e [result code],
303f0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 as UTF-8..** ^(
30400 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 Memory to hold t
30410 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 he error message
30420 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 string is manag
30430 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a ed internally.**
30440 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 and must not be
30450 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 freed by the ap
30460 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a plication)^..**.
30470 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 ** When the seri
30480 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e alized [threadin
30490 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 g mode] is in us
304a0 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 e, it might be t
304b0 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 he.** case that
304c0 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f a second error o
304d0 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 ccurs on a separ
304e0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 ate thread in be
304f0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d tween.** the tim
30500 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 e of the first e
30510 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c rror and the cal
30520 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 l to these inter
30530 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 faces..** When t
30540 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 hat happens, the
30550 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 second error wi
30560 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 ll be reported s
30570 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e ince these.** in
30580 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 terfaces always
30590 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 report the most
305a0 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 recent result.
305b0 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 To avoid.** this
305c0 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 , each thread ca
305d0 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 n obtain exclusi
305e0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 ve use of the [d
305f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 atabase connecti
30600 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f on] D.** by invo
30610 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 king [sqlite3_mu
30620 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 tex_enter]([sqli
30630 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 te3_db_mutex](D)
30640 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 ) before beginni
30650 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 ng.** to use D a
30660 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c nd invoking [sql
30670 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 ite3_mutex_leave
30680 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 ]([sqlite3_db_mu
30690 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a tex](D)) after.*
306a0 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 * all calls to t
306b0 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 he interfaces li
306c0 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f sted here are co
306d0 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 mpleted..**.** I
306e0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 f an interface f
306f0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 ails with SQLITE
30700 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 _MISUSE, that me
30710 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 ans the interfac
30720 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 e.** was invoked
30730 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 incorrectly by
30740 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e the application.
30750 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 In that case,
30760 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 the.** error cod
30770 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 e and message ma
30780 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 y or may not be
30790 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 set..*/.SQLITE_A
307a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 PI int sqlite3_e
307b0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a rrcode(sqlite3 *
307c0 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 db);.SQLITE_API
307d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 int sqlite3_exte
307e0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c nded_errcode(sql
307f0 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 ite3 *db);.SQLIT
30800 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 E_API const char
30810 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 *sqlite3_errmsg
30820 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 (sqlite3*);.SQLI
30830 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 TE_API const voi
30840 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 d *sqlite3_errms
30850 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 g16(sqlite3*);.S
30860 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 QLITE_API const
30870 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 char *sqlite3_er
30880 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a rstr(int);../*.*
30890 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 * CAPI3REF: Prep
308a0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f ared Statement O
308b0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 bject.** KEYWORD
308c0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 S: {prepared sta
308d0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 tement} {prepare
308e0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a d statements}.**
308f0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 .** An instance
30900 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 of this object r
30910 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 epresents a sing
30920 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 le SQL statement
30930 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 that.** has bee
30940 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 n compiled into
30950 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 binary form and
30960 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65 is ready to be e
30970 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 valuated..**.**
30980 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 Think of each SQ
30990 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61 L statement as a
309a0 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74 separate comput
309b0 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 er program. The
309c0 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c .** original SQL
309d0 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20 text is source
309e0 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65 code. A prepare
309f0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 d statement obje
30a00 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f ct .** is the co
30a10 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f mpiled object co
30a20 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 de. All SQL mus
30a30 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69 t be converted i
30a40 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 nto a.** prepare
30a50 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f d statement befo
30a60 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e re it can be run
30a70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 ..**.** The life
30a80 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70 -cycle of a prep
30a90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f ared statement o
30aa0 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f bject usually go
30ab0 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a es like this:.**
30ac0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e .** <ol>.** <li>
30ad0 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70 Create the prep
30ae0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f ared statement o
30af0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c bject using [sql
30b00 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
30b10 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 )]..** <li> Bind
30b20 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 values to [para
30b30 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 meters] using th
30b40 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
30b50 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 ().** inter
30b60 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 faces..** <li> R
30b70 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 un the SQL by ca
30b80 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 lling [sqlite3_s
30b90 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f tep()] one or mo
30ba0 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 re times..** <li
30bb0 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70 > Reset the prep
30bc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 ared statement u
30bd0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 sing [sqlite3_re
30be0 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 set()] then go b
30bf0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 ack.** to s
30c00 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 tep 2. Do this
30c10 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d zero or more tim
30c20 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 es..** <li> Dest
30c30 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 roy the object u
30c40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 sing [sqlite3_fi
30c50 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f nalize()]..** </
30c60 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ol>.*/.typedef s
30c70 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74 truct sqlite3_st
30c80 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b mt sqlite3_stmt;
30c90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
30ca0 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 : Run-time Limit
30cb0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c s.** METHOD: sql
30cc0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 ite3.**.** ^(Thi
30cd0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f s interface allo
30ce0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 ws the size of v
30cf0 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 arious construct
30d00 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a s to be limited.
30d10 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 ** on a connecti
30d20 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e on by connection
30d30 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 basis. The fir
30d40 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 st parameter is
30d50 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 the.** [database
30d60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f connection] who
30d70 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 se limit is to b
30d80 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 e set or queried
30d90 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 . The.** second
30da0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e parameter is on
30db0 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 e of the [limit
30dc0 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 categories] that
30dd0 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 define a.** cla
30de0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 ss of constructs
30df0 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 to be size limi
30e00 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 ted. The third
30e10 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 parameter is the
30e20 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f .** new limit fo
30e30 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 r that construct
30e40 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 .)^.**.** ^If th
30e50 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 e new limit is a
30e60 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 negative number
30e70 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 , the limit is u
30e80 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 nchanged..** ^(F
30e90 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 or each limit ca
30ea0 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 tegory SQLITE_LI
30eb0 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 MIT_<i>NAME</i>
30ec0 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b there is a .** [
30ed0 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 limits | hard up
30ee0 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 per bound].** se
30ef0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d t at compile-tim
30f00 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 e by a C preproc
30f10 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c essor macro call
30f20 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 ed.** [limits |
30f30 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 SQLITE_MAX_<i>NA
30f40 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 ME</i>]..** (The
30f50 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 "_LIMIT_" in th
30f60 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 e name is change
30f70 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e d to "_MAX_".))^
30f80 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f .** ^Attempts to
30f90 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 increase a limi
30fa0 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 t above its hard
30fb0 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 upper bound are
30fc0 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 .** silently tru
30fd0 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 ncated to the ha
30fe0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a rd upper bound..
30ff0 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 **.** ^Regardles
31000 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 s of whether or
31010 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 not the limit wa
31020 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a s changed, the .
31030 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 ** [sqlite3_limi
31040 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 t()] interface r
31050 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 eturns the prior
31060 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 value of the li
31070 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 mit..** ^Hence,
31080 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 to find the curr
31090 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c ent value of a l
310a0 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 imit without cha
310b0 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d nging it,.** sim
310c0 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 ply invoke this
310d0 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74 interface with t
310e0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 he third paramet
310f0 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a er set to -1..**
31100 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d .** Run-time lim
31110 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 its are intended
31120 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c for use in appl
31130 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 ications that ma
31140 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 nage.** both the
31150 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 ir own internal
31160 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 database and als
31170 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74 o databases that
31180 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a are controlled.
31190 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 ** by untrusted
311a0 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 external sources
311b0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 . An example ap
311c0 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 plication might
311d0 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 be a.** web brow
311e0 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73 ser that has its
311f0 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 own databases f
31200 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f or storing histo
31210 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 ry and.** separa
31220 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e te databases con
31230 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 trolled by JavaS
31240 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f cript applicatio
31250 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a ns downloaded.**
31260 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 off the Interne
31270 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c t. The internal
31280 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 databases can b
31290 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c e given the.** l
312a0 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 arge, default li
312b0 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 mits. Databases
312c0 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 managed by exte
312d0 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e rnal sources can
312e0 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 .** be given muc
312f0 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 h smaller limits
31300 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 designed to pre
31310 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 vent a denial of
31320 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 service.** atta
31330 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 ck. Developers
31340 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 might also want
31350 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 to use the [sqli
31360 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a te3_set_authoriz
31370 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 er()].** interfa
31380 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f ce to further co
31390 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 ntrol untrusted
313a0 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f SQL. The size o
313b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a f the database.*
313c0 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 * created by an
313d0 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74 untrusted script
313e0 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 can be containe
313f0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b d using the.** [
31400 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 max_page_count]
31410 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 [PRAGMA]..**.**
31420 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d New run-time lim
31430 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 it categories ma
31440 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 y be added in fu
31450 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a ture releases..*
31460 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
31470 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 sqlite3_limit(s
31480 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c qlite3*, int id,
31490 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f int newVal);../
314a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 *.** CAPI3REF: R
314b0 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 un-Time Limit Ca
314c0 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 tegories.** KEYW
314d0 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 ORDS: {limit cat
314e0 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 egory} {*limit c
314f0 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a ategories}.**.**
31500 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 These constants
31510 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 define various
31520 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 performance limi
31530 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 ts.** that can b
31540 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e e lowered at run
31550 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c -time using [sql
31560 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a ite3_limit()]..*
31570 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f * The synopsis o
31580 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f f the meanings o
31590 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 f the various li
315a0 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 mits is shown be
315b0 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e low..** Addition
315c0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 al information i
315d0 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b s available at [
315e0 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 limits | Limits
315f0 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a in SQLite]..**.*
31600 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 * <dl>.** [[SQLI
31610 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d TE_LIMIT_LENGTH]
31620 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c ] ^(<dt>SQLITE_L
31630 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e IMIT_LENGTH</dt>
31640 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 .** <dd>The maxi
31650 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 mum size of any
31660 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f string or BLOB o
31670 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 r table row, in
31680 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a bytes.<dd>)^.**.
31690 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
316a0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e T_SQL_LENGTH]] ^
316b0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
316c0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 T_SQL_LENGTH</dt
316d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
316e0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 imum length of a
316f0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c n SQL statement,
31700 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 in bytes.</dd>)
31710 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
31720 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 _LIMIT_COLUMN]]
31730 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d ^(<dt>SQLITE_LIM
31740 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a IT_COLUMN</dt>.*
31750 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
31760 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 m number of colu
31770 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 mns in a table d
31780 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 efinition or in
31790 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 the.** result se
317a0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 t of a [SELECT]
317b0 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e or the maximum n
317c0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 umber of columns
317d0 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 in an index.**
317e0 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 or in an ORDER B
317f0 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c Y or GROUP BY cl
31800 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a ause.</dd>)^.**.
31810 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 ** [[SQLITE_LIMI
31820 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e T_EXPR_DEPTH]] ^
31830 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
31840 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 T_EXPR_DEPTH</dt
31850 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 >.** <dd>The max
31860 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 imum depth of th
31870 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 e parse tree on
31880 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c any expression.<
31890 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
318a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 QLITE_LIMIT_COMP
318b0 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 OUND_SELECT]] ^(
318c0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 <dt>SQLITE_LIMIT
318d0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 _COMPOUND_SELECT
318e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
318f0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 maximum number
31900 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f of terms in a co
31910 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 mpound SELECT st
31920 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a atement.</dd>)^.
31930 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c **.** [[SQLITE_L
31940 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e IMIT_VDBE_OP]] ^
31950 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
31960 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a T_VDBE_OP</dt>.*
31970 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 * <dd>The maximu
31980 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 m number of inst
31990 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 ructions in a vi
319a0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 rtual machine pr
319b0 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f ogram.** used to
319c0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 implement an SQ
319d0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 L statement. If
319e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
319f0 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 74 68 e_v2()] or.** th
31a00 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74 72 69 e equivalent tri
31a10 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 73 es to allocate s
31a20 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20 74 68 pace for more th
31a30 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f 70 63 an this many opc
31a40 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73 69 6e odes.** in a sin
31a50 67 6c 65 20 70 72 65 70 61 72 65 64 20 73 74 61 gle prepared sta
31a60 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c 49 54 tement, an SQLIT
31a70 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20 69 73 E_NOMEM error is
31a80 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 returned.</dd>)
31a90 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 ^.**.** [[SQLITE
31aa0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f _LIMIT_FUNCTION_
31ab0 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 ARG]] ^(<dt>SQLI
31ac0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
31ad0 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 N_ARG</dt>.** <d
31ae0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 d>The maximum nu
31af0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 mber of argument
31b00 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e s on a function.
31b10 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b </dd>)^.**.** [[
31b20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 SQLITE_LIMIT_ATT
31b30 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 ACHED]] ^(<dt>SQ
31b40 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 LITE_LIMIT_ATTAC
31b50 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e HED</dt>.** <dd>
31b60 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 The maximum numb
31b70 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 er of [ATTACH |
31b80 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 attached databas
31b90 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a es].)^</dd>.**.*
31ba0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 * [[SQLITE_LIMIT
31bb0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 _LIKE_PATTERN_LE
31bc0 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e NGTH]].** ^(<dt>
31bd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b SQLITE_LIMIT_LIK
31be0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 E_PATTERN_LENGTH
31bf0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 </dt>.** <dd>The
31c00 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 maximum length
31c10 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 of the pattern a
31c20 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b rgument to the [
31c30 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f LIKE] or.** [GLO
31c40 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 B] operators.</d
31c50 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c d>)^.**.** [[SQL
31c60 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 ITE_LIMIT_VARIAB
31c70 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e LE_NUMBER]].** ^
31c80 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 (<dt>SQLITE_LIMI
31c90 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 T_VARIABLE_NUMBE
31ca0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 R</dt>.** <dd>Th
31cb0 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 e maximum index
31cc0 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 number of any [p
31cd0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 arameter] in an
31ce0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e SQL statement.)^
31cf0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f .**.** [[SQLITE_
31d00 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 LIMIT_TRIGGER_DE
31d10 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 PTH]] ^(<dt>SQLI
31d20 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 TE_LIMIT_TRIGGER
31d30 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c _DEPTH</dt>.** <
31d40 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 dd>The maximum d
31d50 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f epth of recursio
31d60 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c n for triggers.<
31d70 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 /dd>)^.**.** [[S
31d80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b QLITE_LIMIT_WORK
31d90 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c ER_THREADS]] ^(<
31da0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f dt>SQLITE_LIMIT_
31db0 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f WORKER_THREADS</
31dc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d dt>.** <dd>The m
31dd0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 aximum number of
31de0 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 auxiliary worke
31df0 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20 61 r threads that a
31e00 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 single.** [prep
31e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
31e20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 may start.</dd>)
31e30 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 ^.** </dl>.*/.#d
31e40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d efine SQLITE_LIM
31e50 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 IT_LENGTH
31e60 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 0.#
31e70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 define SQLITE_LI
31e80 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 MIT_SQL_LENGTH
31e90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 1.
31ea0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c #define SQLITE_L
31eb0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 IMIT_COLUMN
31ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 2
31ed0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f .#define SQLITE_
31ee0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 LIMIT_EXPR_DEPTH
31ef0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
31f00 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 3.#define SQLITE
31f10 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f _LIMIT_COMPOUND_
31f20 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 SELECT
31f30 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 4.#define SQLIT
31f40 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 E_LIMIT_VDBE_OP
31f50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20
31f60 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 5.#define SQLI
31f70 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f TE_LIMIT_FUNCTIO
31f80 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 N_ARG
31f90 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 6.#define SQL
31fa0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 ITE_LIMIT_ATTACH
31fb0 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 ED
31fc0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 7.#define SQ
31fd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f LITE_LIMIT_LIKE_
31fe0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 PATTERN_LENGTH
31ff0 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 8.#define S
32000 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
32010 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 ABLE_NUMBER
32020 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 9.#define
32030 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 SQLITE_LIMIT_TRI
32040 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 GGER_DEPTH
32050 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 10.#define
32060 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f SQLITE_LIMIT_WO
32070 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 RKER_THREADS
32080 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 11../*.**
32090 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 CAPI3REF: Prepa
320a0 72 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 re Flags.**.** T
320b0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 hese constants d
320c0 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 66 6c efine various fl
320d0 61 67 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 ags that can be
320e0 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 22 passed into.** "
320f0 70 72 65 70 46 6c 61 67 73 22 20 70 61 72 61 6d prepFlags" param
32100 65 74 65 72 20 6f 66 20 74 68 65 20 5b 73 71 6c eter of the [sql
32110 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 28 ite3_prepare_v3(
32120 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 )] and.** [sqlit
32130 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 e3_prepare16_v3(
32140 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a )] interfaces..*
32150 2a 0a 2a 2a 20 4e 65 77 20 66 6c 61 67 73 20 6d *.** New flags m
32160 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 ay be added in f
32170 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f uture releases o
32180 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 f SQLite..**.**
32190 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 <dl>.** [[SQLITE
321a0 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 53 54 _PREPARE_PERSIST
321b0 45 4e 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 ENT]] ^(<dt>SQLI
321c0 54 45 5f 50 52 45 50 41 52 45 5f 50 45 52 53 49 TE_PREPARE_PERSI
321d0 53 54 45 4e 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 STENT</dt>.** <d
321e0 64 3e 54 68 65 20 53 51 4c 49 54 45 5f 50 52 45 d>The SQLITE_PRE
321f0 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 20 PARE_PERSISTENT
32200 66 6c 61 67 20 69 73 20 61 20 68 69 6e 74 20 74 flag is a hint t
32210 6f 20 74 68 65 20 71 75 65 72 79 20 70 6c 61 6e o the query plan
32220 6e 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 ner.** that the
32230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
32240 6e 74 20 77 69 6c 6c 20 62 65 20 72 65 74 61 69 nt will be retai
32250 6e 65 64 20 66 6f 72 20 61 20 6c 6f 6e 67 20 74 ned for a long t
32260 69 6d 65 20 61 6e 64 0a 2a 2a 20 70 72 6f 62 61 ime and.** proba
32270 62 6c 79 20 72 65 75 73 65 64 20 6d 61 6e 79 20 bly reused many
32280 74 69 6d 65 73 2e 29 5e 20 5e 57 69 74 68 6f 75 times.)^ ^Withou
32290 74 20 74 68 69 73 20 66 6c 61 67 2c 20 5b 73 71 t this flag, [sq
322a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 lite3_prepare_v3
322b0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 ()].** and [sqli
322c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 te3_prepare16_v3
322d0 28 29 5d 20 61 73 73 75 6d 65 20 74 68 61 74 20 ()] assume that
322e0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 the prepared sta
322f0 74 65 6d 65 6e 74 20 77 69 6c 6c 20 0a 2a 2a 20 tement will .**
32300 62 65 20 75 73 65 64 20 6a 75 73 74 20 6f 6e 63 be used just onc
32310 65 20 6f 72 20 61 74 20 6d 6f 73 74 20 61 20 66 e or at most a f
32320 65 77 20 74 69 6d 65 73 20 61 6e 64 20 74 68 65 ew times and the
32330 6e 20 64 65 73 74 72 6f 79 65 64 20 75 73 69 6e n destroyed usin
32340 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 g.** [sqlite3_fi
32350 6e 61 6c 69 7a 65 28 29 5d 20 72 65 6c 61 74 69 nalize()] relati
32360 76 65 6c 79 20 73 6f 6f 6e 2e 20 54 68 65 20 63 vely soon. The c
32370 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 urrent implement
32380 61 74 69 6f 6e 20 61 63 74 73 0a 2a 2a 20 6f 6e ation acts.** on
32390 20 74 68 69 73 20 68 69 6e 74 20 62 79 20 61 76 this hint by av
323a0 6f 69 64 69 6e 67 20 74 68 65 20 75 73 65 20 6f oiding the use o
323b0 66 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d f [lookaside mem
323c0 6f 72 79 5d 20 73 6f 20 61 73 20 6e 6f 74 20 74 ory] so as not t
323d0 6f 0a 2a 2a 20 64 65 70 6c 65 74 65 20 74 68 65 o.** deplete the
323e0 20 6c 69 6d 69 74 65 64 20 73 74 6f 72 65 20 6f limited store o
323f0 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f f lookaside memo
32400 72 79 2e 20 46 75 74 75 72 65 20 76 65 72 73 69 ry. Future versi
32410 6f 6e 73 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 ons of.** SQLite
32420 20 6d 61 79 20 61 63 74 20 6f 6e 20 74 68 69 73 may act on this
32430 20 68 69 6e 74 20 64 69 66 66 65 72 65 6e 74 6c hint differentl
32440 79 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 y..** </dl>.*/.#
32450 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 define SQLITE_PR
32460 45 50 41 52 45 5f 50 45 52 53 49 53 54 45 4e 54 EPARE_PERSISTENT
32470 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 0x
32480 30 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 01../*.** CAPI3R
32490 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e EF: Compiling An
324a0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a SQL Statement.*
324b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c * KEYWORDS: {SQL
324c0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 statement compi
324d0 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 ler}.** METHOD:
324e0 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 sqlite3.** CONST
324f0 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f RUCTOR: sqlite3_
32500 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 stmt.**.** To ex
32510 65 63 75 74 65 20 61 6e 20 53 51 4c 20 73 74 61 ecute an SQL sta
32520 74 65 6d 65 6e 74 2c 20 69 74 20 6d 75 73 74 20 tement, it must
32530 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 first be compile
32540 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f d into a byte-co
32550 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 de.** program us
32560 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 ing one of these
32570 20 72 6f 75 74 69 6e 65 73 2e 20 20 4f 72 2c 20 routines. Or,
32580 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 in other words,
32590 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a these routines.*
325a0 2a 20 61 72 65 20 63 6f 6e 73 74 72 75 63 74 6f * are constructo
325b0 72 73 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 rs for the [prep
325c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
325d0 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 object..**.** Th
325e0 65 20 70 72 65 66 65 72 72 65 64 20 72 6f 75 74 e preferred rout
325f0 69 6e 65 20 74 6f 20 75 73 65 20 69 73 20 5b 73 ine to use is [s
32600 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
32610 32 28 29 5d 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 2()]. The.** [s
32620 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 qlite3_prepare()
32630 5d 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6c ] interface is l
32640 65 67 61 63 79 20 61 6e 64 20 73 68 6f 75 6c 64 egacy and should
32650 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 20 be avoided..**
32660 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 [sqlite3_prepare
32670 5f 76 33 28 29 5d 20 68 61 73 20 61 6e 20 65 78 _v3()] has an ex
32680 74 72 61 20 22 70 72 65 70 46 6c 61 67 73 22 20 tra "prepFlags"
32690 6f 70 74 69 6f 6e 20 74 68 61 74 20 69 73 20 75 option that is u
326a0 73 65 64 0a 2a 2a 20 66 6f 72 20 73 70 65 63 69 sed.** for speci
326b0 61 6c 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a al purposes..**.
326c0 2a 2a 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 ** The use of th
326d0 65 20 55 54 46 2d 38 20 69 6e 74 65 72 66 61 63 e UTF-8 interfac
326e0 65 73 20 69 73 20 70 72 65 66 65 72 72 65 64 2c es is preferred,
326f0 20 61 73 20 53 51 4c 69 74 65 20 63 75 72 72 65 as SQLite curre
32700 6e 74 6c 79 0a 2a 2a 20 64 6f 65 73 20 61 6c 6c ntly.** does all
32710 20 70 61 72 73 69 6e 67 20 75 73 69 6e 67 20 55 parsing using U
32720 54 46 2d 38 2e 20 20 54 68 65 20 55 54 46 2d 31 TF-8. The UTF-1
32730 36 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 6 interfaces are
32740 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 61 73 20 provided.** as
32750 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 2e 20 20 a convenience.
32760 54 68 65 20 55 54 46 2d 31 36 20 69 6e 74 65 72 The UTF-16 inter
32770 66 61 63 65 73 20 77 6f 72 6b 20 62 79 20 63 6f faces work by co
32780 6e 76 65 72 74 69 6e 67 20 74 68 65 0a 2a 2a 20 nverting the.**
32790 69 6e 70 75 74 20 74 65 78 74 20 69 6e 74 6f 20 input text into
327a0 55 54 46 2d 38 2c 20 74 68 65 6e 20 69 6e 76 6f UTF-8, then invo
327b0 6b 69 6e 67 20 74 68 65 20 63 6f 72 72 65 73 70 king the corresp
327c0 6f 6e 64 69 6e 67 20 55 54 46 2d 38 20 69 6e 74 onding UTF-8 int
327d0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 erface..**.** Th
327e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 e first argument
327f0 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 , "db", is a [da
32800 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f tabase connectio
32810 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d n] obtained from
32820 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 a.** prior succ
32830 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b essful call to [
32840 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c sqlite3_open()],
32850 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 [sqlite3_open_v
32860 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 2()] or.** [sqli
32870 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 te3_open16()].
32880 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e The database con
32890 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 nection must not
328a0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 have been close
328b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 d..**.** The sec
328c0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a ond argument, "z
328d0 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 Sql", is the sta
328e0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d tement to be com
328f0 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a piled, encoded.*
32900 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d * as either UTF-
32910 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 8 or UTF-16. Th
32920 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 e sqlite3_prepar
32930 65 28 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 e(), sqlite3_pre
32940 70 61 72 65 5f 76 32 28 29 2c 0a 2a 2a 20 61 6e pare_v2(),.** an
32950 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 d sqlite3_prepar
32960 65 5f 76 33 28 29 0a 2a 2a 20 69 6e 74 65 72 66 e_v3().** interf
32970 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 aces use UTF-8,
32980 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 and sqlite3_prep
32990 61 72 65 31 36 28 29 2c 20 73 71 6c 69 74 65 33 are16(), sqlite3
329a0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c _prepare16_v2(),
329b0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
329c0 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20 75 prepare16_v3() u
329d0 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a se UTF-16..**.**
329e0 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 ^If the nByte a
329f0 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 rgument is negat
32a00 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 ive, then zSql i
32a10 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 s read up to the
32a20 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 .** first zero t
32a30 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e erminator. ^If n
32a40 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 Byte is positive
32a50 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 , then it is the
32a60 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 .** number of by
32a70 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 tes read from zS
32a80 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 ql. ^If nByte i
32a90 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 s zero, then no
32aa0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 prepared.** stat
32ab0 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 ement is generat
32ac0 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 ed..** If the ca
32ad0 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 ller knows that
32ae0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 the supplied str
32af0 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 ing is nul-termi
32b00 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 nated, then.** t
32b10 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 here is a small
32b20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 performance adva
32b30 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 ntage to passing
32b40 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 an nByte parame
32b50 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 ter that.** is t
32b60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 he number of byt
32b70 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 es in the input
32b80 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 string <i>includ
32b90 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e ing</i>.** the n
32ba0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a ul-terminator..*
32bb0 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 *.** ^If pzTail
32bc0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e is not NULL then
32bd0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 *pzTail is made
32be0 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 to point to the
32bf0 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 first byte.** p
32c00 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 ast the end of t
32c10 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 he first SQL sta
32c20 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 tement in zSql.
32c30 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 These routines
32c40 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 only.** compile
32c50 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d the first statem
32c60 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 ent in zSql, so
32c70 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 *pzTail is left
32c80 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 pointing to.** w
32c90 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f hat remains unco
32ca0 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a mpiled..**.** ^*
32cb0 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 ppStmt is left p
32cc0 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d ointing to a com
32cd0 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 piled [prepared
32ce0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 statement] that
32cf0 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 can be.** execut
32d00 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 ed using [sqlite
32d10 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 3_step()]. ^If
32d20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f there is an erro
32d30 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 r, *ppStmt is se
32d40 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e t.** to NULL. ^
32d50 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 If the input tex
32d60 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 t contains no SQ
32d70 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 L (if the input
32d80 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 is an empty.** s
32d90 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 tring or a comme
32da0 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 nt) then *ppStmt
32db0 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e is set to NULL.
32dc0 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 .** The calling
32dd0 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 procedure is res
32de0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c ponsible for del
32df0 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c eting the compil
32e00 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d ed.** SQL statem
32e10 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 ent using [sqlit
32e20 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 e3_finalize()] a
32e30 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 fter it has fini
32e40 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a shed with it..**
32e50 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 ppStmt may not
32e60 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e be NULL..**.** ^
32e70 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 On success, the
32e80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 sqlite3_prepare(
32e90 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 ) family of rout
32ea0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c ines return [SQL
32eb0 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 ITE_OK];.** othe
32ec0 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 rwise an [error
32ed0 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 code] is returne
32ee0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c d..**.** The sql
32ef0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
32f00 29 2c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 ), sqlite3_prepa
32f10 72 65 5f 76 33 28 29 2c 20 73 71 6c 69 74 65 33 re_v3(), sqlite3
32f20 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 2c _prepare16_v2(),
32f30 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f .** and sqlite3_
32f40 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 20 69 prepare16_v3() i
32f50 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 nterfaces are re
32f60 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c commended for al
32f70 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 0a l new programs..
32f80 2a 2a 20 54 68 65 20 6f 6c 64 65 72 20 69 6e 74 ** The older int
32f90 65 72 66 61 63 65 73 20 28 73 71 6c 69 74 65 33 erfaces (sqlite3
32fa0 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 _prepare() and s
32fb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 qlite3_prepare16
32fc0 28 29 29 0a 2a 2a 20 61 72 65 20 72 65 74 61 69 ()).** are retai
32fd0 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 ned for backward
32fe0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c s compatibility,
32ff0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 but their use i
33000 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a s discouraged..*
33010 2a 20 5e 49 6e 20 74 68 65 20 22 76 58 22 20 69 * ^In the "vX" i
33020 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 nterfaces, the p
33030 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
33040 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 t.** that is ret
33050 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 urned (the [sqli
33060 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 te3_stmt] object
33070 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 ) contains a cop
33080 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 y of the.** orig
33090 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 inal SQL text. T
330a0 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b his causes the [
330b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 sqlite3_step()]
330c0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 interface to.**
330d0 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 behave different
330e0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 ly in three ways
330f0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 :.**.** <ol>.**
33100 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 <li>.** ^If the
33110 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 database schema
33120 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 changes, instead
33130 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 of returning [S
33140 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 QLITE_SCHEMA] as
33150 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 it.** always us
33160 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 ed to do, [sqlit
33170 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 e3_step()] will
33180 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 automatically re
33190 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a compile the SQL.
331a0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 ** statement and
331b0 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 try to run it a
331c0 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 gain. As many as
331d0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 [SQLITE_MAX_SCH
331e0 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 EMA_RETRY].** re
331f0 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 tries will occur
33200 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f before sqlite3_
33210 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 step() gives up
33220 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 and returns an e
33230 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a rror..** </li>.*
33240 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 *.** <li>.** ^Wh
33250 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 en an error occu
33260 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 rs, [sqlite3_ste
33270 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e p()] will return
33280 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 one of the deta
33290 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 iled.** [error c
332a0 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 odes] or [extend
332b0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e ed error codes].
332c0 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 ^The legacy be
332d0 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a havior was that.
332e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 ** [sqlite3_step
332f0 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 ()] would only r
33300 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 eturn a generic
33310 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 [SQLITE_ERROR] r
33320 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e esult code.** an
33330 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f d the applicatio
33340 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 n would have to
33350 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 make a second ca
33360 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 ll to [sqlite3_r
33370 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 eset()].** in or
33380 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 der to find the
33390 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 underlying cause
333a0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e of the problem.
333b0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 With the "v2" p
333c0 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 repare.** interf
333d0 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c aces, the underl
333e0 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 ying reason for
333f0 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 the error is ret
33400 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c urned immediatel
33410 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a y..** </li>.**.*
33420 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 * <li>.** ^If th
33430 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 e specific value
33440 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d bound to [param
33450 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 eter | host para
33460 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a meter] in the .*
33470 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d * WHERE clause m
33480 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 ight influence t
33490 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 he choice of que
334a0 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 ry plan for a st
334b0 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e atement,.** then
334c0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 the statement w
334d0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 ill be automatic
334e0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c ally recompiled,
334f0 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 as if there had
33500 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 been .** a sche
33510 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 ma change, on th
33520 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 e first [sqlite
33530 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 3_step()] call f
33540 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 ollowing any cha
33550 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 nge.** to the [s
33560 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 qlite3_bind_text
33570 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 | bindings] of
33580 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d that [parameter]
33590 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 . .** ^The speci
335a0 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 fic value of WHE
335b0 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d RE-clause [param
335c0 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c eter] might infl
335d0 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 uence the .** ch
335e0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c oice of query pl
335f0 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 an if the parame
33600 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d ter is the left-
33610 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b hand side of a [
33620 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f LIKE].** or [GLO
33630 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 B] operator or i
33640 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 f the parameter
33650 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 is compared to a
33660 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e n indexed column
33670 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c .** and the [SQL
33680 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 ITE_ENABLE_STAT3
33690 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f ] compile-time o
336a0 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 ption is enabled
336b0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f ..** </li>.** </
336c0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 3c 70 3e 5e 73 71 ol>.**.** <p>^sq
336d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 33 lite3_prepare_v3
336e0 28 29 20 64 69 66 66 65 72 73 20 66 72 6f 6d 20 () differs from
336f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
33700 76 32 28 29 20 6f 6e 6c 79 20 69 6e 20 68 61 76 v2() only in hav
33710 69 6e 67 0a 2a 2a 20 74 68 65 20 65 78 74 72 61 ing.** the extra
33720 20 70 72 65 70 46 6c 61 67 73 20 70 61 72 61 6d prepFlags param
33730 65 74 65 72 2c 20 77 68 69 63 68 20 69 73 20 61 eter, which is a
33740 20 62 69 74 20 61 72 72 61 79 20 63 6f 6e 73 69 bit array consi
33750 73 74 69 6e 67 20 6f 66 20 7a 65 72 6f 20 6f 72 sting of zero or
33760 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 .** more of the
33770 5b 53 51 4c 49 54 45 5f 50 52 45 50 41 52 45 5f [SQLITE_PREPARE_
33780 50 45 52 53 49 53 54 45 4e 54 7c 53 51 4c 49 54 PERSISTENT|SQLIT
33790 45 5f 50 52 45 50 41 52 45 5f 2a 5d 20 66 6c 61 E_PREPARE_*] fla
337a0 67 73 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c gs. ^The.** sql
337b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 ite3_prepare_v2(
337c0 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b ) interface work
337d0 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 s exactly the sa
337e0 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 me as.** sqlite3
337f0 5f 70 72 65 70 61 72 65 5f 76 33 28 29 20 77 69 _prepare_v3() wi
33800 74 68 20 61 20 7a 65 72 6f 20 70 72 65 70 46 6c th a zero prepFl
33810 61 67 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a ags parameter..*
33820 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 /.SQLITE_API int
33830 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 sqlite3_prepare
33840 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c (. sqlite3 *db,
33850 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 /* D
33860 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a atabase handle *
33870 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a /. const char *
33880 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 zSql, /* S
33890 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 QL statement, UT
338a0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 F-8 encoded */.
338b0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 int nByte,
338c0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 /* Maxi
338d0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 mum length of zS
338e0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a ql in bytes. */.
338f0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a sqlite3_stmt *
33900 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 *ppStmt, /* OUT
33910 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 : Statement hand
33920 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 le */. const ch
33930 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 ar **pzTail
33940 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 /* OUT: Pointer
33950 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f to unused portio
33960 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a n of zSql */.);.
33970 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
33980 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 qlite3_prepare_v
33990 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2(. sqlite3 *db
339a0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 , /*
339b0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 Database handle
339c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 */. const char
339d0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 *zSql, /*
339e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 SQL statement, U
339f0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a TF-8 encoded */.
33a00 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 int nByte,
33a10 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 /* Max
33a20 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a imum length of z
33a30 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f Sql in bytes. */
33a40 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
33a50 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
33a60 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
33a70 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 dle */. const c
33a80 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 har **pzTail
33a90 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
33aa0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
33ab0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
33ac0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
33ad0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f sqlite3_prepare_
33ae0 76 33 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 v3(. sqlite3 *d
33af0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a b, /*
33b00 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 Database handle
33b10 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 */. const char
33b20 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a *zSql, /*
33b30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 SQL statement,
33b40 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f UTF-8 encoded */
33b50 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 . int nByte,
33b60 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 /* Ma
33b70 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 ximum length of
33b80 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a zSql in bytes. *
33b90 2f 0a 20 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 /. unsigned int
33ba0 20 70 72 65 70 46 6c 61 67 73 2c 20 2f 2a 20 5a prepFlags, /* Z
33bb0 65 72 6f 20 6f 72 20 6d 6f 72 65 20 53 51 4c 49 ero or more SQLI
33bc0 54 45 5f 50 52 45 50 41 52 45 5f 20 66 6c 61 67 TE_PREPARE_ flag
33bd0 73 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 s */. sqlite3_s
33be0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f tmt **ppStmt, /
33bf0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 * OUT: Statement
33c00 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
33c10 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c st char **pzTail
33c20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 /* OUT: Poi
33c30 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 nter to unused p
33c40 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a ortion of zSql *
33c50 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 /.);.SQLITE_API
33c60 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 int sqlite3_prep
33c70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33 are16(. sqlite3
33c80 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 *db,
33c90 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e /* Database han
33ca0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
33cb0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 oid *zSql,
33cc0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e /* SQL statemen
33cd0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 t, UTF-16 encode
33ce0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 d */. int nByte
33cf0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f , /
33d00 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 * Maximum length
33d10 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 of zSql in byte
33d20 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f s. */. sqlite3_
33d30 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 stmt **ppStmt,
33d40 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e /* OUT: Statemen
33d50 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f t handle */. co
33d60 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 nst void **pzTai
33d70 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f l /* OUT: Po
33d80 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 inter to unused
33d90 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 portion of zSql
33da0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 */.);.SQLITE_API
33db0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 int sqlite3_pre
33dc0 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c pare16_v2(. sql
33dd0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 ite3 *db,
33de0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 /* Database
33df0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e handle */. con
33e00 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 st void *zSql,
33e10 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 /* SQL stat
33e20 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e ement, UTF-16 en
33e30 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e coded */. int n
33e40 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 Byte,
33e50 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 /* Maximum le
33e60 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 ngth of zSql in
33e70 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 bytes. */. sqli
33e80 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d te3_stmt **ppStm
33e90 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 t, /* OUT: Stat
33ea0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a ement handle */.
33eb0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 const void **p
33ec0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 zTail /* OUT
33ed0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 : Pointer to unu
33ee0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a sed portion of z
33ef0 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 Sql */.);.SQLITE
33f00 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 _API int sqlite3
33f10 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 0a 20 _prepare16_v3(.
33f20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 sqlite3 *db,
33f30 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 /* Data
33f40 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 base handle */.
33f50 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 const void *zSq
33f60 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 l, /* SQL
33f70 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 statement, UTF-1
33f80 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6 encoded */. i
33f90 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 nt nByte,
33fa0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 /* Maximu
33fb0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c m length of zSql
33fc0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 in bytes. */.
33fd0 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 70 72 65 unsigned int pre
33fe0 70 46 6c 61 67 73 2c 20 2f 2a 20 5a 65 72 6f 20 pFlags, /* Zero
33ff0 6f 72 20 6d 6f 72 65 20 53 51 4c 49 54 45 5f 50 or more SQLITE_P
34000 52 45 50 41 52 45 5f 20 66 6c 61 67 73 20 2a 2f REPARE_ flags */
34010 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 . sqlite3_stmt
34020 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 **ppStmt, /* OU
34030 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e T: Statement han
34040 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 dle */. const v
34050 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 oid **pzTail
34060 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 /* OUT: Pointer
34070 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 to unused porti
34080 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b on of zSql */.);
34090 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
340a0 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 : Retrieving Sta
340b0 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 tement SQL.** ME
340c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 THOD: sqlite3_st
340d0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 mt.**.** ^The sq
340e0 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 lite3_sql(P) int
340f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 erface returns a
34100 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f pointer to a co
34110 70 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a py of the UTF-8.
34120 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 ** SQL text used
34130 20 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 to create [prep
34140 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 ared statement]
34150 50 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 P if P was.** cr
34160 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65 eated by [sqlite
34170 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 3_prepare_v2()],
34180 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 [sqlite3_prepar
34190 65 5f 76 33 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c e_v3()],.** [sql
341a0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 ite3_prepare16_v
341b0 32 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69 74 65 2()], or [sqlite
341c0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 29 3_prepare16_v3()
341d0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 ]..** ^The sqlit
341e0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 e3_expanded_sql(
341f0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 P) interface ret
34200 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 urns a pointer t
34210 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 o a UTF-8.** str
34220 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 ing containing t
34230 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70 he SQL text of p
34240 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e repared statemen
34250 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75 t P with.** [bou
34260 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65 nd parameters] e
34270 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e xpanded..**.** ^
34280 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 (For example, if
34290 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 a prepared stat
342a0 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64 ement is created
342b0 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a using the SQL.*
342c0 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24 * text "SELECT $
342d0 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66 abc,:xyz" and if
342e0 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20 parameter $abc
342f0 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65 is bound to inte
34300 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20 ger 2345.** and
34310 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69 parameter :xyz i
34320 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20 s unbound, then
34330 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69 sqlite3_sql() wi
34340 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 ll return.** the
34350 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67 original string
34360 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a , "SELECT $abc,:
34370 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33 xyz" but sqlite3
34380 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a _expanded_sql().
34390 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22 ** will return "
343a0 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c SELECT 2345,NULL
343b0 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 ".)^.**.** ^The
343c0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 sqlite3_expanded
343d0 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65 _sql() interface
343e0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 returns NULL if
343f0 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 insufficient me
34400 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c mory.** is avail
34410 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65 able to hold the
34420 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74 result, or if t
34430 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20 he result would
34440 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68 exceed the.** th
34450 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67 e maximum string
34460 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e length determin
34470 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 ed by the [SQLIT
34480 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e E_LIMIT_LENGTH].
34490 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c .**.** ^The [SQL
344a0 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c ITE_TRACE_SIZE_L
344b0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 IMIT] compile-ti
344c0 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73 me option limits
344d0 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 the size of.**
344e0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20 bound parameter
344f0 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68 expansions. ^Th
34500 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54 e [SQLITE_OMIT_T
34510 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 RACE] compile-ti
34520 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75 me.** option cau
34530 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61 ses sqlite3_expa
34540 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c nded_sql() to al
34550 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c ways return NULL
34560 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72 ..**.** ^The str
34570 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 ing returned by
34580 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69 sqlite3_sql(P) i
34590 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c s managed by SQL
345a0 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75 ite and is.** au
345b0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 tomatically free
345c0 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61 d when the prepa
345d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 red statement is
345e0 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e finalized..** ^
345f0 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 The string retur
34600 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65 ned by sqlite3_e
34610 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20 xpanded_sql(P),
34620 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e on the other han
34630 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65 d,.** is obtaine
34640 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f d from [sqlite3_
34650 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75 malloc()] and mu
34660 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68 st be free by th
34670 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a e application.**
34680 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74 by passing it t
34690 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 o [sqlite3_free(
346a0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
346b0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 I const char *sq
346c0 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 lite3_sql(sqlite
346d0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 3_stmt *pStmt);.
346e0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 SQLITE_API char
346f0 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 *sqlite3_expande
34700 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 d_sql(sqlite3_st
34710 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a mt *pStmt);../*.
34720 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 ** CAPI3REF: Det
34730 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c ermine If An SQL
34740 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 Statement Write
34750 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a s The Database.*
34760 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 * METHOD: sqlite
34770 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 3_stmt.**.** ^Th
34780 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 e sqlite3_stmt_r
34790 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 eadonly(X) inter
347a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 face returns tru
347b0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a e (non-zero) if.
347c0 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 ** and only if t
347d0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 he [prepared sta
347e0 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 tement] X makes
347f0 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 no direct change
34800 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 s to.** the cont
34810 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 ent of the datab
34820 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 ase file..**.**
34830 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 Note that [appli
34840 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 cation-defined S
34850 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 QL functions] or
34860 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 .** [virtual tab
34870 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 les] might chang
34880 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 e the database i
34890 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 ndirectly as a s
348a0 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a ide effect. .**
348b0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 ^(For example,
348c0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f if an applicatio
348d0 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 n defines a func
348e0 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 tion "eval()" th
348f0 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 at .** calls [sq
34900 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 lite3_exec()], t
34910 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e hen the followin
34920 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 g SQL statement
34930 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 would.** change
34940 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c the database fil
34950 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 e through side-e
34960 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 ffects:.**.** <b
34970 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a lockquote><pre>.
34980 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 ** SELECT eva
34990 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 l('DELETE FROM t
349a0 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 1') FROM t2;.**
349b0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f </pre></blockquo
349c0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 te>.**.** But be
349d0 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 cause the [SELEC
349e0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 T] statement doe
349f0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 s not change the
34a00 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a database file.*
34a10 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 * directly, sqli
34a20 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
34a30 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 y() would still
34a40 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a return true.)^.*
34a50 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f *.** ^Transactio
34a60 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d n control statem
34a70 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 ents such as [BE
34a80 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 GIN], [COMMIT],
34a90 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b [ROLLBACK],.** [
34aa0 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 SAVEPOINT], and
34ab0 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 [RELEASE] cause
34ac0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 sqlite3_stmt_rea
34ad0 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 donly() to retur
34ae0 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 n true,.** since
34af0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 the statements
34b00 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f themselves do no
34b10 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 t actually modif
34b20 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 y the database b
34b30 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 ut.** rather the
34b40 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 y control the ti
34b50 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 ming of when oth
34b60 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f er statements mo
34b70 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 dify the .** dat
34b80 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 abase. ^The [AT
34b90 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 TACH] and [DETAC
34ba0 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c H] statements al
34bb0 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 so cause.** sqli
34bc0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c te3_stmt_readonl
34bd0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 y() to return tr
34be0 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 ue since, while
34bf0 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 those statements
34c00 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 .** change the c
34c10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 onfiguration of
34c20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 a database conne
34c30 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e ction, they do n
34c40 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e ot make .** chan
34c50 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 ges to the conte
34c60 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 nt of the databa
34c70 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b se files on disk
34c80 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
34c90 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
34ca0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 ) interface retu
34cb0 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 rns true for [BE
34cc0 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 GIN] since.** [B
34cd0 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 EGIN] merely set
34ce0 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 s internal flags
34cf0 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e , but the [BEGIN
34d00 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 |BEGIN IMMEDIATE
34d10 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c ] and.** [BEGIN|
34d20 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d BEGIN EXCLUSIVE]
34d30 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 commands do tou
34d40 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 ch the database
34d50 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 and so.** sqlite
34d60 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 3_stmt_readonly(
34d70 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 ) returns false
34d80 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e for those comman
34d90 64 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 ds..*/.SQLITE_AP
34da0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 I int sqlite3_st
34db0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 mt_readonly(sqli
34dc0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 te3_stmt *pStmt)
34dd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 ;../*.** CAPI3RE
34de0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 F: Determine If
34df0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 A Prepared State
34e00 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 ment Has Been Re
34e10 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 set.** METHOD: s
34e20 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a qlite3_stmt.**.*
34e30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 * ^The sqlite3_s
34e40 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 tmt_busy(S) inte
34e50 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 rface returns tr
34e60 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 ue (non-zero) if
34e70 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 the.** [prepare
34e80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 d statement] S h
34e90 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 as been stepped
34ea0 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 at least once us
34eb0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 ing .** [sqlite3
34ec0 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 _step(S)] but ha
34ed0 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f s neither run to
34ee0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74 completion (ret
34ef0 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 urned.** [SQLITE
34f00 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c _DONE] from [sql
34f10 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e ite3_step(S)]) n
34f20 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 or.** been reset
34f30 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f using [sqlite3_
34f40 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 reset(S)]. ^The
34f50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 sqlite3_stmt_bu
34f60 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 sy(S).** interfa
34f70 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 ce returns false
34f80 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 if S is a NULL
34f90 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 pointer. If S i
34fa0 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c s not a .** NULL
34fb0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 pointer and is
34fc0 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f not a pointer to
34fd0 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 a valid [prepar
34fe0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a ed statement].**
34ff0 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 object, then th
35000 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e e behavior is un
35010 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 defined and prob
35020 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 ably undesirable
35030 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 ..**.** This int
35040 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 erface can be us
35050 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f ed in combinatio
35060 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f n [sqlite3_next_
35070 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f stmt()].** to lo
35080 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 cate all prepare
35090 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 d statements ass
350a0 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 ociated with a d
350b0 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e atabase .** conn
350c0 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 ection that are
350d0 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 in need of being
350e0 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 reset. This ca
350f0 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f n be used,.** fo
35100 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 r example, in di
35110 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 agnostic routine
35120 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 s to search for
35130 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 prepared .** sta
35140 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 tements that are
35150 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 holding a trans
35160 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a action open..*/.
35170 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 SQLITE_API int s
35180 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 qlite3_stmt_busy
35190 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b (sqlite3_stmt*);
351a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 ../*.** CAPI3REF
351b0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 : Dynamically Ty
351c0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 ped Value Object
351d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 .** KEYWORDS: {p
351e0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 rotected sqlite3
351f0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 _value} {unprote
35200 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c cted sqlite3_val
35210 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 ue}.**.** SQLite
35220 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 uses the sqlite
35230 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 3_value object t
35240 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 o represent all
35250 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 values.** that c
35260 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 an be stored in
35270 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 a database table
35280 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 . SQLite uses dy
35290 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 namic typing.**
352a0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 for the values i
352b0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 t stores. ^Valu
352c0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c es stored in sql
352d0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
352e0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 ts.** can be int
352f0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 egers, floating
35300 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 point values, st
35310 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 rings, BLOBs, or
35320 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 NULL..**.** An
35330 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 sqlite3_value ob
35340 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 ject may be eith
35350 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f er "protected" o
35360 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e r "unprotected".
35370 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 .** Some interfa
35380 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 ces require a pr
35390 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
353a0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e value. Other in
353b0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c terfaces.** will
353c0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 accept either a
353d0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e protected or an
353e0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c unprotected sql
353f0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 ite3_value..** E
35400 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 very interface t
35410 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 hat accepts sqli
35420 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 te3_value argume
35430 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a nts specifies.**
35440 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 whether or not
35450 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 it requires a pr
35460 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f otected sqlite3_
35470 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b value. The.** [
35480 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 sqlite3_value_du
35490 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 p()] interface c
354a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f an be used to co
354b0 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a nstruct a new .*
354c0 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 * protected sqli
354d0 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 te3_value from a
354e0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 n unprotected sq
354f0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a lite3_value..**.
35500 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 ** The terms "pr
35510 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e otected" and "un
35520 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 protected" refer
35530 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e to whether or n
35540 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 ot.** a mutex is
35550 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 held. An inter
35560 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c nal mutex is hel
35570 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 d for a protecte
35580 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
35590 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f ue object but no
355a0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 mutex is held f
355b0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 or an unprotecte
355c0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c d.** sqlite3_val
355d0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 ue object. If S
355e0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 QLite is compile
355f0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 d to be single-t
35600 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 hreaded.** (with
35610 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 [SQLITE_THREADS
35620 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 AFE=0] and with
35630 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 [sqlite3_threads
35640 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 afe()] returning
35650 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 0).** or if SQL
35660 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e ite is run in on
35670 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 e of reduced mut
35680 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 ex modes .** [SQ
35690 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 LITE_CONFIG_SING
356a0 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 LETHREAD] or [SQ
356b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 LITE_CONFIG_MULT
356c0 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e ITHREAD].** then
356d0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 there is no dis
356e0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e tinction between
356f0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 protected and u
35700 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 nprotected.** sq
35710 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 lite3_value obje
35720 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e cts and they can
35730 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 be used interch
35740 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 angeably. Howev
35750 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d er,.** for maxim
35760 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c um code portabil
35770 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d ity it is recomm
35780 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 ended that appli
35790 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c cations.** still
357a0 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e make the distin
357b0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 ction between pr
357c0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 otected and unpr
357d0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 otected.** sqlit
357e0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 e3_value objects
357f0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 even when not s
35800 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 trictly required
35810 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c ..**.** ^The sql
35820 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
35830 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 ts that are pass
35840 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 ed as parameters
35850 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 into the.** imp
35860 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b lementation of [
35870 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 application-defi
35880 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e ned SQL function
35890 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 s] are protected
358a0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 ..** ^The sqlite
358b0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 3_value object r
358c0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 eturned by.** [s
358d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 qlite3_column_va
358e0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 lue()] is unprot
358f0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 ected..** Unprot
35900 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 ected sqlite3_va
35910 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 lue objects may
35920 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 61 73 20 only be used as
35930 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 arguments.** to
35940 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f [sqlite3_result_
35950 76 61 6c 75 65 28 29 5d 2c 20 5b 73 71 6c 69 74 value()], [sqlit
35960 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d e3_bind_value()]
35970 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 , and.** [sqlite
35980 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 0a 3_value_dup()]..
35990 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f ** The [sqlite3_
359a0 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c value_blob | sql
359b0 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 ite3_value_type(
359c0 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 )] family of.**
359d0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 interfaces requi
359e0 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c re protected sql
359f0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 ite3_value objec
35a00 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 ts..*/.typedef s
35a10 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 61 truct sqlite3_va
35a20 6c 75 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 lue sqlite3_valu
35a30 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 e;../*.** CAPI3R
35a40 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e EF: SQL Function
35a50 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a Context Object.
35a60 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 **.** The contex
35a70 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 t in which an SQ
35a80 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 L function execu
35a90 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e tes is stored in
35aa0 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 an.** sqlite3_c
35ab0 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 ontext object.
35ac0 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e ^A pointer to an
35ad0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 sqlite3_context
35ae0 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c object.** is al
35af0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d ways first param
35b00 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 eter to [applica
35b10 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c tion-defined SQL
35b20 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 functions]..**
35b30 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d The application-
35b40 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 defined SQL func
35b50 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 tion implementat
35b60 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 ion will pass th
35b70 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 is.** pointer th
35b80 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 rough into calls
35b90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 to [sqlite3_res
35ba0 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 ult_int | sqlite
35bb0 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 3_result()],.**
35bc0 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 [sqlite3_aggrega
35bd0 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b te_context()], [
35be0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 sqlite3_user_dat
35bf0 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 a()],.** [sqlite
35c00 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 3_context_db_han
35c10 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 dle()], [sqlite3
35c20 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c _get_auxdata()],
35c30 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 .** and/or [sqli
35c40 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 te3_set_auxdata(
35c50 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 )]..*/.typedef s
35c60 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f truct sqlite3_co
35c70 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f ntext sqlite3_co
35c80 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 ntext;../*.** CA
35c90 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 PI3REF: Binding
35ca0 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 Values To Prepar
35cb0 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a ed Statements.**
35cc0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 KEYWORDS: {host
35cd0 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 parameter} {hos
35ce0 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 t parameters} {h
35cf0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 ost parameter na
35d00 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a me}.** KEYWORDS:
35d10 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d {SQL parameter}
35d20 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 {SQL parameters
35d30 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e } {parameter bin
35d40 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a ding}.** METHOD:
35d50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a sqlite3_stmt.**
35d60 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c .** ^(In the SQL
35d70 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 statement text
35d80 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 input to [sqlite
35d90 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 3_prepare_v2()]
35da0 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 and its variants
35db0 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 ,.** literals ma
35dc0 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 y be replaced by
35dd0 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 a [parameter] t
35de0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 hat matches one
35df0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 of following.**
35e00 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a templates:.**.**
35e10 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f <ul>.** <li> ?
35e20 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a .** <li> ?NNN.*
35e30 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 * <li> :VVV.**
35e40 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c <li> @VVV.** <l
35e50 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c i> $VVV.** </ul
35e60 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 >.**.** In the t
35e70 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 emplates above,
35e80 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 NNN represents a
35e90 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 n integer litera
35ea0 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 l,.** and VVV re
35eb0 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 presents an alph
35ec0 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 anumeric identif
35ed0 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c ier.)^ ^The val
35ee0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 ues of these.**
35ef0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f parameters (also
35f00 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 called "host pa
35f10 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f rameter names" o
35f20 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 r "SQL parameter
35f30 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 s").** can be se
35f40 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 t using the sqli
35f50 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 te3_bind_*() rou
35f60 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 tines defined he
35f70 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 re..**.** ^The f
35f80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f irst argument to
35f90 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e the sqlite3_bin
35fa0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 d_*() routines i
35fb0 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f s always.** a po
35fc0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 inter to the [sq
35fd0 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 lite3_stmt] obje
35fe0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d ct returned from
35ff0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 .** [sqlite3_pre
36000 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 pare_v2()] or it
36010 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a s variants..**.*
36020 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 * ^The second ar
36030 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e gument is the in
36040 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 dex of the SQL p
36050 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 arameter to be s
36060 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 et..** ^The left
36070 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 most SQL paramet
36080 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
36090 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 of 1. ^When the
360a0 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 same named.** S
360b0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 QL parameter is
360c0 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f used more than o
360d0 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 nce, second and
360e0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 subsequent.** oc
360f0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 currences have t
36100 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 he same index as
36110 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 the first occur
36120 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 rence..** ^The i
36130 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 ndex for named p
36140 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 arameters can be
36150 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 looked up using
36160 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 the.** [sqlite3
36170 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
36180 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 index()] API if
36190 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 desired. ^The i
361a0 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e ndex.** for "?NN
361b0 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 N" parameters is
361c0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e the value of NN
361d0 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 N..** ^The NNN v
361e0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 alue must be bet
361f0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b ween 1 and the [
36200 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d sqlite3_limit()]
36210 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 .** parameter [S
36220 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 QLITE_LIMIT_VARI
36230 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 ABLE_NUMBER] (de
36240 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 fault value: 999
36250 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 )..**.** ^The th
36260 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 ird argument is
36270 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e the value to bin
36280 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 d to the paramet
36290 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 er..** ^If the t
362a0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 hird parameter t
362b0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 o sqlite3_bind_t
362c0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 ext() or sqlite3
362d0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a _bind_text16().*
362e0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e * or sqlite3_bin
362f0 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 d_blob() is a NU
36300 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 LL pointer then
36310 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d the fourth param
36320 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 eter.** is ignor
36330 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 ed and the end r
36340 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d esult is the sam
36350 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e e as sqlite3_bin
36360 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 d_null()..**.**
36370 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 ^(In those routi
36380 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 nes that have a
36390 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c fourth argument,
363a0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 its value is th
363b0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 e.** number of b
363c0 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 ytes in the para
363d0 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c meter. To be cl
363e0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 ear: the value i
363f0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 s the.** number
36400 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 of <u>bytes</u>
36410 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f in the value, no
36420 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 t the number of
36430 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a characters.)^.**
36440 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 ^If the fourth
36450 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c parameter to sql
36460 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 ite3_bind_text()
36470 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
36480 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 _text16().** is
36490 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 negative, then t
364a0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 he length of the
364b0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 string is.** th
364c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 e number of byte
364d0 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 s up to the firs
364e0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f t zero terminato
364f0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 r..** If the fou
36500 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f rth parameter to
36510 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c sqlite3_bind_bl
36520 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 ob() is negative
36530 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 , then.** the be
36540 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 havior is undefi
36550 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e ned..** If a non
36560 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 -negative fourth
36570 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 parameter is pr
36580 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 ovided to sqlite
36590 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 3_bind_text().**
365a0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 or sqlite3_bind
365b0 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c _text16() or sql
365c0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 ite3_bind_text64
365d0 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 () then.** that
365e0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 parameter must b
365f0 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 e the byte offse
36600 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e t.** where the N
36610 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f UL terminator wo
36620 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 uld occur assumi
36630 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 ng the string we
36640 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e re NUL.** termin
36650 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 ated. If any NU
36660 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 L characters occ
36670 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 ur at byte offse
36680 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a ts less than .**
36690 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 the value of th
366a0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 e fourth paramet
366b0 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 er then the resu
366c0 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c lting string val
366d0 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 ue will.** conta
366e0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 in embedded NULs
366f0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 . The result of
36700 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 expressions inv
36710 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a olving strings.*
36720 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 * with embedded
36730 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 NULs is undefine
36740 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 d..**.** ^The fi
36750 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 fth argument to
36760 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 the BLOB and str
36770 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 ing binding inte
36780 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 rfaces.** is a d
36790 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 estructor used t
367a0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 o dispose of the
367b0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 BLOB or.** stri
367c0 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 ng after SQLite
367d0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 has finished wit
367e0 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 h it. ^The dest
367f0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 ructor is called
36800 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f .** to dispose o
36810 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 f the BLOB or st
36820 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 ring even if the
36830 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 call to bind AP
36840 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 I fails..** ^If
36850 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 the fifth argume
36860 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 nt is.** the spe
36870 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 cial value [SQLI
36880 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e TE_STATIC], then
36890 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 SQLite assumes
368a0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f that the.** info
368b0 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 rmation is in st
368c0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 atic, unmanaged
368d0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e space and does n
368e0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 ot need to be fr
368f0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 eed..** ^If the
36900 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 fifth argument h
36910 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 as the value [SQ
36920 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c LITE_TRANSIENT],
36930 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 then.** SQLite
36940 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 makes its own pr
36950 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 ivate copy of th
36960 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 e data immediate
36970 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 ly, before.** th
36980 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
36990 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 () routine retur
369a0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 ns..**.** ^The s
369b0 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f ixth argument to
369c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
369d0 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f xt64() must be o
369e0 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 ne of.** [SQLITE
369f0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f _UTF8], [SQLITE_
36a00 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f UTF16], [SQLITE_
36a10 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 UTF16BE], or [SQ
36a20 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a LITE_UTF16LE].**
36a30 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 to specify the
36a40 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 encoding of the
36a50 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 text in the thir
36a60 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 d parameter. If
36a70 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 .** the sixth ar
36a80 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 gument to sqlite
36a90 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 3_bind_text64()
36aa0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 is not one of th
36ab0 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c e.** allowed val
36ac0 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c ues shown above,
36ad0 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20 or if the text
36ae0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 encoding is diff
36af0 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 erent.** from th
36b00 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 e encoding speci
36b10 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74 fied by the sixt
36b20 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 h parameter, the
36b30 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a n the behavior.*
36b40 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a * is undefined..
36b50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 **.** ^The sqlit
36b60 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 e3_bind_zeroblob
36b70 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 () routine binds
36b80 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 a BLOB of lengt
36b90 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 h N that.** is f
36ba0 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 illed with zeroe
36bb0 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 s. ^A zeroblob
36bc0 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f uses a fixed amo
36bd0 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a unt of memory.**
36be0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 (just an intege
36bf0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 r to hold its si
36c00 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 ze) while it is
36c10 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e being processed.
36c20 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 .** Zeroblobs ar
36c30 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 e intended to se
36c40 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 rve as placehold
36c50 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 ers for BLOBs wh
36c60 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 ose.** content i
36c70 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 s later written
36c80 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 using.** [sqlite
36c90 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 3_blob_open | in
36ca0 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 cremental BLOB I
36cb0 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a /O] routines..**
36cc0 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c ^A negative val
36cd0 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 ue for the zerob
36ce0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 lob results in a
36cf0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f zero-length BLO
36d00 42 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 B..**.** ^The sq
36d10 6c 69 74 65 33 5f 62 69 6e 64 5f 70 6f 69 6e 74 lite3_bind_point
36d20 65 72 28 53 2c 49 2c 50 2c 54 2c 44 29 20 72 6f er(S,I,P,T,D) ro
36d30 75 74 69 6e 65 20 63 61 75 73 65 73 20 74 68 65 utine causes the
36d40 20 49 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 I-th parameter
36d50 69 6e 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 in.** [prepared
36d60 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 74 6f 20 statement] S to
36d70 68 61 76 65 20 61 6e 20 53 51 4c 20 76 61 6c 75 have an SQL valu
36d80 65 20 6f 66 20 4e 55 4c 4c 2c 20 62 75 74 20 74 e of NULL, but t
36d90 6f 20 61 6c 73 6f 20 62 65 0a 2a 2a 20 61 73 73 o also be.** ass
36da0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 ociated with the
36db0 20 70 6f 69 6e 74 65 72 20 50 20 6f 66 20 74 79 pointer P of ty
36dc0 70 65 20 54 2e 20 20 5e 44 20 69 73 20 65 69 74 pe T. ^D is eit
36dd0 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 her a NULL point
36de0 65 72 20 6f 72 0a 2a 2a 20 61 20 70 6f 69 6e 74 er or.** a point
36df0 65 72 20 74 6f 20 61 20 64 65 73 74 72 75 63 74 er to a destruct
36e00 6f 72 20 66 75 6e 63 74 69 6f 6e 20 66 6f 72 20 or function for
36e10 50 2e 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 P. ^SQLite will
36e20 69 6e 76 6f 6b 65 20 74 68 65 0a 2a 2a 20 64 65 invoke the.** de
36e30 73 74 72 75 63 74 6f 72 20 44 20 77 69 74 68 20 structor D with
36e40 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e a single argumen
36e50 74 20 6f 66 20 50 20 77 68 65 6e 20 69 74 20 69 t of P when it i
36e60 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 s finished using
36e70 0a 2a 2a 20 50 2e 20 20 54 68 65 20 54 20 70 61 .** P. The T pa
36e80 72 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 rameter should b
36e90 65 20 61 20 73 74 61 74 69 63 20 73 74 72 69 6e e a static strin
36ea0 67 2c 20 70 72 65 66 65 72 61 62 6c 79 20 61 20 g, preferably a
36eb0 73 74 72 69 6e 67 0a 2a 2a 20 6c 69 74 65 72 61 string.** litera
36ec0 6c 2e 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 l. The sqlite3_b
36ed0 69 6e 64 5f 70 6f 69 6e 74 65 72 28 29 20 72 6f ind_pointer() ro
36ee0 75 74 69 6e 65 20 69 73 20 70 61 72 74 20 6f 66 utine is part of
36ef0 20 74 68 65 0a 2a 2a 20 5b 70 6f 69 6e 74 65 72 the.** [pointer
36f00 20 70 61 73 73 69 6e 67 20 69 6e 74 65 72 66 61 passing interfa
36f10 63 65 5d 20 61 64 64 65 64 20 66 6f 72 20 53 51 ce] added for SQ
36f20 4c 69 74 65 20 33 2e 32 30 2e 30 2e 0a 2a 2a 0a Lite 3.20.0..**.
36f30 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 ** ^If any of th
36f40 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a e sqlite3_bind_*
36f50 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 () routines are
36f60 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 called with a NU
36f70 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f LL pointer.** fo
36f80 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 r the [prepared
36f90 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 statement] or wi
36fa0 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 th a prepared st
36fb0 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 atement for whic
36fc0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 h.** [sqlite3_st
36fd0 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 ep()] has been c
36fe0 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e alled more recen
36ff0 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 tly than [sqlite
37000 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 3_reset()],.** t
37010 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c hen the call wil
37020 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 l return [SQLITE
37030 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e _MISUSE]. If an
37040 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 y sqlite3_bind_(
37050 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 ).** routine is
37060 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 passed a [prepar
37070 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 ed statement] th
37080 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 at has been fina
37090 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 lized, the.** re
370a0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 sult is undefine
370b0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 d and probably h
370c0 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 armful..**.** ^B
370d0 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 indings are not
370e0 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b cleared by the [
370f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d sqlite3_reset()]
37100 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e routine..** ^Un
37110 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 bound parameters
37120 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 are interpreted
37130 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 as NULL..**.**
37140 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
37150 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 d_* routines ret
37160 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 urn [SQLITE_OK]
37170 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e on success or an
37180 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d .** [error code]
37190 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 if anything goe
371a0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 s wrong..** ^[SQ
371b0 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 LITE_TOOBIG] mig
371c0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 ht be returned i
371d0 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 f the size of a
371e0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a string or BLOB.*
371f0 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 * exceeds limits
37200 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c imposed by [sql
37210 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c ite3_limit]([SQL
37220 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 ITE_LIMIT_LENGTH
37230 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 ]) or.** [SQLITE
37240 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a _MAX_LENGTH]..**
37250 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d ^[SQLITE_RANGE]
37260 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 is returned if
37270 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a the parameter.**
37280 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 index is out of
37290 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 range. ^[SQLIT
372a0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 E_NOMEM] is retu
372b0 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 rned if malloc()
372c0 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 fails..**.** Se
372d0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
372e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f _bind_parameter_
372f0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 count()],.** [sq
37300 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d lite3_bind_param
37310 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e eter_name()], an
37320 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f d [sqlite3_bind_
37330 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 parameter_index(
37340 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 )]..*/.SQLITE_AP
37350 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 I int sqlite3_bi
37360 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f nd_blob(sqlite3_
37370 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 stmt*, int, cons
37380 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 t void*, int n,
37390 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
373a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
373b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f sqlite3_bind_blo
373c0 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 b64(sqlite3_stmt
373d0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f *, int, const vo
373e0 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e id*, sqlite3_uin
373f0 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 t64,.
37400 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 voi
37410 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 d(*)(void*));.SQ
37420 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
37430 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 ite3_bind_double
37440 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 (sqlite3_stmt*,
37450 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 int, double);.SQ
37460 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
37470 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 ite3_bind_int(sq
37480 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 lite3_stmt*, int
37490 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 , int);.SQLITE_A
374a0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
374b0 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 ind_int64(sqlite
374c0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 3_stmt*, int, sq
374d0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 lite3_int64);.SQ
374e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c LITE_API int sql
374f0 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 ite3_bind_null(s
37500 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e qlite3_stmt*, in
37510 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 t);.SQLITE_API i
37520 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f nt sqlite3_bind_
37530 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d text(sqlite3_stm
37540 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 t*,int,const cha
37550 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 r*,int,void(*)(v
37560 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 oid*));.SQLITE_A
37570 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
37580 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 ind_text16(sqlit
37590 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 e3_stmt*, int, c
375a0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c onst void*, int,
375b0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 void(*)(void*))
375c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
375d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 sqlite3_bind_te
375e0 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d xt64(sqlite3_stm
375f0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 t*, int, const c
37600 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 har*, sqlite3_ui
37610 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 nt64,.
37620 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 v
37630 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 oid(*)(void*), u
37640 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 nsigned char enc
37650 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 oding);.SQLITE_A
37660 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
37670 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 ind_value(sqlite
37680 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 3_stmt*, int, co
37690 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 nst sqlite3_valu
376a0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 e*);.SQLITE_API
376b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 int sqlite3_bind
376c0 5f 70 6f 69 6e 74 65 72 28 73 71 6c 69 74 65 33 _pointer(sqlite3
376d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 76 6f 69 _stmt*, int, voi
376e0 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c d*, const char*,
376f0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b void(*)(void*));
37700 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 .SQLITE_API int
37710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 sqlite3_bind_zer
37720 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 oblob(sqlite3_st
37730 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 mt*, int, int n)
37740 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 ;.SQLITE_API int
37750 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 sqlite3_bind_ze
37760 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 roblob64(sqlite3
37770 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c _stmt*, int, sql
37780 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f ite3_uint64);../
37790 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e *.** CAPI3REF: N
377a0 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 umber Of SQL Par
377b0 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f ameters.** METHO
377c0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a D: sqlite3_stmt.
377d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 **.** ^This rout
377e0 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 ine can be used
377f0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 to find the numb
37800 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d er of [SQL param
37810 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b eters].** in a [
37820 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
37830 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 nt]. SQL parame
37840 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 ters are tokens
37850 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 of the.** form "
37860 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 ?", "?NNN", ":AA
37870 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 A", "$AAA", or "
37880 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 @AAA" that serve
37890 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 as.** placehold
378a0 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 ers for values t
378b0 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 hat are [sqlite3
378c0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 _bind_blob | bou
378d0 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 nd].** to the pa
378e0 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 rameters at a la
378f0 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 ter time..**.**
37900 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 ^(This routine a
37910 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 ctually returns
37920 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 the index of the
37930 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d largest (rightm
37940 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 ost).** paramete
37950 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 r. For all forms
37960 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 except ?NNN, th
37970 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f is will correspo
37980 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d nd to the.** num
37990 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 ber of unique pa
379a0 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 rameters. If pa
379b0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 rameters of the
379c0 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 ?NNN form are us
379d0 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 ed,.** there may
379e0 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 be gaps in the
379f0 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 list.)^.**.** Se
37a00 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 e also: [sqlite3
37a10 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 _bind_blob|sqlit
37a20 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b e3_bind()],.** [
37a30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 sqlite3_bind_par
37a40 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 ameter_name()],
37a50 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f and.** [sqlite3_
37a60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 bind_parameter_i
37a70 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 ndex()]..*/.SQLI
37a80 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 TE_API int sqlit
37a90 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 e3_bind_paramete
37aa0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f r_count(sqlite3_
37ab0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 stmt*);../*.** C
37ac0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 API3REF: Name Of
37ad0 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 A Host Paramete
37ae0 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c r.** METHOD: sql
37af0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 ite3_stmt.**.**
37b00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e ^The sqlite3_bin
37b10 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
37b20 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 (P,N) interface
37b30 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e returns.** the n
37b40 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 ame of the N-th
37b50 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 [SQL parameter]
37b60 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 in the [prepared
37b70 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a statement] P..*
37b80 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 * ^(SQL paramete
37b90 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 rs of the form "
37ba0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 ?NNN" or ":AAA"
37bb0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 or "@AAA" or "$A
37bc0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 AA".** have a na
37bd0 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 me which is the
37be0 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 string "?NNN" or
37bf0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 ":AAA" or "@AAA
37c00 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 " or "$AAA".** r
37c10 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 espectively..**
37c20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 In other words,
37c30 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 the initial ":"
37c40 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 or "$" or "@" or
37c50 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 "?".** is inclu
37c60 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 ded as part of t
37c70 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 he name.)^.** ^P
37c80 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 arameters of the
37c90 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 form "?" withou
37ca0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e t a following in
37cb0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 teger have no na
37cc0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 me.** and are re
37cd0 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 ferred to as "na
37ce0 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e meless" or "anon
37cf0 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 ymous parameters
37d00 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 "..**.** ^The fi
37d10 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 rst host paramet
37d20 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 er has an index
37d30 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a of 1, not 0..**.
37d40 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 ** ^If the value
37d50 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e N is out of ran
37d60 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 ge or if the N-t
37d70 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a h parameter is.*
37d80 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e * nameless, then
37d90 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 NULL is returne
37da0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 d. ^The returne
37db0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 d string is.** a
37dc0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 lways in UTF-8 e
37dd0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 ncoding even if
37de0 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 the named parame
37df0 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 ter was.** origi
37e00 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 nally specified
37e10 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 as UTF-16 in [sq
37e20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 lite3_prepare16(
37e30 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f )],.** [sqlite3_
37e40 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2c prepare16_v2()],
37e50 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 or [sqlite3_pre
37e60 70 61 72 65 31 36 5f 76 33 28 29 5d 2e 0a 2a 2a pare16_v3()]..**
37e70 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 .** See also: [s
37e80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 qlite3_bind_blob
37e90 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d |sqlite3_bind()]
37ea0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 ,.** [sqlite3_bi
37eb0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 nd_parameter_cou
37ec0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 nt()], and.** [s
37ed0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 qlite3_bind_para
37ee0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a meter_index()]..
37ef0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f */.SQLITE_API co
37f00 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 nst char *sqlite
37f10 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 3_bind_parameter
37f20 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 _name(sqlite3_st
37f30 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a mt*, int);../*.*
37f40 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 * CAPI3REF: Inde
37f50 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 x Of A Parameter
37f60 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 With A Given Na
37f70 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 me.** METHOD: sq
37f80 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
37f90 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 ^Return the ind
37fa0 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 ex of an SQL par
37fb0 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 ameter given its
37fc0 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 name. ^The.**
37fd0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 index value retu
37fe0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 rned is suitable
37ff0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 for use as the
38000 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 second.** parame
38010 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f ter to [sqlite3_
38020 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 bind_blob|sqlite
38030 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 3_bind()]. ^A z
38040 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e ero.** is return
38050 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e ed if no matchin
38060 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 g parameter is f
38070 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 ound. ^The para
38080 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 meter.** name mu
38090 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 st be given in U
380a0 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 TF-8 even if the
380b0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d original statem
380c0 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 ent.** was prepa
380d0 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 red from UTF-16
380e0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 text using [sqli
380f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 te3_prepare16_v2
38100 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 ()] or.** [sqlit
38110 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 33 28 e3_prepare16_v3(
38120 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c )]..**.** See al
38130 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e so: [sqlite3_bin
38140 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 d_blob|sqlite3_b
38150 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 ind()],.** [sqli
38160 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 te3_bind_paramet
38170 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 er_count()], and
38180 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e .** [sqlite3_bin
38190 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 d_parameter_name
381a0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 ()]..*/.SQLITE_A
381b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 PI int sqlite3_b
381c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e ind_parameter_in
381d0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 dex(sqlite3_stmt
381e0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a *, const char *z
381f0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 Name);../*.** CA
38200 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c PI3REF: Reset Al
38210 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 l Bindings On A
38220 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 Prepared Stateme
38230 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 nt.** METHOD: sq
38240 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a lite3_stmt.**.**
38250 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 ^Contrary to th
38260 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d e intuition of m
38270 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 any, [sqlite3_re
38280 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 set()] does not
38290 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 reset.** the [sq
382a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 lite3_bind_blob
382b0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 | bindings] on a
382c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 [prepared state
382d0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 ment]..** ^Use t
382e0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 his routine to r
382f0 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 eset all host pa
38300 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c rameters to NULL
38310 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 ..*/.SQLITE_API
38320 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 int sqlite3_clea
38330 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 r_bindings(sqlit
38340 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a e3_stmt*);../*.*
38350 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 * CAPI3REF: Numb
38360 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e er Of Columns In
38370 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a A Result Set.**
38380 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 METHOD: sqlite3
38390 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 _stmt.**.** ^Ret
383a0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f urn the number o
383b0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 f columns in the
383c0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 result set retu
383d0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b rned by the.** [
383e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 prepared stateme
383f0 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72 6f nt]. ^If this ro
38400 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 2c utine returns 0,
38410 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 that means the
38420 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 .** [prepared st
38430 61 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e 73 atement] returns
38440 20 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65 78 no data (for ex
38450 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 ample an [UPDATE
38460 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72 2c ])..** ^However,
38470 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 74 68 just because th
38480 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 is routine retur
38490 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e 75 ns a positive nu
384a0 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a mber does not.**
384b0 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20 6f mean that one o
384c0 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20 64 r more rows of d
384d0 61 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74 75 ata will be retu
384e0 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43 54 rned. ^A SELECT
384f0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 69 statement.** wi
38500 6c 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20 61 ll always have a
38510 20 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74 65 positive sqlite
38520 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 3_column_count()
38530 20 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20 6f but depending o
38540 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20 63 n the.** WHERE c
38550 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 lause constraint
38560 73 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65 20 s and the table
38570 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67 68 content, it migh
38580 74 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77 73 t return no rows
38590 2e 0a